← Dashboard · Docs ·User Guide

Grove User Guide

Dashboard Overview

The Grove dashboard is a single-page app with tabs:

Tab	What it does
🏠 Home	Cell status, storage, network health, activity log
📁 Files	Browse your file tree, upload, organize — your content (like a drive)
📡 Feed	Files shared with you by friends — signal, not storage
💬 Chat	E2E encrypted messaging with peers
🤖 AI	GroveAI chat + search (visible only when AI is configured)
⚙️ Settings	Cell name, password, theme, relay, remote access, backup

> No separate Invites tab. Invite management lives inside the Home tab quick-actions menu (✉️ icon).

Files Tab

Your content. Think of it like Google Drive, but encrypted and peer-replicated.

Uploading Files

Drag and drop files onto the upload zone, or click to browse
Progress bar shows speed (MB/s) and ETA
Generic filenames from mobile (image.jpg, photo.jpg) auto-timestamped
Files are automatically encrypted, chunked, and synced to peers

View Modes

📋 List view — traditional file list with details
🖼️ Gallery view — image grid with thumbnails (click toggle in header)
Sort: A-Z, Size, or Date buttons — click again to toggle asc/desc

File Type Icons

Files show type-specific icons: 🖼️ image, 🎬 video, 🎵 audio, 📝 text, 📕 PDF, 📦 archive, 📃 document, 📊 spreadsheet, 📽️ presentation, ⚙️ executable

File Actions (⋯ menu)

For files in Grove (local + backed up):

✏️ Rename — rename the file in place
⬇ Download — download file to your device (works from phone too)
🔗 Share — share with friend cells
🌐 Show in Portal — toggle file visibility on your linked remote portal (owner only)
🗑️ Remove Locally — delete local copy (stays backed up on peers)
🌲 Remove from Grove — remove from all peers (moves to Recycle Bin)

For Grove-only files (no local copy):

🔄 Restore — download back from peers

For local-only files:

🌲 Back up to Grove — encrypt and sync to peers

Rename and Move

Rename: ✏️ Rename in the ⋯ menu — edits in place
Move: Select files with checkboxes → Move batch button → pick destination folder

Folders

👁️ Watch — auto-backup new or modified files in this folder (two options: Watch Only, or Watch + Back Up)
🔗 Auto-Share — auto-share new files added to this folder with a friend cell
📡 Serve as Site — publish folder as a web site with audience control (see Renderers below)
Click a folder to browse into it
Batch operations: select multiple files/folders with checkboxes

Renderers (Folder-Level)

When you're inside a folder, you can optionally assign it a role:

📡 Site — serves as a web page at /site// with configurable audience (see Sharing)
Photo and markdown folders get suggestions to serve as a gallery or reader
🎵 Music and 🎬 Video — a folder full of audio or video files renders as a library + player

A folder auto-switches to a media role when it holds at least 3 files of that type and they make up at least half its contents. You can also set it by hand: inside the folder, click 🎵 show as music or 🎬 show as video (shown once there are 3+ matching files), and show as files to revert. The role sticks.

Music & Video Folders

A media folder looks like a music app's library: a track list with a player. Track titles come from the filename (a leading track number like 03 - is stripped), so name your files how you want them to read — there's no tag reading yet. Sub-folders become a nested tree, so an Artist/Album or Show/Season layout just works.

The player is a compact sticky bar at the bottom:

Play/pause, previous/next, and a seek scrubber
🔀 Shuffle and the now-playing title
Auto-advances to the next track when one finishes
Lossless audio (FLAC, WAV, ALAC, AIFF) shows a lossless badge
One player handles both music and video. For video, tap ⛶ to watch the picture full-screen — the bar itself stays compact

Big files start instantly and seek anywhere without downloading the whole thing first. Formats your browser can't play in-page (MKV, AVI, some MOV/HEVC) show a Can't play this format here · Download link instead of failing silently; MP4, WebM, M4V, OGV and common audio play inline. This works the same on the portal — friends and family see music and video folders in their Files view, no separate tab.

Recycle Bin

Deleted Grove files go to the Recycle Bin for 24 hours before permanent removal. A banner appears at the top of the Files tab when items are pending.

View bin ↓ — scroll to the Recycle Bin section
Restore — recover a deleted file before the timer expires
Empty Recycle Bin — permanently delete all items immediately

Feed Tab

Files shared with you by friends, plus your outgoing shares. This is signal — not a place to store things.

Views

🖼️ Gallery — photo grid (default), great for shared images
📋 List — detailed list with action buttons

File Actions

