- Add restart CLI command (stop + start in one step) - Disable tsup code splitting to prevent ERR_MODULE_NOT_FOUND when daemon is running during a global npm upgrade (hash-named chunks get replaced, breaking dynamic imports in the old process) - Update help, docs, and README Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
4.3 KiB
Daemon Mode
Foreground vs Daemon
OpenACP can run in two modes, controlled by the runMode config field.
Foreground (runMode: "foreground") — The process stays attached to your terminal. Log output is printed to stdout. The process exits when you close the terminal or press Ctrl+C. Use this during initial setup, debugging, or when you want to watch logs in real time.
Daemon (runMode: "daemon") — The process detaches from the terminal and runs in the background. Output is written to a log file. The process survives terminal closure. This is the recommended mode for production self-hosting.
Commands
All daemon commands use the openacp CLI:
openacp start # Start (foreground or daemon depending on runMode config)
openacp stop # Send SIGTERM to the daemon, wait up to 5 s, then SIGKILL
openacp status # Print running/stopped and PID if running
openacp logs # Tail the daemon log file
openacp restart # stop + start
openacp start
When runMode is daemon, this spawns a detached child process (--daemon-child flag) and returns immediately. The child writes its PID to the PID file and begins accepting messages.
When runMode is foreground, this runs the server in the current process.
openacp stop
Reads the PID file and sends SIGTERM. Polls every 100 ms for up to 5 seconds waiting for the process to exit. If the process does not exit within 5 seconds, SIGKILL is sent. The PID file is removed after a successful stop.
Calling stop also removes the running marker file (~/.openacp/running), which suppresses autostart on the next boot.
openacp restart
Equivalent to stop followed by start. If no daemon is running, it skips the stop step and starts a new one. Useful after updating OpenACP to pick up the new version without manually stopping first.
openacp status
Checks whether the PID in the PID file is alive (using kill -0). Cleans up stale PID files automatically.
openacp logs
Tails ~/.openacp/logs/openacp.log. In daemon mode this is where all server output goes.
File Locations
| File | Path | Purpose |
|---|---|---|
| PID file | ~/.openacp/openacp.pid |
Process ID of the running daemon |
| Log file | ~/.openacp/logs/openacp.log |
Daemon stdout/stderr and application logs |
| Running marker | ~/.openacp/running |
Written on start, removed on stop; used to decide whether to autostart on boot |
| Port file | ~/.openacp/api.port |
Current API port (written by the server on startup) |
Autostart on Boot
OpenACP can register itself to start automatically when you log in. This is configured separately per platform.
macOS — LaunchAgent
On macOS, autostart uses a user-level launchd plist:
~/Library/LaunchAgents/com.openacp.daemon.plist
When autostart is enabled, the plist is written and loaded with launchctl load. The daemon is configured with RunAtLoad: true and KeepAlive set to restart on non-zero exit. Log output goes to ~/.openacp/logs/openacp.log.
To enable autostart from the CLI:
openacp config # → Run Mode → Enable auto-start
Or via onboard:
openacp onboard # → Run Mode → switch to daemon mode (enables autostart automatically)
To remove the LaunchAgent:
openacp config # → Run Mode → Disable auto-start
This runs launchctl unload and deletes the plist file.
Linux — systemd User Service
On Linux, autostart uses a systemd user service:
~/.config/systemd/user/openacp.service
When autostart is enabled, the unit file is written and enabled with systemctl --user enable openacp. The service uses Restart=on-failure.
To enable or disable, use the same openacp config or openacp onboard flow as on macOS.
Windows
Autostart is not supported natively on Windows. Use WSL2 and follow the Linux instructions, or configure a Windows Task Scheduler entry manually pointing to the WSL binary.
When to Use Each Mode
| Scenario | Recommended mode |
|---|---|
| First-time setup | Foreground — watch the logs live |
| Debugging a problem | Foreground with OPENACP_DEBUG=true |
| Persistent personal server | Daemon with autostart enabled |
| CI / container | Foreground (process managed by container runtime) |
| Server with uptime requirements | Daemon + systemd (Linux) or LaunchAgent (macOS) |