Daemon Lifecycle

Manage the daemon through opta daemon. This guide covers lifecycle control, health instrumentation, and platform-native service registration for resilient startup behavior.

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 daemon state file under the Opta config root (macOS/Linux: ~/.config/opta/daemon/state.json, Windows: %APPDATA%\\opta\\daemon\\state.json).

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.

Checking Status

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

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

If the daemon is not running, you will see:

○ stopped  (no daemon process found)

Viewing Logs

The daemon writes structured logs to the daemon log path (~/.config/opta/daemon/daemon.log on macOS/Linux and %APPDATA%\\opta\\daemon\\daemon.log on Windows). Use the logs subcommand to tail the file:

[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

Restarting

The daemon CLI currently exposes explicit stop and startcommands. For a clean restart, run stop then start.

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

Stopping

opta daemon stop sends a graceful shutdown signal, waits for clean termination, and force-stops only when necessary. Active sessions remain preserved on disk and can be resumed after restart.

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

Health Check

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

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

{
  "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.

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/

<?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>run</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.

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

schtasks (Windows)

On Windows, the install command registers a Scheduled Task that launches the daemon at user logon.

Installed Windows scheduled task: OptaDaemon
Daemon will start automatically at user logon.

Uninstalling

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

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: