setup

kasmos ships service unit templates in contrib/ and a set of just recipes for managing them. the justfile recipes auto-detect whether you are on linux (systemd) or macos (launchd) and apply the right tooling automatically. this page covers both.

prerequisites

• kas binary installed and on $PATH (via just install or go install github.com/kastheco/kasmos/cmd/kas@latest)
• linux only — systemd user session available (loginctl enable-linger on headless servers)
• macOS only — no extra setup needed; launchd is always available

just recipes

all daemon management is available through the justfile at the repo root. the recipes detect $(uname -s) at runtime so the same commands work on both platforms.

install and enable

# install the orchestration daemon and enable it now
just kasmosd-enable

# install the plan store service and enable it now
just db-service-enable

# enable both services in one step
just services-enable

kasmosd-enable runs in three stages:

1. calls just install — builds and installs the kas binary, creates the optional kms alias.
2. installs the service definition for the current platform:
   • linux — resolves the kas binary via command -v kas, renders contrib/kasmos.service by substituting __KAS_BIN__ with the absolute path, writes the result to ~/.config/systemd/user/kasmos.service, and reloads the daemon.
   • macOS — renders contrib/com.kasmos.daemon.plist with the current $HOME and binary path, copies it to ~/Library/LaunchAgents/, and loads it with launchctl.
3. enables and starts the service.

db-service-enable does the same for the task-store service (kas serve), which exposes the task-store rest api and admin ui on port 7433 (configurable with --port) plus the shared mcp endpoint on port 7434 by default.

direct daemon start/stop

# start the daemon in the foreground (useful for debugging)
just kasmosd-start    # runs: kas daemon start

# stop the daemon by pid
just kasmosd-stop     # runs: kas daemon stop

# check daemon status
just kasmosd-status   # runs: kas daemon status

diagnose installation

just doctord

doctord prints a structured report:

• whether the kas binary is on $PATH
• install and active state of both services
• whether the daemon socket is present at the expected path
• a "next steps" block listing the relevant just recipes

service units

linux — systemd

contrib/kasmos.service is a template. __KAS_BIN__ is replaced with the absolute binary path during just kasmosd-install. the installed unit looks like:

[Unit]
Description=kasmos orchestration daemon
Documentation=https://github.com/kastheco/kasmos
After=network.target

[Service]
Type=simple
ExecStart=/home/you/go/bin/kas daemon start --foreground
ExecStop=/home/you/go/bin/kas daemon stop
Restart=on-failure
RestartSec=5
Environment=HOME=%h
StandardOutput=journal
StandardError=journal
SyslogIdentifier=kasmos

[Install]
WantedBy=default.target

logs go to the journal:

journalctl --user -u kasmos -f

contrib/kasmosdb.service follows the same template pattern for kas serve.

macos — launchd

contrib/com.kasmos.daemon.plist (rendered by just kasmosd-enable with the active $HOME):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.kasmos.daemon</string>
  <key>ProgramArguments</key>
  <array>
    <string>/Users/you/go/bin/kas</string>
    <string>daemon</string>
    <string>start</string>
    <string>--foreground</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/Users/you/Library/Logs/kasmos/daemon.log</string>
  <key>StandardErrorPath</key>
  <string>/Users/you/Library/Logs/kasmos/daemon.err.log</string>
</dict>
</plist>

logs are written to ~/Library/Logs/kasmos/daemon.log:

tail -f ~/Library/Logs/kasmos/daemon.log

manage the service manually:

# load and start
launchctl load ~/Library/LaunchAgents/com.kasmos.daemon.plist

# stop and unload
launchctl unload ~/Library/LaunchAgents/com.kasmos.daemon.plist

# check status
launchctl list | grep kasmos

daemon config file

the daemon reads ~/.config/kasmos/daemon.toml on startup. create it manually or let the daemon create an empty one on first run. see the cli reference for the full field list.

minimal example to auto-watch two repos and enable pr monitoring:

repos = ["/home/user/project-a", "/home/user/project-b"]
auto_advance_waves = true
auto_review_fix = true
max_review_fix_cycles = 3

[pr_monitor]
enabled = true
poll_interval_sec = 60.0
reactions = ["eyes"]

verifying the daemon is running

# check socket presence (fastest check)
kas daemon status

# view live logs — linux
journalctl --user -u kasmos -f

# view live logs — macOS
tail -f ~/Library/Logs/kasmos/daemon.log

# run the diagnostic script
just doctord

the socket lives at:

• $XDG_RUNTIME_DIR/kasmos/kas.sock (when XDG_RUNTIME_DIR is set — typical on systemd desktop sessions)
• os.TempDir()/kasmos-<uid>/kas.sock (fallback; on macOS this is typically $TMPDIR, e.g. /var/folders/.../kasmos-<uid>/kas.sock, not /tmp)

manual foreground run

useful when iterating on daemon config or debugging signal flow:

kas daemon start --foreground --config /tmp/test-daemon.toml

ctrl-c sends SIGTERM and triggers the 35-second graceful drain.