ADF daemon

Install

Requires Node.js 22 or newer. 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. adf does not start a daemon while Studio 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.

Configuration

Environment variables

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:

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

Run one of them at a time on the same agents: both would open the same files, start the same channels and bind the same mesh port.

Limitations

• The API speaks plain HTTP. For remote use put an SSH tunnel or a TLS proxy in front (Remote daemon); with a proxy, set ADF_DAEMON_BEHIND_PROXY=1.
• No lock stops Studio and a hand-started daemon from opening the same .adf file. Let one process own each agent.
• The /events replay 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.