Daemon API

aivoryd is the only process that reads your agent sessions. The desktop app, the phone app and the aivoryd call command are all clients of one JSON-RPC 2.0 API. This page shows you how to connect, how to authenticate, and which methods and events exist.

Quick Start

Start a daemon with demo data and a private endpoint name. Then call it from a second terminal:

aivoryd serve --demo --endpoint docs-try
aivoryd call daemon/info --endpoint docs-try

aivoryd call <METHOD> --params '<JSON>' sends one request and prints every message that comes back. Stop the demo daemon with aivoryd call daemon/shutdown --endpoint docs-try.

Without --demo, aivoryd serve shows the real sessions of your machine (Claude Code, Codex CLI and Gemini CLI). See Daemon for what the daemon stores.

Transports

You can run --remote and --iroh together, and with --demo.

Local Pipe or Socket

The endpoint name is 1 to 64 characters of [A-Za-z0-9._-]. The default name is default. Choose another name with --endpoint <NAME>.

Open the pipe or socket, write one request as one line, and read lines. The local connection is trusted: it needs no token. It is the only transport that may call the local-only methods.

This Python script talks to a demo daemon on Windows. On Linux and macOS, open an AF_UNIX socket to the path above and use the same lines:

import json

pipe = open(r"\\.\pipe\aivory-code-docs-try", "r+b", buffering=0)


def call(id, method, params=None):
    msg = {"jsonrpc": "2.0", "id": id, "method": method}
    if params is not None:
        msg["params"] = params
    pipe.write((json.dumps(msg) + "\n").encode())
    # A notification has no id. Skip it until the response with this id arrives.
    while True:
        line = b""
        while not line.endswith(b"\n"):
            line += pipe.read(1)
        reply = json.loads(line)
        if reply.get("id") == id:
            return reply


print(call(1, "daemon/info")["result"]["version"])
print(call(2, "autopilot/get"))

WebSocket

aivoryd serve --remote 0.0.0.0:7420

The daemon listens on that address. The pairing QR code names the LAN address of the machine and the same port. Connect with a WebSocket client to ws://<host>:<port>/ and add a query:

The server answers 401 Unauthorized for an unknown token or a code that is used or expired, and 400 Bad Request when the request is no WebSocket upgrade. Each text frame is one JSON-RPC message, in both directions. A frame can hold up to 8 MB. The LAN link has no TLS. Use it on networks that you trust, or use iroh.

iroh

aivoryd serve --iroh --relay default

--relay takes a URL, default for the iroh relays, or none for direct paths only. Open a QUIC connection with the ALPN aivory/rpc/1 and one bidirectional stream. Each message is a frame: a 4-byte big-endian length, then one JSON-RPC message (up to 8 MB).

The first frame must be the request link/hello:

The reply has deviceId, name, newlyPaired, node (the node id of the daemon) and, for a new device or needToken, a token for the WebSocket link. A device that is not allowed gets an error with code -32001 and the daemon closes the stream.

Message Format

Every message is a JSON object.

{"jsonrpc":"2.0","id":1,"method":"autopilot/get"}

Names in JSON are camelCase. Time values are milliseconds since the Unix epoch.

Pair a Remote Client

A remote client has no token at first. A local client creates a pairing code, and the remote client trades it for a token.

1. A local client calls devices/pair. The result has code (AIV- and 6 characters), expires (a time in ms, 10 minutes ahead) and url.
2. Show url as a QR code, or give the code to the remote client. The link has the form aivory://pair?node=<node id>&relay=<relay url>&host=<ip:port>&direct=<ip:port,...>&code=<code>. Each field is optional.
3. The remote client connects once with the code. On the WebSocket link it adds ?code=<code>&device=<name>. On iroh it sends the code in link/hello.
4. On a new pairing, the first message from the daemon is a notification:

{"jsonrpc":"2.0","method":"device/paired","params":{"token":"<64 hex characters>","device":{"id":"d1a2b3c4","name":"Pixel","os":"Android","paired":0,"lastSeen":0,"online":true}}}

5. Store the token. The daemon keeps only its SHA-256, so the token comes once. Use ?token=<token> on later WebSocket connections. On iroh, the key of the device proves who it is.

A code works once and ends after 10 minutes. devices/remove with a device id deletes the device and closes its iroh connection. settings/get lists the devices.

A paired device can register a push target with devices/push. The daemon sends the sealed phone push to the gateway that you set with --push-url <URL> (or the setting remote.pushUrl). Without a URL, the daemon sends no push.

Local-only Methods

A paired device gets the error -32004 (NOT_AVAILABLE) for these methods. Only the local pipe or socket may call them:

repos/add, repos/remove, project/new, map/addPart, providers/addAcp, providers/removeAcp, settings/importClaude, daemon/restart, theme/inspect, theme/add, theme/remove, theme/checkUpdates, theme/update, theme/diff, theme/job, registry/add, registry/remove, registry/refresh.

All other methods are open to a paired device. theme/list, theme/get and theme/asset are how a phone loads a theme.

Follow the War Room

warroom/snapshot returns the full view once. For a live view, use the feed:

1. Call warroom/subscribe with {}. The result has epoch, cursor and a snapshot (the full WarRoom).
2. The daemon then sends warroom/delta notifications on the same connection. Each has params.seq (increasing) and params.delta.
3. Apply each delta to your copy of the view and set your cursor to seq.
4. After a reconnect, call warroom/subscribe with {"cursor": <last seq>, "epoch": <epoch>}. If the epoch is the same, the result has deltas (everything you missed) and no snapshot. If the daemon restarted, the epoch changed and you get a fresh snapshot.

{"jsonrpc":"2.0","method":"warroom/delta","params":{"seq":42,"delta":{"type":"tick","now":1792593300000}}}

A delta has a type:

The Rust type WarRoom has apply(seq, delta) that implements these rules. The session states are needsYou, error, working, idle, parked and done.

Other Notifications

The ADR for themes names a notification theme/changed. The daemon does not send it yet. Call theme/list again to see changes.

Methods

The schema has 77 methods, and the daemon has three more (sessions/*). Parameters with ? are optional. Result types are named in the schema $defs. The daemon returns -32004 for a method that needs the war-room engine on a daemon that does not run it.

Two methods work only with aivoryd serve --demo: session/resume and session/handoff. A live daemon answers -32004.

Daemon

War Room and Autopilot

Sessions

Here id is a session id from warroom/snapshot.

The providers of sessions/* are claude, codex and gemini. The war-room methods also name opencode and goose.

Inbox and Tasks

Repos and Projects

Settings, Providers and Devices

Code Intelligence and the Ledger

Pass session to read the worktree of a session. The schema has the types of the positions, ranges and results.

Coordination

Themes and Registries

A job method returns {"job": "<id>"}. Poll theme/job with that id until state is done or failed. A done job has result.

To draw a theme in your client, read the theme reference and call theme/get with your display class. The settings key display.customTheme holds the id of the theme that the user selected.

Examples

These calls run against aivoryd serve --demo. The commands print one response per line.

Read the Daemon

aivoryd call daemon/info --endpoint docs-try

Request:

{"jsonrpc":"2.0","id":1,"method":"daemon/info"}

Response:

{"id":1,"jsonrpc":"2.0","result":{"contract":"0.1.0","cwd":"C:\\work","demo":true,"host":"CAPTIVA","name":"aivoryd","pid":7972,"protocol":"jsonrpc-2.0/ndjson","version":"0.1.0"}}

contract is the version of the protocol. cwd is shortened here. cwd, host and pid change on each run.

Change the Autopilot

aivoryd call autopilot/set --params '{"maxRunning":10}' --endpoint docs-try

Request and response:

{"jsonrpc":"2.0","id":1,"method":"autopilot/set","params":{"maxRunning":10}}
{"id":1,"jsonrpc":"2.0","result":{"maxPerCodebase":4,"maxRunning":10,"on":true,"order":"priority","parkAfterMin":15,"startQueued":true}}

The result is the whole Autopilot object. Fields that you leave out do not change.

Handle an Error

aivoryd call session/pause --params '{"id":"zzz"}' --endpoint docs-try

Response:

{"error":{"code":-32001,"message":"no session 'zzz'"},"id":1,"jsonrpc":"2.0"}

An unknown method gives -32601:

{"error":{"code":-32601,"message":"unknown method 'nope/x'"},"id":1,"jsonrpc":"2.0"}

Error Codes

An error has code, message and sometimes data.

Versioning

The protocol is at version 0.x and may change between releases. Read contract after you connect and compare it with the schema that you built against. Ignore unknown fields in results and unknown type values of a delta. The JSON Schema file is generated from the Rust types and is the source of truth: proto/schema/aivory-protocol.schema.json. The folder proto/fixtures/ of the repository has one real result for each demo method. Protobuf frames are planned. The wire format today is JSON-RPC 2.0.

Next Steps