Daemon HTTP API

The local dashboard, CLI, and future relay clients use this API. Browser code must not read daemon files or import daemon implementation modules. All paths below are relative to the authenticated listener. Responses are JSON; timestamps are ISO 8601 UTC strings. Session IDs are <group>/<name>. Task IDs are integers scoped to their group. Approval, question, message, note, and event IDs are database-wide integers.

Transport and authentication#

The daemon listens on 127.0.0.1 at the port in $NID_HOME/daemon.json. CLI requests send Authorization: Bearer <daemon token>. Keep that token out of browser code, URLs, storage, and HTML. Agent MCP requests use a per-session bearer token and include session in the RPC envelope; those credentials cannot access human methods or the SSE stream.

The separate dashboard listener accepts its HttpOnly SameSite=Strict session cookie after a one-time login exchange. It routes to the same API with a human dashboard principal. Dashboard cookies never authorize agent RPC envelopes, shutdown, or dashboard.* methods. The listener validates Host and Origin before calling the API. See Dashboard listener for the login exchange and the checks.

POST /rpc, with Content-Type: application/json:

{"method":"sessions.list","params":{"group":"web"}}

Success is {"ok":true,"result":...} (undefined becomes null). A method failure is {"ok":false,"error":"readable reason"} with HTTP 200. Human authentication failures are HTTP 401; malformed JSON/envelopes are HTTP 400; unsupported paths/verbs are HTTP

404. Invalid agent credentials return an RPC error. Bodies are limited to 16 MiB. Unknown methods return unknown method <name>; unknown tools return unknown tool <name>. Clients must inspect ok, not just the HTTP status. Requests do not use JSON-RPC 2.0 IDs or batch arrays. No CORS access is granted.

Interactive front door#

These human RPCs work through both daemon bearer authentication and the dashboard cookie.

team.start {dir, goal, group?} returns {group: string, started: boolean}. It loads the repository's nid.yaml, selects the named group or the first configured group, starts missing sessions, resumes stopped sessions, and sends the goal to the lead (or the first session in a peer team). Existing sessions keep running. The group goal is updated and the goal is delivered once as a human message. started is true when no session was running before this call. Concurrent starts are serialized by group. Configured worker prompts are retained; a new lead receives its configured prompt along with the goal. A group name belonging to another repository is rejected.

group.summary {group} returns the shared terminal/dashboard completion card:

{
  group: string,
  goal: string,
  done: boolean,
  doneNote?: {text: string, author: string, at: string},
  tasks: {total: number, done: number, open: number, claimed: number,
          blocked: number, review: number, cancelled: number},
  agents: [{id: string, name: string, agent: string, state: SessionState,
            costUsd: number, tokens: {input: number, output: number}}],
  spend: {costUsd: number, estimatedUsd: number, billedUsd: number, budgetUsd: number | null},
  tokens: {input: number, output: number},
  diffstat: {files: number, insertions: number, deletions: number,
             perFile: [{path: string, ins: number, del: number}]},
  commits: number,
  changedSummary: string[],
  rateLimit: RateLimitInfo | null
}

done means the latest lead decision starts with DONE:; a solo session also counts as the lead. Submitting another goal through team.start clears the previous DONE card. Worker notes never mark a multi-agent group done. changedSummary contains done task titles and summaries. Diff totals and commit counts compare the integration branch with the group's original base; unintegrated work is excluded. Binary files count as files with zero line counts. Git totals are cached by base and integration HEAD, making two-second polling inexpensive. rateLimit is the worst reported state, or null when there is no report. costUsd = estimatedUsd + billedUsd.

session.interrupt {session} returns "ok" and interrupts that session's turn, including dismissing pending approvals/questions. Existing interrupt {target} continues to accept a session or group.

approvals.answer {id?, session?, allow?, remember?, message?} and the existing approve RPC return resolved approval IDs (number[]). allow defaults to true; remember accepts only "session". With allow: true, it remembers the matching tool or command rule for this running agent session. Known command CLIs match their executable and verb (for example npm install); other simple commands match exactly. Compound shell commands and broad permission grants always require another answer. Tool identities come from driver metadata, never display text. Unidentified requests (including ACP requests without a stable tool identity) cannot be remembered. Rules end when the session's driver stops/restarts or the daemon restarts.

With allow: false, optional message is delivered as human guidance to the agent; Claude also receives it in its tool rejection response. Approval records keep their existing shape {id, sessionId, title, detail, status, createdAt}. Titles now explain the action using the requesting session's name, such as lead wants to run \npm install x` or codex2 wants to edit src/a.ts`; detail contains the full request for expansion. Automatically allowed requests remain in approval history and emit an allowed event.

Stored/streamed tool_call and tool_result events include a one-line summary (at most 240 characters) for collapsed display, alongside the existing tool, id, full input/output and result ok. Match calls/results by id when the driver supplies one. Older stored events may omit summary; clients should fall back to the tool name. Text output retains its original newlines for the expanded view.

For isolated UI journeys, copy test/fixtures/journey.yaml into a temporary Git repo as nid.yaml, or use writeJourneyConfig(repo) from test/helpers.ts. Its mock lead runs a deterministic journey on the first goal: command approval, task creation and claim, a journey.txt change, integration, and a DONE: decision. Denial aborts the journey. The mock also accepts APPROVE_COMMAND <command>, TASK <path> <text>, DONE <summary>, and JOURNEY as explicit script lines. No command is actually executed by APPROVE_COMMAND. Always give test daemons a temporary NID_HOME.

Dashboard listener#

The browser dashboard has its own listener, also bound to 127.0.0.1. The daemon starts it at launch on port 7420 (or a free port when 7420 is taken; NID_DASHBOARD_PORT pins the port, off defers it to the first dashboard.open) and records the port as dashboardPort in daemon.json. It serves the UI and the same POST /rpc and GET /events and GET /terminal as above, authenticated by a session cookie instead of a bearer token.

Signing in:

1. A bearer client calls dashboard.open {port?} (bearer only). Result: {port, url, loginUrl}; passing a different port moves the listener there. nid dashboard [--port n] [--no-open] does this and opens loginUrl.
2. loginUrl is http://127.0.0.1:<port>/login?token=<48 hex>. The token is single use and expires after 60 seconds.
3. GET /login?token=... answers 303 Location: / with Set-Cookie: nid_session=<random 256-bit id>; HttpOnly; SameSite=Strict; Path=/; Max-Age=2592000. Invalid, reused or expired tokens get 401; a cross-site navigation (Sec-Fetch-Site: cross-site|same-site) gets 403. Sessions live in daemon memory, so a daemon restart signs browsers out.
4. POST /logout (same-origin) deletes the session and clears the cookie (204). It has no body or RPC envelope, does not stop agents, and is idempotent without a live cookie. It still requires a matching Origin or Sec-Fetch-Site: same-origin.

Checks on every request, before anything reaches the API:

Behind the cookie, the API is the human API except that agent envelopes (session set), shutdown and dashboard.* are refused. The daemon bearer token is not accepted on this listener and the cookie is not accepted on the bearer port. Responses carry Content-Security-Policy: default-src 'self'; ...; frame-ancestors 'none', X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Referrer-Policy: no-referrer; API responses are Cache-Control: no-store. The page never receives the daemon token.

Limits: at most 32 outstanding login links and 64 signed-in browsers (the oldest are dropped first); at most 64 open /events streams per daemon (NID_MAX_EVENT_STREAMS), beyond which /events answers 503 with Retry-After: 5; a stream whose client stops reading is closed once 2 MiB are queued (EventSource reconnects and resumes); request bodies are limited to 16 MiB. Bearer tokens are compared in constant time.

Residual risk: browsers do not isolate cookies by port, so the session cookie is also sent to other servers on 127.0.0.1 (any port). A hostile local web server the browser visits could capture it; such a process already runs as a local user, but on shared multi-user machines sign out (or let the daemon restart) after use. Login links are single use and expire in 60s, so a link left in browser history is harmless.

A hosted or relayed UI must reach the daemon only through these same endpoints.

Human RPC methods#

? denotes an optional field; {} means no parameters. All methods require human authentication. The data records are specified in src/protocol.ts; their public fields are summarized below. Optional fields omitted in a patch remain unchanged.

Session options are {model?, permissions?:"worktree"|"ask"|"yolo", yolo?, shared?, autoRestart?, extraArgs?:string[], billing?:"auto"|"subscription"|"api", compression?:boolean|CompressionSetting}. compression overrides the group's and ~/.nid/config.yaml's compression keys for this session (invalid values error at spawn). billing overrides the group's and ~/.nid/config.yaml's billing setting for this session; an invalid value errors at spawn, and a mode the agent cannot use fails the start with the reason (for example no subscription login, no API key, or an agent whose billing nid does not manage). Group policies are lead or peers. GroupConfig contains id, absolute dir, optional goal, policy, setup, budgetUsd, autoRestart, settings (GroupSettings from the group's top-level settings keys) and sessions. Each configured session contains agent, resolved name, and optional model, yolo, shared, autoRestart, role, prompt, billing, compression.

Pull requests and CI tasks#

land {pr:true} uses gh when installed and authenticated for the origin host (gh auth status --hostname); otherwise, when the daemon has GH_TOKEN or GITHUB_TOKEN, the REST API. Error text is redacted (tokens, URL credentials). The origin fetch URL identifies the GitHub repository; git pushes to origin's configured push URL. PR creation saves Group.settings.pr = {url, number, base}. It summarizes the group goal, tasks and summaries, authors/reviewers, session cost and token totals. An open PR with matching head and base is reused. Subsequent PR landing pushes new integrated work.

Each failing check yields an open task with meta.check: {name, sha, url?} and log links in its detail. The name/head pair is unique across repeated polls even if its task is already done. Pending/cancelled/skipped checks do not create tasks. REST polling includes check runs and legacy statuses with pagination. pr.watch is optional background polling, resumes after daemon restart, stops on explicit cancellation or group removal, and does not push agent fixes automatically.

For local API integration tests, NID_GITHUB_API overrides the API base and selects REST instead of gh; normal deployments should leave it unset.

Local worktree files#

spawn accepts settings: {copy?:string[], link?:string[]}; group.update accepts the same settings patch for future sessions. The lists are persisted on Group.settings; omitted lists are unchanged, empty lists clear them. config.read/up also accept these keys at group level in nid.yaml. Example RPC:

{"method":"group.update","params":{"group":"web","settings":{"copy":[".env","config/**/*.json"],"link":["node_modules"]}}}

Paths are relative to Group.repo. Copy supports files/directories and *, ?, ** globs; link supports directories/globs (symlinks on Unix, junctions on Windows). New isolated worktrees are populated before setup. Existing files are preserved and tracked files are skipped. Missing/unmatched sources emit a session notice. Absolute, parent-traversing and .git paths are rejected; source symlinks are skipped. Git info/exclude entries prevent normal task commits from including copied/linked paths. Excludes are shared across the repository's worktrees. Existing/resumed and shared-checkout sessions are not populated.

Group settings#

Group.settings holds optional per-group settings (all keys optional; omitted keys use the default). They can be set in nid.yaml (as top-level keys of a group), with nid group set <group> key=value..., or with group.update {settings}.

Notifications#

The daemon raises notifications for: approval (an agent requests permission), question (ask_human), blocked (task marked blocked), stall, limit (rate limit), done (a DONE: decision note), budget (budget reached), review and pr. Targets are the desktop (Windows toast via PowerShell, macOS osascript, Linux notify-send; skipped when unavailable; NID_NOTIFY_DESKTOP=0 disables it) and webhooks from $NID_HOME/config.yaml:

notify:
  desktop: true
  events: [approval, question, blocked, stall, limit, done, budget]   # optional filter
  webhooks:
    - url: https://hooks.slack.com/services/...   # Slack: {"text": ...}
    - url: https://discord.com/api/webhooks/...   # Discord: {"content": ...}
    - url: https://example.com/nid
      kind: json                                  # {event, group, session, title, body, suppressed, at, source}
      events: [done]

merged with the group's settings.notify (group desktop/events win; webhooks are combined). An event key is sent once per 10 minutes; each target gets at most 6 notifications a minute, and the next delivery reports how many were suppressed.

Remote access (cloud.*)#

Remote access is docs/remote.md. These methods drive it from the CLI (nid cloud ..., behind --experimental) and the local dashboard; both listeners expose them. Operations that turn "can reach" into "can read" (link and re-link, relay change, key rotation, pairing, raising a role, widening a scope) run the platform user verification inside the daemon, in the method itself (2.4): no parameter can assert that a person was verified, so it does not matter which local caller asks. A refused or failed verification is an error naming the reason; noUserVerification is accepted only on a machine without a verifier (first link, and pairing capped at view).

The Remote column is the method's tier for a paired device (src/remote/allowlist.ts, 5.3): READ for every role, ADMIN for admin devices, LOCAL never through the channel. From a device, roles can only be lowered, scopes only narrowed, a device cannot revoke itself, a scoped admin reaches only devices inside its scope, and cloud.pair.begin shows its code on the machine only.

The connector's wire protocol to the relay (relay_ctl operations on channel 0 for routing tokens and revocation, and the self-hosted relay's HTTP and WebSocket endpoints) is docs/remote.md appendix C; the frames inside a device channel are appendix B. A device reaches every other method only as allowed by the allowlist above; destructive ones (group.remove, memory.clear, session.permissions {profile:"yolo"}, taking terminal control) answer the first call with {twoStep:true, confirm, expiresInSeconds:60, message} and run on a second call that repeats the parameters plus confirm.

Public records#

• Group: id, nullable repo and base, goal, policy, setup, nullable budgetUsd, settings, createdAt.
• Task: id, groupId, title, detail, status, nullable owner, createdBy, deps, summary, meta (feature bookkeeping: budgetMinutes?, claimedAt?, reassignments?:[{from, at, reason}], review?, check?), createdAt, updatedAt. Statuses: open, claimed, review (finished, waiting for a reviewer; see review.*), blocked, done, cancelled. meta.review on a reviewed task: {task, reviewer, round, head, verdict?, by?, notes?, approved?} (its current review task, round number, reviewed commit); on a review task: {of, author, round, head}.
• Session: id, groupId, name, agent, role, state, cwd, nullable branch, vendorSessionId, pid, status, options, costUsd (all reported cost), billedUsd (the part paid through an API key: turns run while the session's resolved billing.mode is "api"; sessions without a resolved mode use options.billing, and the mock driver counts as billed unless billing:"subscription"; the rest of costUsd is an API-equivalent estimate on a subscription plan; absent on records from older daemons = all billed), nullable usageWindow ({usedPercent?, resetsAt?, kind?, at}: the latest plan usage window the agent reported, at any level), inputTokens, outputTokens, turns, nullable context ({used, size, updatedAt, turns, rotations, lastRotation?:{at, mode, reason}}: tokens in the context window after the last model call and the window size as reported by the agent, null when unknown; turns counts turns since the conversation started or was last rotated), nullable billing ({mode:"subscription"|"api"|"unmanaged", requested:"auto"|"subscription"|"api", detail}: how the agent was billed at its last start, e.g. detail claude.ai max or API key from $ANTHROPIC_API_KEY; unmanaged for agents that choose billing themselves; fallback?:{until, since, reason} while a rate-limit fallback bills the API key (group setting fallback); null before the first start), nullable rateLimit ({status:"ok"|"warning"|"limited", resetsAt, usedPercent?, kind?, message?, since?}; nid stores only "warning" and "limited"), createdAt, updatedAt. States: starting, idle, working, waiting, limited (provider usage limit reached; resumes at rateLimit.resetsAt), native (driver paused for a native takeover; see session.takeover), stopped, error. A daemon restart turns native sessions into stopped. Quiet fields are nullable timestamps/durations computed at read time. rateLimit is persisted: warning when a usage window is at least the group's limitWarnPercent (default 90) full, limited while the provider limit is hit. A limited session holds all deliveries until resetsAt (plus a few seconds), then returns to idle, re-queues the input of a turn the limit cut short and delivers what was held. When the wait is longer than the group's limitReleaseMinutes (default 20) its claimed tasks are released back to open (recorded in task meta.reassignments and on the board) and offered to idle teammates. The limit survives stop/resume and daemon restarts. sessions.list and session.get add compression: {count, originalTokens, compressedTokens, enabled}: tokens compression saved in the session's traffic (persisted) and whether compression is on for it.
• BoardEntry: id, groupId, author, kind, text, createdAt.
• Lock: groupId, path, session, reason, expiresAt (expired locks are removed when read).
• Message: id, groupId, from, to, text, createdAt.
• Approval: id, sessionId, title, detail, status (pending, allowed, denied), createdAt.
• Question: id, groupId, sessionId, text, status (pending, answered, timeout), nullable answer, createdAt, nullable answeredAt.
• StoredEvent: id, sessionId, ts, event (tagged AgentEvent below).

Agent RPC tools#

Agents POST the same RPC envelope with session:"web/worker" and their per-session bearer credential. The result is always {text:string, notices:string[]}. Notices are messages delivered while the agent was working. Tools are scoped to the authenticated session's group; human credentials/cookies cannot impersonate a session.

Completing a task with a summary does not require a new file edit. When its work is already integrated, task_update done succeeds and explains that there are no new changes to commit. Edits that normalize away during staging (such as line-ending-only changes) also avoid an empty commit. If a submodule still has unfinished changes, completion instead asks the agent to check git status and commit those changes first.

Raw terminal stream#

GET /terminal?session=<encoded group/name> opens a running PTY's raw terminal. It requires human bearer authentication or a dashboard cookie; agent credentials cannot read it or call terminal RPCs. Missing sessions and structured/stopped sessions return HTTP 400 JSON errors.

The response is text/event-stream. Events are JSON:

Heartbeats arrive every 15 seconds. There are at most 64 terminal streams per daemon (503 beyond the cap), with a 2 MiB output queue per connection; slow clients are disconnected. This stream has no event IDs or historical replay cursor. Reconnect gets a new viewer ID and fresh snapshot; reset the terminal emulator before replaying it. A rolling raw buffer may lack older screen state.

To type, call session.terminal.control with active:true and this stream's viewer ID, then use session.terminal.write / session.terminal.resize. Another controlling viewer, an expired viewer ID, a viewer from another session, malformed base64 or invalid dimensions returns an RPC error. Input never goes through the chat queue. Control pauses automated turn-end detection and delivery (including human chat messages) without stopping the process. Release with active:false; closing the stream releases automatically. Queued messages resume after any pending PTY work settles. Control is ephemeral and is lost on stop or daemon restart.

nid attach --tty uses this API and reserves Ctrl-] for local detach. The dashboard bundles xterm.js and its CSS in its offline assets, starts read-only, and enables input after Take control.

