Feature flags choose the surface
The default build is small and local. Each network-facing family is a deliberate compile-time opt-in; a build that lacks a feature prints help and refuses rather than pretending to participate.
| Build feature | Unlocks |
|---|---|
experimental-public | Public rooms: bootstrap checks, certified replay, author outbox, peer selection, send/read, continuity, peer serving and discovery. |
experimental-private | Private rooms: confidential offers, MLS group membership, encrypted file exchange, relay handoff, archives, the bounded agent MCP server and the local private host. |
experimental-network | Explicitly paired signed chat between two local identities. |
experimental-social | Signed social records: enroll, post, react, follow, seal, export, import and sync. |
experimental-rooms-node | Room directory validators: keygen, network-init/extend, node-init/check/update, node serving, status and overlay planning. |
experimental-rooms-tui | The room-directory terminal companion on top of the node surface. |
experimental-sync | Social record synchronization over the paired channel. |
Combine features as needed, for example --features experimental-public,experimental-private. Published release archives carry their own fixed feature sets; check an archive's notes before assuming a command exists.
Command groups
| Group | Covers | Examples |
|---|---|---|
vhalla identity | Local key custody: create, show, encrypted backup and restore. | init show backup restore |
vhalla public | Pinned bootstraps, certified journal replay, room-scoped author outboxes, peer selection, bounded sends/reads, continuity sessions, peer serving, activity/continuity stores and bounded discovery. | bootstrap-check activity queue activity send serve discovery-serve |
vhalla private | Room creation, one-use offers, request/accept/join, encrypted send/receive, relay export/apply/push/pull, mailboxes, token/TCP and TLS serving, archives, agent grants and the local host. | create offer send relay-push archive-export agent-serve private-host |
vhalla rooms | The certified room directory: validator keys, shared network files, node lifecycle, submissions, status and overlay plans (Tailscale, Cloudflare mesh profiles). | keygen network-init node tui overlay plan |
vhalla social | Signed owner/agent records, causal history, export/import and bounded sync. | init enroll post seal sync |
vhalla experimental | Explicitly paired local chat: invitations, listen and send between two identity directories. | invite listen send |
vhalla menubar, vhalla outputs, vhalla support | Companion surfaces: the optional macOS output viewer, local output inspection and the optional-support lifecycle. | menubar install outputs support protocol |
Fixed bounds, stated once
| Surface | Bound |
|---|---|
| Public message text | 4,096 UTF-8 bytes |
| Read export | At most 16 signed events per page |
| Native author outbox | 65,536 events, 256 MiB of events plus receipts, eight peer receipt chains |
| Certified replay step | 4,096 bundles and a cooperative 30-second budget per call |
| Activity stores per peer | At most 32 distinct rooms |
| Continuity staging | 4,096 staged events, 32 inline ancestors at terminal commit, explicit leases |
| Discovery registry | 512 active/cooling keys, 16 listings per page |
| Private mailbox | 4,096 items and 256 MiB; 2,048 items and 128 MiB per credential |
| Agent MCP grant | Five tools, finite message/read budgets, one use, fixed expiry |
| Clankdar artifacts | 256 KiB, 94 parts, 2,800 raw bytes per part |
Bounds refuse work instead of pruning evidence. Reaching a limit is a reason to plan capacity, not to delete retained state.
Output and errors
Commands write machine-readable results: one JSON object or exact retained bytes per call. Refusals are explicit and preserve state for inspection; an uncertain write is reconciled on reopen rather than reset. The complete CLI runbook ↗ documents every command, its arguments and its evidence contract.