exocomp knowledge base
exocomp knowledge base
exocomp is a homelab control plane: one Go binary (exocompd) — running as a systemd
host service or rootless container — that owns state, sequencing, keys, and recovery,
shelling out to pinned tools (ansible-core, opentofu, restic, sops, age, git) for
everything else.
Scale is one operator and a handful of hosts. Two constraints rule every decision here: trivial bootstrap and trivial disaster recovery.
1. User guide (front and center)
Task-oriented workflows and step-by-step guides for everyday homelab management — guide/index.md.
| Guide | Covers |
|---|---|
| Quickstart | 15-minute quickstart: Quadlet deployment, first-run wizard, and printing the recovery card |
| Sources and inventory | Registering Git repositories, local directories, SSH fleet keys, and auto-onboarding hosts |
| Ansible automation | Running playbooks, ad-hoc execution, --privileged API egress, and --check config drift |
| OpenTofu infrastructure | Workspaces, native SQLite HTTP state backend, plan diffs, CEL policies, and sealed outputs |
| Provision-to-converge handoffs | Chaining OpenTofu apply to Ansible playbook execution in a single atomic ledger workflow |
| Secrets and fleet keys | Age envelope encryption, SOPS integration, run-secret bindings, and zero secret leakage |
| Health checks and probes | Reachability matrix, CIDR network groups, probe targets, and check-triggered runs |
| Reactive automation | Webhooks, CEL event rule routing, push alerts, silence windows, and phone approvals |
| Mobile companion (in development) | Pairing phone via QR code, ntfy push notifications, and one-thumb approval decisions |
| AI agent integration | Model Context Protocol (POST /mcp) setup with scoped bearer tokens for Claude Code / Cursor |
2. Design and visual showcase (front and center)
Interface design as a functional contract — design/index.md.
| Page | Covers |
|---|---|
| Visual showcase & gallery | Interface tour: High-resolution screenshots of Web Dashboard (dark & light), OpenTofu plan diffs, live log tails, checks matrix, and TUI |
| Design invariants | The five immutable design principles, color-plus-word rules, and UI vocabulary |
| Web design system | CSS tokens, typography scale, tabular number invariants, and WCAG AA contrast rules |
| Terminal UI (TUI) | Bubble Tea/Lip Gloss terminal surface, 80x24 layout, keymaps, and Row 24 powerline strip |
| Machine token specification | Full token catalog transcribed from internal/web/tokens.css for automated agents |
3. Contributor guide (front and center)
How work lands here and what gates it — contribution/index.md.
| Guide | Covers |
|---|---|
| Developer setup | Toolchain prerequisites (Go 1.23+, rootless Podman, nono sandbox) and git hooks activation |
| Developer workflow | Running exocompd in development mode, templ template generation, and local CLI testing |
| Testing and verification gates | make check fast loop, make check-race, mutation testing of safety guards, and Lima VM testbeds |
| Codebase architecture map | Package relationships, unidirectional store boundaries, the step ledger, and the nono execution driver |
| Worktree lanes & branch hygiene | Parallel work in .worktrees/, linear commit history on main, and commit message conventions |
| Schema migrations | Authoring forward-only SQLite migrations, PRAGMA user_version, and collision resolution |
4. Operations and cluster lifecycle
Day-2 production operations, node-zero deployment, disaster recovery drills, and cluster maintenance — operations/index.md.
| Runbook | Covers |
|---|---|
| Bootstrap and deployment | Container Quadlet deploy, node-zero self-management, and adoption runbooks |
| Running the daemon | exocomp serve flags, process lifecycle, signal handling, and single-instance locks |
| Planned reboot & drain mode | exocomp drain — cordoning the daemon, draining in-flight jobs, and reboot safety |
| Upgrade and rollback | Zero-sudo upgrade choreography: mandatory pre-upgrade snapshots, binary swap, rollback |
| Containers and derived images | Shipped OCI image, offline builds, and derived FROM exocomp custom containers |
| Disaster recovery | The 3 backup legs (NAS/S3/Git), recovery kit, and restoring onto a dead host |
| Cold-standby failover | Replicated store takeover, Litestream fast-forward, and split-brain active lease guards |
| Offline caches and vendoring | Vendoring Ansible collections and OpenTofu providers for airgapped operations |
5. Technical reference
Precise specifications and wire protocols — reference/index.md.
| Reference | Covers |
|---|---|
| Command line interface (CLI) | Syntax, commands, global flags, and JSON envelope output (--output json) |
| Configuration files | Formats and schemas for .exocomp/hooks.yml, Quadlet unit definitions, and policies |
| Exit codes and error taxonomy | Exit code mappings, error domains, and failure classifications |
REST API (/api/v1) |
Wire endpoints, authentication, idempotency headers, and HTTP status mappings |
| MCP tool catalog | Model Context Protocol tools, input schemas, and scope definitions |
6. Architecture & decision records
Foundational architectural design and immutable decisions — architecture/index.md & decisions/index.md.
- Architecture overview: Component map, the one-queue convergence property, state layout.
- Execution driver: Sandbox tiers (
disabled,enforcingwithnono,container). - Platform contract: Support tiers for systemd, Podman, and SELinux enforcing.
- Reactive layer: CEL evaluation, guardrails, and ledger ordering.
- Decision records 0001–0022: Foundational architecture decision records.
7. Security & SBOM
- Threat model: Assets, threat actors, attack surfaces, and accepted residuals.
- Bill of materials: Component pins, licenses, and memory/binary size budgets.
Conventions
- Every cross-reference in this bundle is a relative link.
- Decision records are appended and superseded, never rewritten to change meaning.
- Docs move with code: structural changes are recorded in log.md.