Server-Sent Events#

GET /events with human authentication returns text/event-stream. Browser clients use a same-origin EventSource and their cookie. Native/relay clients use daemon bearer authentication. Query parameters:

• group: repeatable or comma-separated group IDs.
• session: repeatable or comma-separated full session IDs.
• after: nonnegative event ID, default 0.

Nonempty Last-Event-ID takes precedence over after (an invalid or empty supplied header returns HTTP 400). Group and session filters intersect; values within each filter are ORed. Session filters still receive group-wide hints affecting their group, such as task and goal changes. Group streams automatically include sessions created later.

Each connection first receives hello. Refetch snapshots on every hello because change hints are not persisted. Stored events strictly newer than the cursor are replayed chronologically, then live events follow without a subscription gap. Replay retains at most the newest 1000 matching events; overflow sends resync before that bounded replay. Fetch older transcript pages through session.events as needed. Event retention can remove historical rows; this stream is not a permanent audit log.

Only agent frames carry an SSE ID. EventSource automatically sends that ID on reconnect; deduplicate by ID when combining replay, RPC transcript pages and live activity. The hello.lastEventId is the global high-water mark, not necessarily a matching event. Comments : heartbeat are emitted every 15 seconds. Disconnects remove listeners and timers; clients falling behind more than 2 MiB of buffered frames are disconnected and can reconnect/replay. A daemon restart or reconnect can lose ephemeral hints, hence the snapshot refresh requirement.

hello#

event: hello
data: {"lastEventId":42,"version":"0.1.0-alpha.2"}

agent#

StoredEvent plus groupId. The ID is global, monotonically increasing while the same database is used, and is unrelated to task or approval numbering.

id: 43
event: agent
data: {"id":43,"sessionId":"web/worker","groupId":"web","ts":"2026-10-07T20:00:00.000Z","event":{"type":"text","text":"Tests passed"}}

AgentEvent variants (all fields below are inside event):

change#

event: change
data: {"kind":"approval","group":"web","session":"web/worker"}

Nonpersistent invalidation hint {kind, group, session?}. These have no ID and cannot be individually resumed. Mutations committed by human RPCs, agent tools, and background drivers all emit hints. Rolled-back transactions emit none. Clients may coalesce bursts.

Quiet notices are agent notice events; refresh session/status snapshots as the UI's clock advances to keep quiet duration current. Locks expire when read, not on a timer.

resync#

event: resync
data: {"reason":"replay_limit","lastEventId":5000}

Reasons are replay_limit (more than 1000 matching retained events after the cursor) or cursor_ahead (cursor beyond the current database's last stored event). Refetch snapshots and transcript tails; for cursor_ahead reconnect without the obsolete cursor. This hint has no ID. Never interpret an incomplete replay as the complete transcript.