Nix & Home Manager

Cacophony ships as a Nix flake with a Home Manager module for declarative per-user deployment.

Flake Outputs

Development

# Enter dev shell
nix develop

# Build
cargo build

# Run
cargo run -p caco -- version --json

# Or run directly via nix
nix run . -- version --json

The flake-distributed caco launcher is wrapped with the startup runtime tool PATH Caco needs, including tmux-cli, so direct nix run and profile-installed launches do not depend on a login-shell environment to find required startup helpers. Browser, image, YAML, and legacy network helpers such as playwright-cli, rembg, yq, and nettools remain available on demand through the default dev shell or explicit packages where exposed, but are not included in the mandatory launcher or service startup closure; cold optional dependency realization should not block daemon or persistent-agent startup. Source-sensitive helpers such as caco config sparse validate warn when the running binary commit differs from checkout HEAD, because Nix/profile installs can lag a just-edited source tree.

Home Manager Module

The Home Manager module provides declarative per-user bootstrap. It installs the binary, materializes config, exports environment variables, and optionally enables a native user-service backend that runs a foreground Cacophony lifecycle supervisor.

Minimal Configuration

{
  services.cacophony = {
    enable = true;
    package = inputs.cacophony.packages.${pkgs.system}.caco;
    nodeName = "localhost";
  };
}

Full Configuration

{
  services.cacophony = {
    enable = true;
    package = inputs.cacophony.packages.${pkgs.system}.caco;
    nodeName = "localhost";
    cacophonyDir = "${config.home.homeDirectory}/.cacophony";

    providers = {
      openai = {
        baseUrl = "https://api.openai.com/v1";
        apiKeyFile = config.sops.secrets.openai-api-key.path;
      };
      anthropic = {
        baseUrl = "https://api.anthropic.com";
        authTokenFile = config.sops.secrets.anthropic-auth-token.path;
      };
      pi.githubCopilot.authFile = "~/.pi/agent/auth.json";
    };

    configTemplateEnv = {
      CACOPHONY_OPENAI_API_KEY_FILE = config.sops.secrets.openai-api-key.path;
    };

    autoUp = true;                  # Enable the managed lifecycle supervisor
    downOnDisable = true;           # Run caco down when disabled
    restartOnConfigChange = false;  # Default: log config drift; operator runs caco restart explicitly
    # Trusted LAN/VPN or SSH tunnel only; do not expose PulseAudio TCP publicly.
    extraEnv = {
      PULSE_SERVER = "<trusted-audio-host>:4713";
    };
  };
}

Module Options

Behavior

When Enabled

1. Installs the caco binary
2. Writes a valid config.yaml to $CACOPHONY_DIR
3. Exports CACOPHONY_DIR and CACO_NODE into managed processes
4. If autoUp = true: installs a native user service (launchd or systemd) that runs caco supervise --interval 30 from the live caco binary, so supervision policy updates with caco itself.
   • What restarts: process and listener liveness are the hard signals. A slow or backpressured daemon API is reported as degraded rather than restarted, unless the daemon stays alive but unresponsive past warmup and a bounded grace period. A stopped TTS service alone never restarts the daemon.
   • Config changes are detected but don't restart services by default; run caco restart, or set restartOnConfigChange = true.
   • Planned restarts: restart sentinels (including the one the health watchdog writes before exiting) make a respawn read as maintenance, and are cleared once services converge. Refresh helpers that install a new caco run caco service start afterwards so the supervisor stays the owner.
   • Not loaded: if the service is installed but not loaded, caco service status --json reports health_state: "not_loaded" with repair_command: "caco service load", and caco ops check raises it as a safe action. On launchd, caco service load bootstraps without a needless kickstart -k.
   • Manual startup: use caco service disable rather than raw launchctl/systemctl, then caco up --skip-update if services should still run unsupervised.
5. Module-managed units load provider tokens from secret paths and export as environment variables
6. When providers.pi.githubCopilot.authFile is set, managed Pi agents can launch with provider: github-copilot and a separate model; Cacophony translates that to Pi's native --model github-copilot/<model> selector and copies the configured auth.json into .pi-agent/

When Disabled

• If downOnDisable = true: runs caco down
• Does not delete $CACOPHONY_DIR unless the user performs explicit cleanup

Service Managers

The native service manager keeps the foreground lifecycle loop alive; the loop itself remains the authority for daemon and sidecar lifecycle and does not supervise caco daemon directly.

• Wrapper: Home Manager units pass through a small secret-loading wrapper that resolves the live binary, then execs caco supervise, so updating caco updates the supervisor policy.
• PATH: Generated systemd user units and launchd plists also set an explicit service-manager PATH that starts with the selected caco launcher's directory, then common user and system tool roots. Managed child services launched by the lifecycle loop receive the same deterministic CACO_BIN, startup runtime PATH, and login identity variables (HOME, USER, and LOGNAME) with the external tools Cacophony shells out to, including git, tmux, tmux-cli, ssh, jq, paplay/parec, grep/sed, and core POSIX utilities, while still searching common user bin roots such as ~/.cargo/bin and ~/.nix-profile/bin, so standalone services do not depend on a login-shell environment after restart/update/manual lifecycle transitions and git/ssh subprocesses can resolve the running UID. Npm-backed browser helpers, image helpers, YAML convenience tools, and legacy network tools such as playwright-cli, rembg, yq, and nettools are intentionally on-demand rather than part of service startup. The flake-distributed caco package and app use the same wrapped startup PATH contract for direct launches.

Secrets Management