ADF daemon
The background process that runs your .adf agents without a desktop window and serves the Daemon API. It runs the same agent files as Studio, for terminals, scripts, servers, and background agents.
On this page
| Package | @agentdocumentformat/cli, command adf daemon |
|---|---|
| Daemon API | http://127.0.0.1:7385, bearer token on every route but /health |
| Agent websites (mesh) | http://127.0.0.1:7295/agents/{handle}/ |
| Runs on | Node.js; see published npm requirements or main source requirements |
| Clients | ADF Studio, the adf commands and terminal app, curl, or any HTTP client |
Install
npm install -g @agentdocumentformat/cli@latestUse the Node.js requirements for the published npm release. The ADF CLI package installs the adf command: the daemon, one-shot commands and the terminal app. Native modules come prebuilt, so no compiler is needed.
Run the daemon
You usually do not start it yourself. adf starts the daemon in the background when no daemon answers on this machine, and it keeps running after the terminal app quits.
adf daemon start # start in the background
adf daemon status # pid, uptime, version, log file
adf daemon logs -f # follow <data dir>/logs/adf-daemon.log
adf daemon restart
adf daemon stop # graceful: agents unloaded, containers stopped
adf daemon # run in the foreground; Ctrl+C stops it--no-daemon or ADF_NO_AUTOSTART=1 turns off automatic start. Studio starts the same daemon, or attaches to one that runs, and runs no agents itself. adf refuses to start a daemon only while a Studio in the legacy Inside Studio mode runs on the same settings; adf daemon start --force skips that check. To start it at login, run adf daemon from systemd, launchd, or a Windows scheduled task. More:Operations.
Load an agent
At startup the daemon loads reviewed autostart agents from the tracked folders in its settings. To add more:
- In the terminal app, press o on Fleet (5) or type
/load path/to/agent.adf. f tracks a folder. - Create one from a template with
adf new my-agent --start. - Over HTTP, with the token from
adf daemon token:
TOKEN=$(adf daemon token)
curl -X POST http://127.0.0.1:7385/agents/load \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"filePath":"/absolute/path/to/example.adf"}'Direct loads skip the review gate unless the request sets "requireReview": true. Autostart only starts agents that are marked autostart, reviewed, not password protected, and not already loaded.
Access token
Every request except GET /health needs Authorization: Bearer <token>. On first start the daemon writes a random token to daemon-token in its data directory. Clients on the same machine read it automatically. For a client elsewhere, print it with adf daemon token and pass it as --token orADF_DAEMON_TOKEN. Delete the file and restart the daemon to rotate it.
Owner identity changes (POST /identity/*) and POST /daemon/shutdown also require a local caller: a loopback connection with no proxy headers. Other callers get 403 loopback_only. Details:Request guard.
Other computers
Remote access lets another computer use this daemon: adf, the terminal app, or Studio on a laptop. It turns on and off without a restart, and listens only on private and Tailscale addresses, on networks you allowed.
# on the computer that runs the agents
adf daemon remote on # or in Studio: Settings → Connections → Add → Share
adf daemon pair # shows a 6-digit code for 2 minutes
# on the other computer
adf pair # lists the ADF computers it finds; or: adf pair <host>After you allow the device, it gets its own device token, saved in the OS keychain. adf daemon deviceslists the paired devices and adf daemon devices revoke disconnects one. A device token cannot reach the owner identity, stored values, or shutdown, but it can run agents and their tools: treat it like the seed phrase. On a LAN the connection is plain HTTP; on a tailnet, pair over the tailnet address or useadf daemon remote serve on for HTTPS. SSH tunnels and TLS proxies also work:Remote daemon.
Configuration
Environment variables
| Variable | Default | Purpose |
|---|---|---|
ADF_DAEMON_HOST | 127.0.0.1 | Host for the Daemon API |
ADF_DAEMON_PORT | 7385 | Port for the Daemon API |
ADF_DAEMON_SETTINGS | Studio’s adf-settings.json | JSON settings file to load |
ADF_USER_DATA_DIR | platform default | Base data directory when no settings path is given |
ADF_DAEMON_TOKEN | <data dir>/daemon-token | Access token. Overrides the token file. Required with a non-loopback host. |
ADF_DAEMON_ALLOWED_HOSTS | unset | Host names clients use when bound beyond loopback |
ADF_DAEMON_BEHIND_PROXY | off | 1 when a reverse proxy on this host forwards to the daemon. Identity secrets and shutdown then also need the local proof file. |
ADF_DAEMON_PIDFILE | next to the settings file | Where to write the process ID |
adf daemon also takes --port, --host and --settings.
Settings file
By default the daemon reads the same adf-settings.json and owner identity as Studio, so providers and tracked folders carry over. Point ADF_DAEMON_SETTINGS or ADF_USER_DATA_DIR elsewhere to keep them separate. Common keys:
| Key | Purpose |
|---|---|
providers | Model provider configurations |
trackedDirectories | Folders scanned at startup for autostart agents |
reviewedAgents | Agent IDs accepted by the review gate |
mcpServers | Global MCP server registrations |
adapters | Global channel adapter registrations |
compute | Podman and compute routing |
meshEnabled | Mesh behavior, on unless false |
Full schema and an example file: Runtime settings.
Daemon API
The Daemon API covers agent lifecycle, chat, events, approvals, identity, credentials, channels, MCP, settings, and compute. Chat turns are asynchronous: POST /agents/{id}/chat answers 202with a turnId, and GET /events streams what happens next as server-sent events. A running daemon serves its own contract at /openapi.json.
Concepts and examples: API guide. Every endpoint: API reference.
Daemon and Studio
| Area | ADF Studio | ADF daemon |
|---|---|---|
| Role | Client of the daemon, with a desktop window | Runs the agents |
| Use | Desktop authoring and visual operation | Terminals, scripts, servers, other clients |
| Visibility | Loop, logs, agent panels, and the Mesh view | Terminal app, /events stream, daemon log |
| Settings and identity | The same adf-settings.json and owner identity on one machine | |
| Agent websites | The daemon's mesh server on port 7295 | |
By default Studio runs its agents in this daemon (Local mode). Studio, the terminal app, and adf commands then show the same agents at the same time, and a chat or approval in one appears in the others. Studio can also connect to the daemons of other computers; each is a runtime of its own. Whether quitting Studio stops the daemon is the setting Keep running after Studio quits; Studio never stops a daemon that adf daemon startor a service started. Details: Connections and runtimes.
On one machine, each agent file runs in one runtime at a time. A runtime takes a lease on the file when it starts the agent; starting it elsewhere is refused with agent_leased. The lease covers one OS user on one machine, not a file on a network share opened from two machines.
Limitations
- The API speaks plain HTTP. Remote access on a LAN sends the token unencrypted; for HTTPS use
tailscale serve, an SSH tunnel, or a TLS proxy (Remote daemon). With a proxy, setADF_DAEMON_BEHIND_PROXY=1. - Agent leases cover one OS user on one machine. An
.adffile on a network share opened from two machines is not protected. - The
/eventsreplay buffer is in memory (1000 frames), not an audit log. Durable history is in each agent’s file. - File-change triggers are incomplete without Studio’s document editor.
- From a source checkout (
npm run daemon), switching between Studio (Electron) and the daemon (Node) rebuilds the native SQLite module.