Skip to main content
The o4 daemon is a long-running background process that can host agent sessions and serve them to clients over a Unix socket. It runs the same agent runtime that o4 sessions use, with a socket in front of it.
The daemon is experimental. In o4 0.2.74, nothing starts it for you, and interactive sessions, print mode (o4 -p), and o4 resume all run their sessions inside the o4 process without using the daemon. You only need the commands on this page if you are building or testing a client for it.

​
Commands

The commands take no options other than --help.

​
Start

o4 daemon start starts the daemon as a detached background process and waits up to 5 seconds for it to answer on its socket:
If a daemon is already running for the same data folder, o4 doesn’t start a second one:
If the daemon stopped without cleaning up, for example after a crash, start clears the leftover files first. If the daemon doesn’t answer within 5 seconds, start prints Error: the daemon did not answer within 5s; see followed by the path of daemon.log, and exits with code 1. Check that log for the reason. Other errors also exit with code 1.

​
Status

o4 daemon status exits with code 0 when the daemon is running and 3 when it isn’t, so scripts can check it without reading the output:

​
Stop and restart

o4 daemon stop asks the daemon to shut down with SIGTERM. If it’s still running after the grace period (10 seconds by default), o4 sends SIGKILL.
When no daemon is running, stop prints daemon is not running and exits with code 3. o4 daemon restart runs stop and then start, and prints what each one prints. If the daemon isn’t running, it prints daemon is not running, starts it, and exits with code 0:

​
Run in the foreground

o4 daemon serve runs the daemon in your terminal instead of in the background. It’s the command start launches, and it isn’t listed in o4 daemon --help. It prints nothing while it runs. o4 daemon status and o4 daemon stop work with it as usual, so stop it from another terminal with o4 daemon stop. If a daemon is already running for the data folder, serve exits with code 1:
If you stop serve with Ctrl+C, it leaves its socket and daemon.pid behind. status then reports not running, and the next start or serve clears the leftover files.

​
Files

The daemon keeps its files in a daemon folder inside the o4 data folder, which is ~/.o4 unless the O4_AGENT_RUNTIME_DATA_DIR environment variable points somewhere else. Each data folder has at most one daemon. The folder is readable only by you, and the socket has owner-only permissions. The daemon also closes any connection from a process running as a different user. It has no network listener.

​
Settings

You can tune the daemon in the [daemon] table of your user config file, ~/.o4/config.toml:
The daemon reads these settings when it starts, so run o4 daemon restart after you change them. stop_grace_ms is read by the stop command itself. If ~/.o4/config.toml can’t be read, the daemon commands use the defaults. o4 also reads [daemon] from the managed config, ~/.o4/managed/config.toml, and a key there wins over the same key in your file. o4 ignores a [daemon] table in a project’s .o4/config.toml or .o4/config.local.toml, with a warning in the log. The settings always come from ~/.o4, even when O4_AGENT_RUNTIME_DATA_DIR points the daemon’s files somewhere else. See Configuration files and the configuration reference.