Quickstart

One machine, one project, one agent, in about five minutes.

Prerequisites

• Nix with flakes, or a Rust toolchain (1.91+)
• Git and SQLite
• Herdr or tmux to host agent terminals (Herdr is the default; set agents.runtime.multiplexer: tmux to use tmux)
• At least one agent runtime you have signed in to: Claude Code, Codex or Pi

The fast path

caco bootstrap dev --check says what is missing. On a fresh machine it looks like this:

caco bootstrap dev --check
  [PASS] Rust toolchain (cargo)           cargo 1.97.0
  [PASS] tmux                             tmux 3.7c
  [PASS] sqlite3                          3.53.3
  [PASS] git                              git version 2.55.0
  [FAIL] caco config.yaml                 missing: ~/.cacophony/config.yaml
  [SKIP] caco-daemon HTTP                 daemon URL unresolved: no config file found
  [PASS] claude-code CLI (optional)       2.1.296 (Claude Code)

Bare caco bootstrap dev then does the rest: it writes a starter config, starts the daemon, creates a sandbox project and files a demo bead. The steps below do the same by hand.

Step by step

1. Install

   # a prebuilt release: Linux x86_64 or aarch64, macOS arm64
   curl -fsSLO "https://a.skh.am/cacophony/install.sh"
   less install.sh
   CACO_INSTALL_REPO="harryaskham/cacophony" bash install.sh
   
   # or with Nix
   nix build github:harryaskham/cacophony
   ./result/bin/caco version --json
   
   # or from a checkout
   cargo install --path crates/caco --locked

   The installer puts caco in ~/.cargo/bin and refuses a binary that does not match the release's .sha256 sidecar; --version v1.2.3 pins one. Release downloads need read access to the release repository. Later, caco update status and caco update --stable-only keep it current.

2. Write a config

   CACOPHONY_DIR="${CACOPHONY_DIR:-$HOME/.cacophony}"
   mkdir -p "$CACOPHONY_DIR"
   test ! -e "$CACOPHONY_DIR/config.yaml" || { echo "config already exists"; exit 1; }
   caco config generate > "$CACOPHONY_DIR/config.yaml"

   A valid single-node config with localhost as the node. Add your projects under projects:; the configuration reference has every field.

3. Create the certificate authority

   caco cert init                     # the cluster CA, never overwritten
   caco cert issue --node localhost   # this node's certificate

   Daemons talk to each other over mutual TLS, even on one machine. A second machine joins this CA rather than making its own. PKI & certificates

4. Validate and start

   caco config validate
   caco up
   caco status --json

   validate checks the schema, names, ports, TLS files and cross-references. caco up starts the daemon, the beads service and sidecars, plus any always-on agents; caco down stops them again.

5. File your first bead

   caco bd create --title "Hello Cacophony" --type task --priority 2
   created: bd-a0000a — Hello Cacophony
   caco bd list --ready

6. Start an agent

   # claim the bead and start a worker for it
   caco bd dispatch --bead-id bd-a0000a --profile dev
   caco agent list
   caco agent attach --id AGENT_ID

   Or skip the bead: caco agent new --project scratch --type claude --profile dev --goal "Tidy the README".

7. Land the work

   caco agent complete --id AGENT_ID --dry-run   # the steps it would take
   caco agent complete --id AGENT_ID

   Squash-merge or a pull request that auto-merges behind CI, as the profile and project decide. Reintegration

8. Watch everything

   caco tui       # the operations console
   caco chat      # straight to chat
   caco inbox     # straight to the inbox
   caco choices   # questions waiting for you

   The web dashboard and the phone and watch apps show the same fleet.

Next

Recipes walk through real tasks with real output: planning a feature as a graph, proving a change, answering decisions, adding a machine and running a flow. Architecture shows how the pieces fit.