kas daemon

Manage the kasmos multi-repo background orchestration daemon. The daemon watches registered repositories for agent lifecycle signals and drives FSM transitions automatically.

kas daemon <subcommand> [flags]

Alias: kas d

persistent flags

flag	default	description
--socket	see below	path to the daemon unix domain socket

Default socket path — the daemon uses a Unix domain socket whose location is determined at startup:

1. $XDG_RUNTIME_DIR/kasmos/kas.sock (preferred, when $XDG_RUNTIME_DIR is set)
2. /tmp/kasmos-<uid>/kas.sock (fallback)

The kas daemon status, add, and remove subcommands connect to this socket to communicate with the running daemon.

subcommands

start

Start the kasmos daemon.

Note for persistent installs: long-running user installations should manage the daemon via the systemd user service (systemctl --user start kasmos) rather than this command. kas daemon start and kas daemon stop are primarily intended for foreground use, debugging, and CI environments where a service manager is not available.

kas daemon start [--foreground] [--config <path>]

# daemonize (default) — forks, detaches, writes PID to ~/.config/kasmos/daemon.pid
kas daemon start

# foreground mode — useful for systemd or direct supervision
kas daemon start --foreground

# use a custom config file
kas daemon start --foreground --config /etc/kasmos/daemon.toml

flag	description
--foreground	run in foreground instead of daemonizing (suitable for systemd Type=simple)
--config	path to daemon TOML config file (default: ~/.config/kasmos/daemon.toml)

When daemonizing, the PID is written to ~/.config/kasmos/daemon.pid.

---

stop

Stop the running daemon by sending SIGTERM to the PID recorded in ~/.config/kasmos/daemon.pid.

kas daemon stop

---

status

Show the current daemon status: registered repos, active plans per repo.

kas daemon status [--socket <path>]

kas daemon status

Connects to the daemon control socket and calls GET /v1/status. Prints daemon not running if the socket is unreachable.

The daemon also serves instance metadata to the tui and live-preview bridge on GET /v1/repos/{project}/instances. Daemon-spawned rows include execution_mode, sdk_speed_tier, skip_permissions, and resource_profile so clients can resume or display sdk/tmux sessions using the same resolved profile defaults and resource-control profile the daemon used when spawning them. resource_profile is omitted for the normal/no-op resource profile. Older daemons omit skip_permissions; newer clients treat that omission as the legacy daemon default (true, bypass permissions).

Live instance text is available on GET /v1/repos/{project}/instances/{title}/capture. Optional start and end query parameters use tmux -S/-E line-range semantics. For SDK instances, both full and ranged captures are rendered with the repo's resolved theme palette, so daemon-managed repos with custom .kasmos/config.toml palettes match the tui and live-preview output.

The control API event stream is available at GET /v1/events and is consumed by kas monitor. Event JSON uses Go time encoding, so timestamp values may include fractional seconds. Event payloads can also include structured detail data for wave and agent outcomes; JSON consumers should preserve that field instead of parsing only the human message.

---

add

Register a repository with the running daemon so it is included in signal scans.

kas daemon add <repo-path> [--socket <path>]

kas daemon add /home/user/myproject

Sends POST /v1/repos with the resolved absolute path. Returns an error if the daemon is not running.

---

remove

Unregister a repository from the running daemon.

kas daemon remove <repo-path> [--socket <path>]

kas daemon remove /home/user/myproject

Derives the project name from the basename of the path and sends DELETE /v1/repos/<project>.

---

reload

Reload the daemon configuration by sending SIGHUP to the daemon process.

kas daemon reload

Reads the PID from ~/.config/kasmos/daemon.pid and sends SIGHUP.

configuration file

The daemon reads ~/.config/kasmos/daemon.toml on startup. All fields are optional — missing keys use the defaults shown below.

# how often the daemon scans for signals (seconds)
poll_interval_sec = 2.0

# repositories to manage on daemon startup
repos = ["/home/user/project-a", "/home/user/project-b"]

# automatically transition planning→ready after planner_finished signal
auto_advance = false

# automatically advance between waves when all tasks in a wave complete
auto_advance_waves = true

# automatically start a fixer after review_changes_requested
auto_review_fix = true

# master agent readiness gate after reviewer approval (enabled by default)
auto_readiness_review = true

# maximum review-fix loop iterations (0 = unlimited)
max_review_fix_cycles = 0

# master agent self-fix ceiling: net lines that may be changed in one attempt (default 80)
readiness_self_fix_max_lines = 80

# verify-round cap: force-promote verify_failed to verify_approved after this many attempts (default 2)
# project-local config.toml overrides this value per-repo
readiness_max_verify_cycles = 2

# unix socket path (overrides XDG_RUNTIME_DIR-based default)
socket_path = ""

[pr_monitor]
# enable GitHub PR polling
enabled = false
# how often to poll open PRs (seconds)
poll_interval_sec = 60.0
# GitHub reactions to add to unprocessed review comments
reactions = ["eyes"]

systemd service example

[Unit]
Description=kasmos daemon
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/kasmos daemon start --foreground
Restart=on-failure

[Install]
WantedBy=default.target