pi-daemon1.3

Reference

Quickstart

Prerequisites: a flake-based Home Manager configuration, and normal Pi logged in once, so ~/.pi/agent/auth.json (and any models.json or settings.json) exists. Pi Daemon sessions use the same models, logins and settings as TUI Pi.

1. Enable the service with a profile

Add Pi Daemon to the inputs of your Home Manager flake, import its module and declare at least one profile:

{
  imports = [ inputs.pi-daemon.homeManagerModules.default ];

  services.pi-daemon = {
    enable = true;
    profiles.personal = {
      cwdRoots = [ "~/src" ];                    # sessions may only run under these
      model = "anthropic/claude-sonnet-4-5";     # optional default
      thinking = "medium";                       # optional default
      mcpServers.notes = { command = "/path/to/notes-mcp"; args = [ "stdio" ]; };
    };
  };
}

home-manager switch installs the package and runs one per-user service, pi-daemon (com.pi-daemon on macOS), under systemd, launchd or supervisord, plus its watchdog pi-daemon-watchdog. It listens on 127.0.0.1:7463. Check it with:

pi-daemon status
systemctl --user status pi-daemon   # Linux

which exits 0 once the host is ready.

2. Find the bearer

On first launch the daemon creates its owner-private state directory and generates a random bearer at ~/.local/state/pi-daemon/api-token. Every client sends it as Authorization: Bearer <token>. Keep it out of shell history, logs and chat; point clients at the file instead of copying it. To supply your own (for example a sops-nix secret), set services.pi-daemon.api.tokenFile.

3. Connect a client

  • Culture: add a host with url: ws://127.0.0.1:7463/ahp and token_file pointing at the bearer; see Culture.
  • An editor: connect its ACP client to ws://127.0.0.1:7463/acp (or /acp/<profile>) with the bearer; see ACP.
  • A browser: open http://127.0.0.1:7463/web and log in with the bearer for a small session list, conversation view and composer.
  • A script or application: use AHP, or ChordClient from this package over /chord; see Applications.

pi-daemon sessions list prints the session catalog.

4. Run it directly instead

Without Home Manager, write a config file and run serve yourself:

# ~/.config/pi/daemon/test/config.yaml
profiles:
  personal:
    cwdRoots: [~/src]
pi-daemon serve --instance test --state-dir ~/.local/state/pi-daemon-test --api-port 7464
pi-daemon status --instance test --api-port 7464

See Operations for configuration, profiles, the service and self-update.