Incoming shares (Shared With Me): 🌲 Add to Grove — decrypts file, saves to GroveHome, ingests as your own, syncs to your peers
Outgoing shares (My Shares): 📂 View in Files — jumps to the file's directory in the Files tab
🗑 Dismiss — remove from feed (doesn't affect the file or the share)
🚫 Unshare — revoke sharing (outgoing only)

File States

Available — chunks present, ready to view
🔏 Verified — cryptographic signature verified
Unavailable — chunks not yet on your cell

Lightbox

Click any image to view full-size. Background scroll is locked. Navigate with:

◀ ▶ buttons or arrow keys
Escape to close
Click outside image to close
⬇ Download (Files tab) or 🌲 Add to Grove (Feed tab incoming)

Sharing Files

How to Share

1. Go to Files tab

2. Click ⋯ on a file or folder → 🔗 Share

3. Search for and select the friend cell to share with

4. For folders: optionally enable 📂 Auto-share new files added to this folder

5. Click Share

What Happens

A signed grant is created for the recipient (envelope-encrypted with X25519 — only they can decrypt)
Grant is pushed to their cell immediately
File appears in their Feed tab

Unsharing

Click ⋯ → 🚫 Unshare
Select which peers to revoke
Their grant is deleted; they lose access

See SHARING.md for full details on grants, folder sharing, Show in Portal, and audience tiers.

Chat

End-to-end encrypted messaging between peers.

X25519 key exchange — each message encrypted with recipient's public key
ChaCha20-Poly1305 — message encryption
Messages stored locally on each cell (not on relay)
Relay carries encrypted messages but can't read them
Chat input is a multi-line textarea: Enter sends, Shift+Enter for newline

GroveAI Tab

Visible only when AI is configured on at least one cell in your grove.

💬 Chat mode — conversation thread; persists across sessions; supports multiple conversations
🔍 Search mode — one-shot question, clean single answer (no thread)
Tier selector — per-message quality control; options depend on what's in your grove:
Lower tiers = faster, cheaper, smaller models
Higher tiers = more capable models; routes to the best available peer
Auto — picks the cheapest model that can handle the question
🎨 Image Generation — available only on cells with the local Flux stack (currently Mac only); generates images from a text prompt; output lands in ~/GroveHome/Images/AI/ even if you close the tab

GroveAI routes to the best LLM in your grove automatically. If no local model is available, the tab may show as offline.

Cells / Peers

Managed from within the ⚙️ Settings tab under the 🔌 Cells section.

Cell Status

🟢 Green dot — online and reachable
🔴 Red dot — offline or unreachable
⭐ Star — favorite cell (always syncs first)

Cell Actions

👥 — Add/remove as friend (friends can share files)
⭐ — Toggle favorite
✏️ — Rename (edit display name)
✕ — Remove cell (choice: keep or delete their files)

Adding Cells

Invite link — create from the Home tab quick-actions (✉️), send to person
Manual — enter IP/hostname in Add Cell form
Discovery — auto-discover cells on local network (mDNS)
Recommendations — existing cells can recommend new ones

Storage

Two-Bar Display (Home tab)

💾 Disk — total disk usage (Grove + other files + free space)
🌲 Grove Storage — breakdown of Grove data:
Your files — files you own, stored locally + on peers
Backed up only — your files only on peers (removed locally)
Shared — files shared with you by peers
Helping peers — encrypted chunks you're storing for others

Backup Health

Shows how many copies of your chunks exist across the fleet:

🟢 Green — at or above desired replication factor
🟡 Yellow — below desired but above minimum
🔴 Red — at risk (single copy only)

Replication Factor

Default: 2 (your cell + 1 peer). Change in Settings → My Cell.

Higher = safer but uses more storage across the fleet
Opp sync automatically maintains the target

Network Health

Sync status — banner shows when background sync is active
Cells list — all connected cells with status, speed, and actions (Settings → Cells)
Activity log — recent events (uploads, syncs, shares, errors) on Home tab
Route benchmark — runs every 6 hours, measures actual throughput

Settings

The ⚙️ Settings tab has two collapsible sections:

🔬 My Cell

Cell name — how other cells see you
Password — change dashboard password
Appearance — Grove Theme (5 named themes: Honey Hearth, Mossbank, Cherry Blossom, Twilight Plum, Midnight Garden) + light/dark toggle
🔑 Identity Backup — download/restore your Ed25519 keys (keep these safe)
🔑 Recovery — generate a one-use password reset link (valid 24h)
⚙️ Advanced Settings (collapsed):
🌍 Remote Access — link this cell to a WAN gateway portal so you can reach it from the web without Tailscale; use "🌐 Show in Portal" on files to expose them there
Portal Host — enable this cell to host portal accounts for others
🔗 Relay — configure relay server, relay hosting, and relay preferences

🔌 Cells

Full peer/cell roster
Friend toggles, favorites, rename, remove

Keyboard Shortcuts

Key	Action
Escape	Close lightbox/modal
← →	Navigate gallery lightbox
Enter	Send chat message
Shift+Enter	New line in chat

Tips

First time? A tutorial appears on first load — follow the tips!
Slow uploads? Check your replication factor (lower = fewer copies to push)
File missing? Check "Grove Only" files in Files view — it may need a Restore
Peer offline? Chunks auto-heal to other peers after ~5 minutes
Want privacy? All chunks are encrypted. Even your peers can't read your files.
Deleted by accident? Check the Recycle Bin — you have 24 hours to restore
Access from anywhere? Set up Remote Access in Settings → Advanced to reach your files without Tailscale