choird

The Choir control plane daemon. Runs on the host, manages agent containers, enforces policy, and owns all durable state.

Responsibilities

• Telegram gateway (multi-bot, multi-DM routing, admin/regular permissions)
• Container lifecycle (Docker create/start/stop/remove)
• Resource leasing (workspaces, git identities, DMs — exclusive access)
• RPC server (UDS + HTTP transport for choir-agent communication)
• Session management and crash recovery
• Heartbeat monitoring and crash detection
• Memory module (Postgres + pgvector: chunking, embedding, tier promotion)
• Approval pipeline (proposals, inline keyboard UX, timeout)
• Secret management (secrets.json authority + explicit apply to running agents)
• Config management (two-phase load/apply, hot-reload)
• Agent image build pipeline (git clone, artifact merge, Docker build)
• Structured logging with archiving

Startup Sequence

1. Read and validate ~/.choir.d/config.json
2. Read and validate ~/.choir.d/secrets.json
3. Connect to Postgres using credentials resolved from configured secret references
4. Verify pgvector is installed in the target database, then initialize per-agent schemas if needed
5. Initialize connection pool
6. Detect and remove orphaned containers (choir.managed=true label)
7. Clean up stale leases (crashed sessions)
8. Start gateway bot instances
9. Start RPC transport server
10. Accept choirctl and gateway commands
11. Log ready with config version summary

Usage

choird [flags]

Flags:
  --config string      Path to config directory (default ~/.choir.d)
  --transport string   Transport mode: uds, http, both (default uds)
  --listen string      HTTP listen address (default :9400)
  --tls-cert string    TLS certificate file (HTTP mode)
  --tls-key string     TLS key file (HTTP mode)