Daemon Lifecycle

The daemon is managed through the opta daemon subcommand. This page covers starting, stopping, monitoring, and installing the daemon as a system service.

Starting the Daemon

The opta daemon start command launches the daemon as a background process. It writes its PID, port, and authentication token to the state file at ~/.config/opta/daemon/state.json.

opta daemon start

Daemon started (pid 12345, port 9999)
Token written to ~/.config/opta/daemon/state.json

If the daemon is already running, the command will report the existing process and exit without starting a second instance.

Auto-start

When you run opta chat or opta do, the CLI will automatically start the daemon if it is not already running. You only need to run opta daemon start explicitly if you want to pre-warm the daemon before use.

Checking Status

The opta daemon status command shows the current state of the daemon process, including PID, port, uptime, and active session count.

opta daemon status

● running  pid=12345  port=9999  uptime=14m  sessions=2

If the daemon is not running, you will see:

opta daemon status

○ stopped  (no daemon process found)

Viewing Logs

The daemon writes structured logs to ~/.config/opta/daemon/daemon.log. Use the logs subcommand to tail the log file:

Tail the last 50 lines of daemon logs

opta daemon logs

[10:00:01] INFO  daemon started on 127.0.0.1:9999
[10:00:02] INFO  session created id=sess_abc123
[10:00:03] INFO  turn started session=sess_abc123 turn=1
[10:00:05] INFO  tool.start tool=file_read path=/src/index.ts
[10:00:05] INFO  tool.end tool=file_read duration=12ms

Show more log history

opta daemon logs --lines 200

Restarting

The opta daemon restart command performs a clean stop followed by a fresh start. On restart, a new authentication token is generated and written to the state file.

opta daemon restart

Stopping daemon (pid 12345)...
Daemon stopped.
Daemon started (pid 12350, port 9999)
Token rotated.

Token rotation

Restarting the daemon rotates the auth token. Any connected clients (Code Desktop, Local Web) will need to reconnect. The CLI reads the new token from the state file automatically.

Stopping

The opta daemon stop command sends a SIGTERM to the daemon process and waits for it to exit cleanly. Active sessions are preserved on disk and can be resumed after the daemon is restarted.

opta daemon stop

Stopping daemon (pid 12345)...
Daemon stopped.

Health Check

You can verify the daemon is responding to requests using the health endpoint:

curl http://127.0.0.1:9999/v3/health

{"status":"ok","version":"3.0.0","uptime":842}

GET/v3/health

Returns daemon health status, protocol version, and uptime in seconds. Does not require authentication.

Response

{
  "status": "ok",
  "version": "3.0.0",
  "uptime": 842
}

Auto-Start on Boot

The opta daemon install command registers the daemon as a system service so it starts automatically when you log in.

launchd (macOS)

On macOS, the install command creates a launchd plist at ~/Library/LaunchAgents/com.opta.daemon.plist.

opta daemon install

Installed launchd service: com.opta.daemon
Daemon will start automatically on login.

The generated plist configures the daemon to:

Start at login (RunAtLoad)
Restart on crash (KeepAlive)
Log stdout/stderr to ~/.config/opta/daemon/

~/Library/LaunchAgents/com.opta.daemon.plist

<?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.opta.daemon</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/opta</string>
    <string>daemon</string>
    <string>start</string>
    <string>--foreground</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
</dict>
</plist>

systemd (Linux)

On Linux, the install command creates a systemd user service at ~/.config/systemd/user/opta-daemon.service.

opta daemon install

Installed systemd user service: opta-daemon
Run: systemctl --user enable --now opta-daemon

Uninstalling

The opta daemon uninstall command removes the system service registration and stops the daemon if it is running.

opta daemon uninstall

Removed launchd service: com.opta.daemon
Daemon stopped.

Crash Recovery

If the daemon crashes unexpectedly, the CLI detects the stale state file on the next command and automatically restarts it. The crash guardian in ensureDaemonRunning performs the following steps:

Detect stale PID

The CLI reads state.json and checks whether the PID is still alive using a signal-zero check.

Clean up state file

If the PID is dead, the stale state.json is removed.

Restart daemon

A new daemon process is spawned with a fresh token and state file.

Retry the original command

The CLI retries connecting to the new daemon and proceeds with the user's command.

Session durability

Persisted session data is stored separately from the daemon process. Even after a crash, all previous sessions remain intact on disk and can be resumed.

Overview

HTTP API