A single Grove node — one device running grove.py and web.py. Every cell has its own identity (keypair), storage, and dashboard. Your laptop, a Raspberry Pi, a VPS — each is a cell.
All the cells you're connected to. Your personal distributed network.
Another cell in your fleet. Peers sync files, relay messages, and back each other up.
A peer you've promoted to friend status. Friends can share files with you (via grants). Non-friend peers can still store your encrypted chunks but can't share files with you.
A peer marked as a preferred sync target. Your chunks will always be synced to favorite peers first, regardless of speed ranking.
A 4MB piece of a file, encrypted with ChaCha20-Poly1305. Files are split into chunks for storage and transfer. Chunk filenames are their SHA-256 hash (content-addressed).
A JSON file describing a complete file: its name, size, chunk hashes, encryption metadata, and source path. Format: {filename}.{hash8}.json. Manifests live in ~/.grove/manifests/.
A cryptographic permission to access a shared file. When you share a file with a peer, you create a signed grant containing the manifest hash, the encrypted file key, and your signature. Grants are verified using Ed25519 signatures.
The system's record of which chunks live on which peers. Used to decide where to replicate, what's under-replicated, and what's at risk. Stored in ~/.grove/placement.db (SQLite).
How many copies of each chunk exist across the fleet. Default desired factor: 2 (your cell + one peer). Configurable per-cell.
A WebSocket server that lets cells communicate when they can't reach each other directly (e.g., behind NAT). Cells connect to a relay and exchange messages through it. Relay operators can't read message contents (end-to-end encrypted).
How two cells communicate. Types:
100.x.x.x)200: / 201: / 202: addresses)192.168.x.x)A token-like credit system for resource sharing. Peers earn bounty by storing chunks for others. Spend bounty to store your data on peers. Currently tracks storage contributions.
Built-in AI chat powered by local LLM inference (llama.cpp or Ollama). Can also route queries to peer cells with more powerful hardware.
Background process that runs every ~5 minutes. Probes all peers, checks for missing chunks, pulls/pushes data to maintain replication targets, records speed measurements, and runs health checks.
1. Upload → File saved to GROVE_HOME (your file tree)
2. Chunk → Split into 4MB chunks, encrypted with ChaCha20
3. Manifest → JSON manifest created describing the file
4. Local storage → Chunks stored in ~/.grove/chunks/{hash[:2]}/{hash}
5. Sync → Opp sync pushes chunks to peers (speed-ranked)
6. Placement → Placement DB tracks which peers hold which chunks
7. Healing → If a peer goes offline, chunks re-replicate elsewhere
1. Select file → Choose file(s) in dashboard
2. Pick peers → Select which friends to share with
3. Create grant → Signed grant with encrypted file key
4. Push grant → Grant sent to peer's cell
5. Peer sees file → Appears in their Feed tab
6. Peer downloads → Chunks pulled from your cell (or other holders)
~/.grove/ # Runtime directory (GROVE_DIR)
├── config.json # Cell configuration
├── node.key # Ed25519 private signing key
├── node.pub # Ed25519 public key
├── node_x25519.key # X25519 private key (for chat encryption)
├── node_x25519.pub # X25519 public key
├── .key # Master encryption key (256-bit)
├── peer_secret # Shared secret for peer API auth
├── dashboard_auth # Dashboard password hash
├── placement.db # SQLite: chunk placement tracking
├── peer_speeds.json # Recorded route speeds
├── peer_health.json # Peer uptime tracking
├── chunks/ # Encrypted chunk storage
│ ├── ab/ # First 2 hex chars of hash
│ │ └── ab3f7c... # Full hash filename
│ └── ...
├── manifests/ # File manifests
│ └── photo.jpg.a1b2c3d4.json
├── grants/ # Received share grants
├── invites/ # Created invite tokens
├── models/ # AI model files (.gguf)
├── grove.py # Core library
└── web.py # Web dashboard + API server
~/GroveHome/ # User file tree (GROVE_HOME)
├── Documents/
├── Photos/
└── ... # Your actual files
┌──────────┐
│ Relay │ (WebSocket hub, optional)
└────┬─────┘
│
┌─────────┼─────────┐
│ │ │
┌───┴──┐ ┌───┴──┐ ┌───┴──┐
│ Cell │ │ Cell │ │ Cell │
│ (Mac)│ │ (Pi) │ │ (VPS)│
└──────┘ └──────┘ └──────┘
↕ ↕ ↕
Tailscale / Yggdrasil / LAN / WAN
Cells find the best route to each peer automatically. Routes are benchmarked every 6 hours and scored by throughput + latency.