Daemon API

1Endpoints

2Base URL

The daemon listens on http://127.0.0.1:7385 by default and speaks plain HTTP. Set the address withADF_DAEMON_HOST and ADF_DAEMON_PORT. Requests and responses are JSON. SendContent-Type: application/json only with a body.

Agents are addressed by id, handle or name ({id}). Loop-aware routes take loop; absent means main.

export TOKEN=$(adf daemon token)
curl http://127.0.0.1:7385/health
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:7385/agents

3Authentication

Every route except GET /health needs a bearer token:

Authorization: Bearer <token>

Per-install token from <settings dir>/daemon-token (printed by adf daemon token), or ADF_DAEMON_TOKEN. Local adf clients send it automatically.

ADF_DAEMON_TOKEN overrides the file, on the daemon and in clients. A missing or wrong token gets401 with code unauthorized.

4Request guard

Three header checks run on every route, before authentication. The daemon sends no CORS headers, so web pages cannot call it.

These routes answer local callers only (403 loopback_only): a loopback connection with no proxy header (Forwarded, X-Forwarded-For, X-Forwarded-Host, X-Forwarded-Proto,X-Real-IP, Via).

• POST/daemon/shutdown
• POST/identity/create
• POST/identity/restore
• POST/identity/unlock
• POST/identity/lock
• POST/identity/confirm-backup

Behind a reverse proxy on the same host, start the daemon with ADF_DAEMON_BEHIND_PROXY=1. These routes then also need X-ADF-Local-Proof, a secret the daemon writes at every start to<settings dir>/daemon-local-proof. The adf CLI and terminal app on that host send it; a caller through the proxy cannot.

5Turns and events

POST /agents/{id}/chat and POST /agents/{id}/trigger answer 202 with aturnId. Every event of that turn carries it as turn_id, ending with turn.completedor agent.error. Messages sent while the loop is busy queue in arrival order and are not dropped; the first interrupts the running turn.

GET /events is a server-sent event stream. Each frame has a daemon-wide cursor, also the SSEid. Resume with ?since=<cursor> or Last-Event-ID, plus?epoch=. Every connection opens with a stream.hello frame that names the daemon run (epoch). A stream.gap frame reports that frames were lost or the daemon restarted; re-read agent state when you get one. Replay comes from an in-memory buffer of the last 1000 frames.

6Errors

Errors are JSON with a human-readable error and a stable machine code. Every error has acode: a specific one where the route defines it, otherwise the status default (bad_request,forbidden, not_found, not_supported, conflict,internal_error, upstream_error, unavailable). Show error; branch oncode.

{ "error": "Unknown agent \"agent-1\"", "code": "not_found" }

A body the HTTP framework cannot parse (malformed JSON, or an empty body sent withContent-Type: application/json) is refused with 400 in Fastify's shape:{ statusCode, code, error, message }. Send no Content-Type on bodiless POSTs.

7Versioning

The API is not versioned by URL. This reference documents API version 0.2.0. A running daemon serves its own contract at GET /openapi.json, and GET /runtime returns its package version as daemon.version.

• Ignore fields you do not know. New fields are added without notice.
• Treat a 404 on a route you need as an older daemon: fall back, or ask the user to update.
• There are no ETags. The last write wins; re-read before you replace a whole config.

8Mesh server

Agent websites, agent cards and ALF message delivery are served by a separate HTTP server on the mesh port (default7295), not by this API. It does not use the daemon token. It is on by default and starts once a reachable agent loads; /network/server/* and meshServerEnabled control it.

POST /agents/:handle/inbox is the only way to deliver a real inbound message: it takes a full, signedALF message. POST /agents/{id}/trigger on the Daemon API does not substitute for it. Everything else under /agents/:handle/* is served by the agent itself: see HTTP serving.

9Specification file

This reference is generated from docs/daemon/openapi.json in the ADF repository, atv0.7.4 (commit 56f129b). Download it to generate a client or load it into an OpenAPI tool.

Download openapi.json · OpenAPI 3.1.0 · 192 operations

For concepts and flows (chat turns, the event stream, approvals, identity), read the API guide. To install and run the daemon, see ADF daemon.