Configuration

Environment variable	Default	Description
BUDDIES_USER	OS username	Your display name in rooms
BUDDIES_AGENT	unknown-agent	Which agent you're using
BUDDIES_DATA_DIR	~/.local/share/buddies	Where local memories are stored
RUST_LOG	warn	Log level (logs go to stderr, never pollutes MCP stdio)
BUDDIES_TRANSPORT	stdio	Transport mode: stdio (default, for MCP clients that spawn the process) or http (standalone HTTP server)
BUDDIES_PORT	8080	HTTP listen port (only used when BUDDIES_TRANSPORT=http)
BUDDIES_HOST	127.0.0.1	HTTP bind address (only used when BUDDIES_TRANSPORT=http)
BUDDIES_HEARTBEAT_SECS	10	Presence announcement interval
BUDDIES_SUSPECT_SECS	30	Elapsed time before a peer becomes unreachable
BUDDIES_OFFLINE_SECS	90	Elapsed time before a peer becomes offline
BUDDIES_MCP_IDLE_SECS	300	HTTP session inactivity limit; expired clients must initialize again
BUDDIES_SIGNER	git	Signing identity source: git, none, gpg, ssh, generated
BUDDIES_GPG_KEY_ID	unset	GPG key ID when BUDDIES_SIGNER=gpg (or use BUDDIES_SIGNING_KEY)
BUDDIES_SSH_PRIVATE_KEY	unset	SSH private key path when BUDDIES_SIGNER=ssh
BUDDIES_SSH_PUBLIC_KEY	inferred	SSH public key value or path when BUDDIES_SIGNER=ssh
BUDDIES_SIGNING_KEY	unset	Generic fallback for BUDDIES_GPG_KEY_ID or BUDDIES_SSH_PRIVATE_KEY

Startup identity options

• Use existing git signing identity (default):
  • BUDDIES_SIGNER=git
  • Reads git config user.signingkey and git config gpg.format
• Provide explicit key at startup:
  • GPG: BUDDIES_SIGNER=gpg BUDDIES_GPG_KEY_ID=<key-id> buddies
  • SSH: BUDDIES_SIGNER=ssh BUDDIES_SSH_PRIVATE_KEY=~/.ssh/id_ed25519 buddies
• Generate identity on first start and reuse it:
  • BUDDIES_SIGNER=generated buddies
  • Generates identity_ed25519 in BUDDIES_DATA_DIR and uses it for signing

Resource limits and shutdown

Distributed searches accept at most 30 seconds; task delegation accepts 1–300 seconds. Long polling is capped at 30 seconds. Each outgoing request registry allows 128 concurrent requests, and merged searches retain at most 50 results. Cancellation and broadcast errors release request registrations immediately.

Database work runs outside the async runtime with four concurrent worker slots. Signing and verification use at most four child processes, with a 10-second queue/execution deadline; timed-out or cancelled commands are terminated. Configured signing failures are errors, never an automatic unsigned fallback.

SIGINT/SIGTERM stops HTTP admission, cancels MCP sessions and notifications, and allows up to five seconds for HTTP connections to finish before stopping watchers, room receivers, and the Iroh router. The stdio transport also cleans up on EOF.