# API Reference Complete REST API and WebSocket documentation for Agent Dashboard. --- ## Table of Contents - [Overview](#overview) - [Authentication](#authentication) - [Base URL](#base-url) - [REST API](#rest-api) - [Sessions](#sessions) - [Agents](#agents) - [Tools](#tools) - [Metrics](#metrics) - [Pricing](#pricing) - [Workspaces](#workspaces) - [Notifications](#notifications) - [Remote Data Sources](#remote-data-sources) - [WebSocket API](#websocket-api) - [Error Handling](#error-handling) - [Rate Limiting](#rate-limiting) - [Pagination](#pagination) - [Examples](#examples) --- ## Overview The Agent Dashboard API provides programmatic access to Claude Code session monitoring data. ```mermaid graph LR Client[API Client] -->|HTTP/HTTPS| REST[REST API
:4820/api/*] Client -->|WebSocket| WS[WebSocket
:4820/ws] REST --> DB[(SQLite)] WS --> Broadcast[Real-time
Broadcasts] style REST fill:#10B981 style WS fill:#F59E0B style DB fill:#003B57,color:#fff ``` **Protocols:** - **REST API** - HTTP/JSON for queries and mutations - **WebSocket** - Real-time event streaming --- ## Authentication The server is **local-first** and is hardened to keep the dashboard off the network by default (see GHSA-gr74-4xfh-6jw9). The trust boundary is the loopback bind, layered with origin and host checks: - **Loopback bind by default** — the server binds `127.0.0.1`, so it is not network-reachable out of the box. Operators opt into a wider bind with `DASHBOARD_HOST` (e.g. `DASHBOARD_HOST=0.0.0.0` for LAN access), which logs a startup warning. - **CORS restricted to loopback origins** — cross-origin web pages cannot read API responses. Requests with no `Origin` (curl, server-to-server) still work. - **Host-header allowlist** — both HTTP requests and WebSocket upgrades are checked against an allowlist to block DNS-rebinding. Add extra LAN names (when you bind beyond loopback) via `DASHBOARD_ALLOWED_HOSTS` (comma-separated). For deliberate LAN exposure, set `DASHBOARD_HOST` to a non-loopback address and list the names clients use in `DASHBOARD_ALLOWED_HOSTS`. ### Optional token (`DASHBOARD_TOKEN`) Authentication is **off by default** (the loopback bind is the trust boundary). When `DASHBOARD_TOKEN` is set, every `/api/*` request **and** the WebSocket must present the token. It is strongly recommended whenever you bind beyond loopback. Pass it any of these ways: - `Authorization: Bearer ` header - `x-dashboard-token: ` header - `?token=` query parameter These paths stay exempt even when a token is configured: `/api/health`, `/api/openapi.json`, `/api/docs`, and `/api/hooks` (local Claude Code hook ingestion). Requests that fail the check get `401` with error code `EUNAUTHORIZED`. `GET /api/settings/info` includes `server.version` (the running dashboard release). Pair with `agenthub version` or the Settings About panel to confirm client and server builds match after deploy. ```mermaid sequenceDiagram participant Client participant API participant Auth participant Resource Client->>API: Request + DASHBOARD_TOKEN API->>Auth: Validate token (if configured) Auth-->>API: Valid API->>Resource: Fetch Data Resource-->>API: Return Data API-->>Client: 200 OK + Data ``` --- ## Base URL ``` http://localhost:4820 ``` For production, use HTTPS: ``` https://dashboard.example.com ``` --- ## REST API ### Workspaces Workspace mutations (`POST /api/lanes/ensure`, `POST /api/lanes/worktree`, `PATCH /api/lanes/:id`, confirmed actions, the runtime routes `POST /api/lanes/:id/up`, `/down` and `/hook/:name`, and `DELETE /api/lanes/:id`) enforce the same loopback same-origin guard as `/api/run`: browser requests must originate from `localhost`, `127.0.0.1`, `::1`, or `0.0.0.0`; CLI and curl requests without `Origin` pass. Every workspace object returned by `GET /api/lanes` and `GET /api/lanes/:id` additionally carries the server's stage-detection heuristic (see `docs/LANES.md#stage-detection` for the full rules, and `server/lib/stage-detect.js` for the matcher): - **`detected_stage`** — stage id inferred from ingested tool events, or `null` if no signal has been seen. Independent of the agent's own declared `stage`. - **`detected_signal`** — the capped (≤120 char) tool-event string that produced `detected_stage`; `null` when `detected_stage` is `null`. - **`detected`** (boolean, on each entry of `pipeline_nodes`) — `true` for the inferred node and any node before it that carries no declared record. Decorates that node's existing `state`; **never** upgrades it to `done` — an inferred stage is never evidence. #### Find or adopt the workspace owning a directory ```http POST /api/lanes/ensure ``` ```json { "cwd": "/absolute/path/to/work", "title": "App package", "pipeline": "default", "tool": "codex" } ``` `cwd` is optional — when missing or empty the server falls back to `os.homedir()` (the user's home directory). This is how the Sagi mascot adopts its dedicated workspace without the client needing to know an absolute path. Existing cwd values still pass through unchanged. `pipeline` is optional and, like `title`, applies **only when a workspace is actually created** — an existing workspace is returned untouched. Omitted, the workspace gets `default`. `POST /api/lanes/worktree` and `POST /api/lanes` take the same optional field. `exact: true` makes only a workspace on this very directory count: without it a `cwd` nested inside another workspace returns that parent workspace (`created: false`); with it the nested directory gets a workspace of its own. The Add-workspace modal sends it, and says so when the directory already has a workspace. An id no template defines returns `400 EBADPIPELINE`. `tool` (an AI Tools catalog id, default `"claude"`) is the CLI this workspace's sessions start on unless a start names another (`POST /api/lanes/:id/start` `tool`). Immutable once the workspace is created; an attempt to update it on an existing workspace returns `400 EBADTOOL`. The tool choice appears as an immutable badge on the workspace card (Codex workspaces only). Idempotent lookup by working directory — the Workspace page opens on a `cwd`, not on a workspace id. Returns the workspace whose own `cwd` is that path, or the longest path-boundary parent of it, as `{ "lane": {...}, "created": false }` with `200`. When no workspace owns the path, an `adopted` workspace is created and returned as `{ "lane": {...}, "created": true }` with `201`; `title` is used only in that case. A *relative* `cwd` returns `400 EBADCWD`; a missing or empty `cwd` falls back to the user's home directory instead of erroring. Path boundaries are respected: a workspace at `/tmp/wt` owns `/tmp/wt/pkg` but never `/tmp/wt-sibling`. Two concurrent calls for the same path always yield **one** workspace: the `lanes.cwd` UNIQUE constraint decides the winner, and the loser re-reads and returns the winning workspace rather than reporting a conflict. #### Update a workspace ```http PATCH /api/lanes/:id ``` Partially updates a workspace. This route is same-origin guarded because its patch can set `run_id`. Every patch value must be a **scalar** — a string, a number or `null`. An object, an array or a boolean for any column but `links` (which is stored as JSON and must be an object) is rejected with `400 EBADFIELD`, as is a `NOT NULL` column patched to `null`: such a value reaches SQLite as a datatype or constraint error, which Express could only report as a `500` on what is plainly the caller's mistake. `title` is patchable, which is how the dashboard's inline rename sets a workspace's display name. It is trimmed and capped at 200 characters, and `null` clears it rather than erroring — clearing a title is legitimate, since callers fall back to showing the workspace's `cwd`. Renaming is display-only: a workspace's branch name was slugified from its title once, at creation. `pipeline` is patchable, which is how a workspace moves between templates after creation (`agenthub lanes pipeline `). An id no template defines is rejected with `400 EBADPIPELINE` rather than stored (`default` is always accepted): `getPipeline` falls back to the default template when READING, so an unvalidated write would be accepted and then silently render the wrong map forever. Same 400 treatment as `EBADKIND`. Switching a template re-resolves the workspace's existing declared `stage` string against the new node list — a stage the old template knew may resolve to nothing in the new one, leaving `progress: 0` and no `current` node until the next `agenthub stage`. **Pipelines are dormant until a template is installed.** AgentHub ships no pipeline template; templates come only from `DASHBOARD_PIPELINES_DIR` (see `docs/LANES.md#custom-pipeline-templates`). With none installed, every workspace is on an empty `default` pipeline (`pipeline_nodes: []`, `progress: 0`), `GET /api/lanes/pipelines` returns `{ "pipelines": [] }`, and `POST /api/lanes/:id/stage` answers `400 { "error": { "code": "ENOPIPELINE", "message": "no pipeline template is installed, so this lane has no stages to declare (drop a template into DASHBOARD_PIPELINES_DIR to turn stages on)", "stages": [] } }`. #### Provision a managed worktree ```http POST /api/lanes/worktree ``` Creates a dashboard-owned workspace from an existing absolute git repository. The request returns immediately with `202` and `lane.status: "provisioning"`; the dashboard completes the `git worktree add` in the background and broadcasts the existing `lane_update` message when the workspace becomes `idle` or `failed`. ```json { "sourceRepo": "/absolute/path/to/repository", "title": "Criteria form", "base": "main", "tool": "claude" } ``` `tool` (an AI Tools catalog id, default `"claude"`) is the CLI this workspace's sessions start on unless a start names another (`POST /api/lanes/:id/start` `tool`). Immutable once the workspace is created; an attempt to update it on an existing workspace returns `400 EBADTOOL`. `sourceRepo` must exist, be absolute, and be a git repository with at least one commit — a repo with no commits has nothing to branch from and is refused with `400 EEMPTYREPO` before any workspace row is created (adopt it as a Repo workspace with `POST /api/lanes/ensure` instead, commit, then `publish`). When `base` is omitted, it defaults to the `LANE_BASE_BRANCH` env var, or `main` when that is also unset. The feature branch is named `` (prefix defaults to `feat/`). `title` (or an optional `slug`) determines the safe branch and directory suffix. If that directory already exists, the slug is suffixed with `-2`, `-3`, and so on, up to 50 attempts. A computed cwd that already belongs to another workspace returns `409 EDUPCWD`; exhausting the directory attempts returns `409 EWORKTREEDIRCOLLISION`. A failed provision keeps its managed workspace row with the git diagnostic in `notes`; use `DELETE /api/lanes/:id` to forget that row because no worktree exists to remove. #### Start a workspace's run ```http POST /api/lanes/:id/start ``` Starts a new run in the workspace's working directory, or attaches an existing idle tmux session. Returns the updated workspace. The request body carries: ```json { "prompt": "Write a test for the user endpoint", "model": "claude-opus-5", "permissionMode": "plan", "effort": "medium", "resumeSessionId": "session-xyz", "sandbox": "read-only", "approval": "on-request" } ``` All fields are optional. - **`tool`** — the AI tool THIS session runs on, an AI Tools catalog id (only an id; the command, args and env still come from the catalog file). Omitted = the workspace's own tool. It must be known (`400 EBADTOOL`) and enabled (`400 EDISABLED`); the workspace's own tool is never re-checked, so a workspace on a tool disabled since keeps starting when `tool` is omitted. A resume (`resumeSessionId`, or `resume`) ignores `tool` and keeps the tool its session ran on (`sessions.tool`). The workspace's own `tool` column is unchanged. The run is recorded with its tool (`dashboard_runs.tool`, the run handle's `tool`). When the session's tool is Codex, three fields control Codex-specific behavior: - **`sandbox`** — one of `read-only`, `workspace-write`, or `danger-full-access`, or omitted/empty for no sandbox. Passed to `codex -s `. - **`approval`** — one of `on-request` or `never`, or omitted/empty for no approval prompt. Passed to `codex -a `. - **`resumeSessionId`** or **`resumeLast: true`** — resume an earlier run instead of starting new. For Codex workspaces specifically, `resumeLast: true` uses `codex resume --last`; `resumeSessionId` uses `codex resume `. For Claude workspaces, `resumeSessionId` re-attaches a Claude session by id. - **`forkSession: true`** (with `resumeSessionId`, Claude workspaces only) — resume into a NEW session id (`claude --resume --fork-session`), leaving the original untouched; the run records no session until the fork's first hook. Without `resumeSessionId` it is `400 EBADSESSION`, on any other tool `400 EUNSUPPORTED`. - **`router: ""`** — the AI Router profile THIS session runs on (omitted = native, or for a resume the router its session last ran on); see § AI Router profiles. `400 EBADROUTER` for an unknown name, `400 EUNSUPPORTED` on a tool other than Claude/Codex. - **`worktree: true`** (Claude workspaces, no `resumeSessionId`) — a NEW session in a git worktree of its own, Claude Code's way: the pane runs `claude --worktree=ah--` (the `=` form, since `-w [name]` would take the prompt as the name; the name is made by the server), so Claude itself creates `/.claude/worktrees/` on branch `worktree-`, copies `.worktreeinclude`, runs the user's `WorktreeCreate` hook and cleans up on exit. `/.claude/worktrees/` is added to the repo root's `info/exclude`; the run is recorded with `worktree: 1` (and the run handle carries `worktree: true`). `400 EUNSUPPORTED` on any other tool. A `resumeSessionId` (or fork) of a session that ran in such a worktree starts the pane IN that worktree; one whose worktree is gone is `400 ENOWORKTREE`. - **`slot`** — which Workspace split pane's session to start, `0`–`3` (default `0`, else `400 EBADSLOT`). Slot 0 is the workspace's own `agenthub-lane-` and is what `run_id` records; slots 1–3 are extra sessions on the same workspace, `agenthub-lane--`, and never touch `run_id`/`status`. The response adds `run_id`: the session this start opened. `stop`, `reset` and `remove` kill every slot's session, not only `run_id`. Error `503 ETMUXMISSING` is returned when the host has no `tmux` binary. Every run the dashboard starts is a tmux session, so this is a missing dependency rather than a bad request — the message carries the install command, and the same code comes back from `POST /api/run`. Nothing else in the dashboard is affected. Error `409 ERUNLIVE` is returned if the workspace already has a live run; stop it first with the `stop` action. The same code and status come back when the workspace's tmux pane is already running an agent while a `prompt` or `resumeSessionId` was sent — that argv cannot be typed over a live agent, so the request is refused instead of answered 200 with nothing done. A start that asks for neither still adopts the existing pane silently. #### Preflight a destructive workspace action ```http GET /api/lanes/:id/preflight?action=reset|remove|purge ``` Returns the exact facts a user must confirm. `reset` and `remove` return `head`, `dirty`, `untracked`, `unpushed`, `database`, `blocked`, and `warnings`; `purge` returns `sessions`, `events`, `tokenRows`, `bytesEstimate`, and `activeSessionSkipped`. `expect` is required: reset/remove must include all of `head`, `dirty`, `untracked`, and `unpushed` (not `database` — see below); purge must include `sessions`, `events`, and `tokenRows`. Missing or incomplete confirmation facts return `400 EEXPECT`. `database` is the name a `reset` (unless `keepDb: true`) or `remove` will drop — `null` when the workspace has no slot yet or its profile declares no `DB_PREFIX`. It is not part of the staleness-checked `expect` set: it is derived from the workspace's slot and profile, not from mutable git/session state, so it cannot go stale between preflight and the action. See `docs/LANES.md#data-isolation-database-redis-and-env-a2`. `blocked` reports conditions that affect the action: `adopted` (not a managed worktree), `missing` (directory gone), `unreadable` (directory exists but git failed against it), and `unpushed-commits` (unpushed count > 0 — the only one `force: true` overrides). **Which of them actually prevent the action depends on the action.** They all block `reset`. None of them blocks `remove`: the server forgets an adopted workspace's row, prunes a hand-deleted worktree, and for an unreadable one attempts `git worktree remove --force` — if git itself refuses (e.g. a corrupt worktree `.git` pointer), the server deregisters it directly from the source repo's bookkeeping instead, without ever touching the directory. So for `remove` they are context rather than refusals — a client must not disable confirmation on them. `warnings` holds purely informational facts that never gate the action: currently just `no-remote` (no git remote configured — nothing here is backed up remotely, but the action proceeds). `unpushed` counts the commits the action would actually discard: commits on no remote when remotes exist, otherwise the commits ahead of the workspace's `base_branch` (its own work), falling back to the total commit count only for a workspace with no base at all. A freshly provisioned worktree therefore reports `0`, not the whole repository's history. #### Reset, remove, or purge a workspace ```http POST /api/lanes/:id/reset POST /api/lanes/:id/remove POST /api/lanes/:id/purge ``` All three actions require `{ "confirm": true }` and a complete `expect` object, and run under the workspace lock. They stop the workspace run and wait for the spawned child's actual `exit` event (including the SIGKILL escalation window) before performing the action. A failed spawn is treated as already exited because no child process started or can touch the workspace directory. A child that does not exit returns `500 ERUNTIMEOUT` and does not run git. `reset` and `remove` additionally require `{ "force": true }` when preflight reports `unpushed > 0`. ```json { "confirm": true, "force": true, "keepDb": false, "expect": { "head": "9b3e74a", "dirty": 4, "untracked": 11, "unpushed": 2 } } ``` For `purge`, `expect` contains `sessions`, `events`, and `tokenRows` from its preflight. If any echoed fact changed, the action returns `409 ESTALE` with its `expected` and `current` diagnostics, without resetting, removing, or purging. Missing `force` for unpushed work returns `409 EUNPUSHED`. `reset` restores the managed worktree's feature branch from its base, cleans untracked files but preserves ignored files, clears the workspace stage state, and — when the workspace's profile declares data isolation (`docs/LANES.md#data-isolation-database-redis-and-env-a2`) — refreshes `.env`, re-runs `bootstrap`, clears `LANE_DIRS`, and drops + recreates + migrates + reseeds the database, unless `keepDb: true` is passed (reset only; skips that whole block, leaving the database untouched). `remove` removes the managed git worktree, prunes it, deletes its feature branch, drops the workspace's database and its `_test` sibling (best-effort; never for an adopted workspace), then deletes the workspace row. `purge` returns the deleted counts: ```json { "ok": true, "purged": { "sessions": 2, "events": 14, "tokenRows": 2 } } ``` Only dashboard-managed worktrees can be reset. For `remove`, a managed workspace uses guarded worktree removal and branch deletion; an adopted workspace only has its dashboard row forgotten, and its directory is never changed. `400` preserves `ENOTMANAGED`, `EOUTSIDEROOT`, and `ENOTWORKTREE` guard failures on the managed destroy path. Git failures return `500` with their git `stderr` in `error.stderr`. #### Read a workspace's working copy ```http GET /api/lanes/:id/git ``` What the workspace's directory looks like to git right now: ```json { "available": true, "branch": "feat/rename-metric", "head": "9b3e74a", "unborn": false, "subject": "free-text rule mode in the form", "dirty": 2, "untracked": 1, "files": [ { "path": "server/lib/alerts.js", "status": " M", "added": 12, "deleted": 3 }, { "path": "scratch.txt", "status": "??", "added": null, "deleted": null } ], "hasRemote": true, "upstream": "origin/feat/rename-metric", "ahead": 2, "behind": 1 } ``` - `dirty`, `untracked` and `files` cover only the workspace's own directory, with cwd-relative, unquoted paths — a workspace that is a subdirectory of its repo does not count its siblings' files (the same scoping as `/git/changes`). - A `cwd` that is missing, is not a git repository, or makes git fail returns `{"available": false}` with HTTP **200** — a normal state, not a fault. - A repo with **no commit yet** (a fresh `git init`) is available too: it reports `unborn: true`, `head: null`, `subject: ""` and the branch the first commit will land on. - `files` names the files the counts came from, **capped at 20** (the counts themselves are never capped). `status` is the two-character `git status --porcelain` code; `path` is the new path for a rename. - `added`/`deleted` come from one `git diff --numstat HEAD` — staged and unstaged work together — and are `null` when git has no delta to report: an untracked file, a binary file, a rename, or a repo with no commits yet. - `hasRemote`, `upstream`, `ahead` and `behind` describe the branch's standing against its remote-tracking ref. A branch that has never been pushed reports `upstream: null` with `ahead`/`behind` **null** — not `0`, which would claim "in sync" about a comparison that was never possible. - Not folded into `GET /api/lanes` on purpose: it shells out to git five times, and the workspace list is polled and re-broadcast on every hook. See `docs/LANES.md` for the full treatment. #### Read a workspace's code changes ```http GET /api/lanes/:id/git/changes?range=work|branch|commit[&sha=][&path=][&full=1][&context=N] ``` One route, three depths — the shapes the Workspace's Changes panel asks for: | Query | Shape | Used by | | --- | --- | --- | | *(none)* | every changed file with its counts, no patch text | overview | | `full=1` | the same list, each file carrying its `hunks` | review | | `path=` | that one file, with its `hunks` | single-file view | | `context=N` | the same, with N unchanged lines around each hunk | the viewer's expand button | `range` picks the comparison: `work` (default) is HEAD vs the working tree with untracked files included, `branch` is `...HEAD` for the workspace's `base_branch`, and `commit` shows the single commit named by `sha` (an unresolvable one is `400 EBADREV`, never an empty diff). `context` defaults to **3** and is clamped to **5000** — at the top of that range the diff has effectively become the whole file, which is what "expand all" means in the panel. Every path on the workspace git surface (reads and writes) is **relative to the workspace's `cwd`**, even when that cwd is a subdirectory of its repo: changes outside the cwd are not listed and cannot be named. Paths are literal file names, never pathspec globs — `new*.js` or `app/[id]/page.js` names exactly that file. ```json { "available": true, "range": "work", "base": "development", "baseRef": "origin/development", "sha": null, "context": 3, "truncated": false, "files": [ { "path": "server/lib/git-ops.js", "status": " M", "untracked": false, "staged": false, "unstaged": true, "conflicted": false, "added": 12, "deleted": 3, "binary": false, "hunks": [ { "header": "@@ -1,2 +1,3 @@", "context": "runGitAction", "oldStart": 1, "newStart": 1, "lines": [{ "type": "add", "oldLine": null, "newLine": 2, "text": " const x = 1;" }] } ] } ] } ``` - Each line is already resolved to both gutters (`oldLine`/`newLine`, one of them `null` on an added or removed line), so a client renders rows without re-parsing `@@` headers. - `staged`, `unstaged` and `conflicted` come from the porcelain XY columns and are reported for `range=work` only — they are what the panel's per-file stage/unstage buttons key off. - An **untracked** file has no git-side "before", so its patch is synthesized as one all-added hunk from the file itself. A binary file reports `binary: true` and `hunks: []`. - Three caps guard the response: **300** files listed, **200 KB** of patch per file, **1 MB** of patch in a `full` read. A cap that bit sets `truncated` on the response and on the file it cut. - Read-only, no same-origin guard. `available: false` (HTTP **200**) for a cwd git cannot read; `400 ENOBASE` when `range=branch` on a workspace with no base branch, and `400 ENOFILECHANGE` for a `path` with no changes in that range. #### Read a workspace's commits, a file, or the file tree ```http GET /api/lanes/:id/git/log?limit=30[&file=] GET /api/lanes/:id/git/file?path=[&rev=work|HEAD|] PUT /api/lanes/:id/git/file {path, content, baseSha} GET /api/lanes/:id/git/ls?q= GET /api/lanes/:id/git/tree?path= GET /api/lanes/:id/git/tree-all ``` The reads behind the Changes panel's **History**, whole-file view, quick-open and file explorer. All four are read-only and unguarded, and all four answer `{available:false}` with HTTP **200** for a cwd git cannot read. - **`/git/log`** → `{available, commits:[{sha, short, subject, author, date, refs}]}`, newest first, `limit` clamped to 200. `file=` narrows it to the commits touching that path — relative, no `..` segment, else `400 EBADPATH`. Reading one commit's diff is `/git/changes?range=commit&sha=`. - **`PUT /git/file`** saves the whole-file editor (same-origin guarded; `server/lib/lane-file-write.js`). Same path guards as the read, plus: the file must already exist, be text and within the 1 MB cap, and `baseSha` must equal the `sha` it was opened at — otherwise `409 ESTALE`, never an overwrite. `403 ESECRET` for `settings.local.json`; `400 EBADPATH`, `ENOFILE`, `EBADCONTENT`, `ETOOBIG`, `EBINARY`. Answers the file re-read, fresh `sha` included. CRLF endings and the final newline are preserved. - **`/git/file`** → `{available, path, rev, binary, truncated, lines, sha?}` (`sha` only for a whole, textual `work` file: what a save sends back). `rev=work` (default) is the file on disk — the one branch that reads the filesystem, and it is realpath-confined to the workspace directory (a symlink resolving outside it is `EBADPATH`); anything else goes through `git show :./` (cwd-relative). At EVERY rev the path must be relative with no `..` segment (else `400 EBADPATH`), and it is normalised (`./a//b` → `a/b`, also the `path` echoed back). Binary content is reported, never returned. Capped at 1 MB — a larger file is `truncated: true`, never `ENOFILE` (a working-tree file is read only up to the cap, never whole). `400 EBADPATH`, `EBADREV` or `ENOFILE`. `.claude/settings.local.json` (where a workspace's AI Router key lives) is `403 ESECRET` at EVERY rev and at ANY depth (`sub/.claude/settings.local.json`, a subdirectory workspace's key, as seen from a workspace at the repo root), and so is any path that RESOLVES to it (a symlinked `.claude` → `conf/` makes it `conf/settings.local.json`). In fact ANY file named `settings.local.json`, in any directory and at any rev, is refused — a symlink target's name is all a workspace above it, or a commit of it, ever sees. Its hunks are never returned by `/git/changes` either. - **`/git/ls`** → `{available, paths, truncated, total}`, capped at 500. It reads `git ls-files`, so ignored files never appear and no skip-list has to be maintained; basename hits rank first. - **`/git/tree`** → `{available, path, entries:[{name, path, dir, status?, changed?}], truncated}` — one directory level: tracked files plus untracked ones git does not ignore (`ls-files --cached --others --exclude-standard`), directories folded and listed first. A changed file carries its porcelain `status` (` M`, `??`, `A `, ` D`…), a folder with anything changed under it `changed: true`. `400 EBADPATH` for a path that escapes the workspace. - **`/git/tree-all`** → `{available, levels: {"": [{name, path, dir}]}, truncated}` — every level of the same tree (entries decorated the same way) from ONE `git ls-files`, each level shaped and capped like `/git/tree`'s; the Files tab's **Expand all folders** is this one request instead of one per folder. #### Read a workspace's own branches ```http GET /api/lanes/:id/git/branches ``` `{"available": true, "branches": [...], "current": "feat/x", "worktrees": [...]}` — the local branches of the workspace's own repo, for the branch switcher. The repo comes from the workspace row, never from the query (that is what `GET /api/lanes/branches` is for, which takes a candidate path for a workspace that does not exist yet). #### A session's own worktree (`?session=`) Every `/api/lanes/:id/git…` route above and below takes `?session=`: the read or write then works in that session's worktree instead of the workspace's folder. The tree is resolved from the SESSION ROW (`server/lib/session-worktree.js`): the session must be owned by this workspace (`sessions.lane_id`), its `cwd` must not be the workspace's own folder, and `git worktree list` of the workspace's repo must register it — otherwise `400 ENOWORKTREE`, never a fall back to the main folder. With it, `GET /git` also answers `worktree: {path, branch}`. #### Remove a session's worktree ```http POST /api/lanes/:id/session-worktree/remove ``` Body `{"session": "", "confirm": true}` (same-origin). Claude Desktop's archive of a worktree session: `git worktree remove ` WITHOUT force (git refuses modified or untracked files: `409 EGIT` with git's message), then `git branch -d` of its branch (`-d`, never `-D`: a branch with commits merged nowhere is kept, `branchKept: true`). A lock held by a live process is `409 ELOCKED`; a stale one (the pid in Claude's `claude session (pid …)` reason is gone) is cleared first. A live pane still holding the session is `409 ELIVE`; no `confirm` is `400 ECONFIRM`; a session with no worktree here `400 ENOWORKTREE`. Answers `{removed: true, branch, branchKept}`. #### Act on a workspace's working copy ```http POST /api/lanes/:id/git/:action ``` The git **writes** the dashboard offers. Guarded (same-origin) and serialized per git index (the workspace lock keyed on the worktree's git dir), so a claude and a codex workspace on one cwd — or a root and a subdirectory workspace of one repo — cannot collide on `index.lock`. | Action | Runs | Body | | --- | --- | --- | | `fetch` | `git fetch --all --prune` | — | | `pull` | `git pull --ff-only` | — | | `push` | `git push -u HEAD` — the branch's upstream remote, else the only remote, else `origin`, else `400 ENOREMOTE` | — | | `stage` | `git add -- ` | `{"paths": ["..."]}` | | `unstage` | `git restore --staged -- ` (a staged rename also passes its original path, so both halves unstage) | `{"paths": ["..."]}` | | `discard` | `git restore --source=HEAD --staged --worktree` (tracked) / `git clean -fd` (untracked) | `{"paths": ["..."], "confirm": true}` | | `stage-hunk` | `git apply --cached` of ONE hunk of `git diff -U HEAD -- ` — or, with `block`, of only that hunk's `block`-th run of +/- lines (the other runs folded into context, as an edited `git add -p` hunk) | `{"path": "...", "hunk": "@@ -1,2 +1,3 @@", "block": 0, "context": 3}` | | `discard-hunk` | `git apply -R` of that one hunk (or that one `block` of it), off the working tree | `{"path": "...", "hunk": "@@ ... @@", "block": 0, "context": 3, "confirm": true}` | | `commit` | `git add -A` then `git commit -m `, or the index as it stands with `only: "staged"` | `{"message": "...", "only": "staged"}` | | `switch` | `git switch [-c] ` | `{"branch": "...", "create": false}` | | `branch-create` | `git branch []` — never switches | `{"branch": "...", "base": "..."}` | | `branch-delete` | `git branch -d ` | `{"branch": "..."}` | | `publish` | `git remote add origin -- ` then `git push -u origin HEAD` — only when the repo has NO remote | `{"url": "https://host/owner/repo.git"}` | | `merge` | `git merge --no-edit ` — a local or remote-tracking branch that exists | `{"branch": "origin/main"}` | | `resolve` | a conflicted file: `checkout --ours\|--theirs` + `add`, or `add` once hand-edited (`done`) | `{"path": "...", "side": "ours\|theirs\|done"}` | | `merge-commit` | `git commit --no-edit` — concludes the merge | — | | `merge-abort` | `git merge --abort` | `{"confirm": true}` | ```json { "action": "commit", "ok": true, "output": "[feat/x 9b3e74a] fix: the thing" } ``` - `pull` is **always** `--ff-only` and `switch` refuses a dirty tree (`400 EDIRTY`): neither can invent a merge commit or a conflict underneath a running agent. There is deliberately no rebase, reset or stash here — `reset` stays behind the destroy guard on `POST /api/lanes/:id/reset`. - **Merge** (issue #45) happens only when asked for by name: on a clean tree (`400 EDIRTY`), from a workspace at the repo root (`400 ESUBDIR` — a merge is repo-wide), for a branch listed under `refs/heads` or `refs/remotes` (`400 ENOBRANCH`). A merge that stops on conflicts is still a **200**, with `conflicts: ["path", …]`; a clean one answers `conflicts: []`. While a merge is in progress `pull`, `switch`, `merge`, `stage-hunk` and `discard-hunk` are `409 EMERGING`, and `GET /api/lanes/:id/git` reports `merging: true` plus `conflicts` (unmerged files, repo-wide). `resolve` accepts only a path git reports as conflicted (`400 EBADPATH`) and a `side` of `ours`/`theirs`/`done` (`400 EBADSIDE`); `done` and a plain `stage` of a conflicted file both refuse while a conflict marker is left in it (`400 EMARKERS`). A side that deleted the file resolves by removing it. `merge-commit` is `409 ECONFLICTS` while anything is unmerged, and it and `merge-abort` are `409 ENOMERGE` with no merge in progress. `merge-abort` needs `confirm: true` (`400 ECONFIRM`). - `push` pushes `HEAD`, never a branch name from the request, so a workspace can only push the branch it is on. - A **path** in the body is never trusted as a path: `stage`, `unstage` and `discard` accept only paths `git status` is reporting as changed right now, so `..`, an absolute path and an untouched file are all `400 EBADPATH`. A `commit` without `only: "staged"` sweeps in (`git add -A -- .`) only the workspace cwd's own changes, and is `400 ENOCHANGES` when the workspace has none — even if the repo is dirty elsewhere. - `discard` and `discard-hunk` are the irreversible actions here and both **require** `confirm: true` (`400 ECONFIRM` without it). The UI additionally asks twice. - A hunk is named by its `@@` line and matched against a FRESH diff at the `context` the caller read it with (send the `context` the changes read returned), so a hunk the file has moved past is `409 EHUNKGONE`, never a stale patch applied somewhere else. The path goes through the same `git status` check; an untracked file has no hunks (`400 EUNTRACKED`). A hunk that no longer applies (e.g. part of it is already staged) is `409 EGIT`. - `branch-create` never switches — the usual reason to create one from a workspace is to spawn a sibling worktree workspace, and moving this pane's HEAD under a working agent is not. `branch-delete` is `-d`, never `-D`, and refuses `main`/`master`/`development`/`develop` (`400 EPROTECTED`), the current branch and a branch another worktree holds (`400 EBRANCHBUSY`). - `publish` is the one write whose **destination comes from the request**, so it only ever gives a remote to a repo that has none: `400 ENOCOMMITS` before the first commit, `400 EREMOTEEXISTS` once any remote exists (it never re-points one), and the name is always `origin`. The URL is allowlisted — `https://` with no userinfo (a token in the URL would land in `.git/config`), `ssh://` and scp-like `user@host:path`; a local path, `file://`, `ext::`, `fd::`, `git://`, `http://` and anything starting with `-` are `400 EBADURL`. If the push fails, `origin` is removed again, so a typo or a missing credential can simply be retried. The response adds `"remote": "origin"`. - Bad input is **400** (`EBADACTION`, `EBADMESSAGE`, `EBADBRANCH`, `EBADPATH`, `ECONFIRM`, `EUNTRACKED`, `EPROTECTED`, `ENOBRANCH`, `EBRANCHEXISTS`, `EBRANCHBUSY`, `EDIRTY`, `ENOCHANGES`, `ESTAGEDOUTSIDE`, `ENOREMOTE`, `EBADURL`, `EREMOTEEXISTS`, `ENOCOMMITS`); git itself exiting non-zero (a rejected push, a diverged pull) is **409 `EGIT`** with git's own `stderr` appended to `error.message` — a rejection reads better in git's words. Anything else (git not installed, a timeout kill) is **500**, still under a string code (`EGIT` when there is none) — `error.code` is never git's numeric exit status. - In a workspace whose cwd is a subdirectory of its repo, `commit` refuses with `400 ESTAGEDOUTSIDE` while the index holds a change outside that directory: `git commit` takes the whole index whatever the cwd, and scoping it with a pathspec would commit the working-tree copy (unstaged edits included). - Network actions (`fetch`/`pull`/`push`/`publish`) are killed after 60s so an unreachable remote fails instead of holding the request open. - **A remote that wants a login** (issue #45) is **409 `EGITAUTH`**, not `EGIT`: the dashboard's git has no terminal to prompt in. The error carries `auth: { protocol, host, username, rejected }` — `rejected: true` when a login WAS sent and refused. Resend the same action with `credentials: { protocol, host, username, password, remember }`: accepted only for a host that is one of the repo's own remotes (`400 EBADHOST` otherwise), used for that one command, and saved to AgentHub's store (below) only after git succeeded AND `remember` is true. Empty or multi-line values are `400 EBADCRED`. #### Git credentials ``` GET /api/git-credentials Saved logins: { items: [{ protocol, host, username, savedAt, hasToken }] } POST /api/git-credentials Save or replace — Body: { protocol, host, username, password } DELETE /api/git-credentials/:protocol/:host Delete one (404 ENOTFOUND) ``` AgentHub's OWN git logins, one per `protocol + host`, shared by everyone using this install; the **Git credentials** tab of Settings (`/settings/git-credentials`) and the git bar's login form both write here. Stored in `/agenthub-git-credentials/credentials.json` (dir `0700`, file `0600`). **No response ever carries a password.** Writes are same-origin guarded; a bad protocol/host is `400 EBADHOST`, an empty login `400 EBADCRED`. A network action reaches git with `-c credential.helper= -c credential.helper=` whenever AgentHub holds a login for one of the repo's remote hosts (or the request carries one) — ONLY AgentHub's helper, so a stale token in the machine's helper cannot win over the one just typed, and git's post-success `store` cannot copy a use-once token into the OS user's helper. Otherwise the command is unchanged and the machine's own helpers answer as before. The secret never reaches argv: the helper reads the store file, or a use-once login from its own process env. #### Read a workspace's runtime ```http GET /api/lanes/:id/runtime ``` What is actually running for this workspace, recomputed on every call from pid files and port probes — never cached, because a process can die without telling anyone. See `docs/LANES.md#workspace-runtime-running-a-workspaces-own-stack`. ```json { "available": true, "provisioned": true, "slot": 3, "kind": "managed", "hooks": ["bootstrap", "boot", "health"], "profileDir": "/work/myapp/.agenthub/profile", "services": [{ "name": "api", "pid": 40213, "alive": true }], "ports": { "api": { "port": 8103, "expected": 8003, "listening": true } }, "database": { "name": "myapp_l3", "testName": "myapp_l3_test" }, "redisIndex": 3, "steppedAside": true, "up": true, "healthy": true, "logs": ["boot.log", "health.log", "api.log"], "logDir": "/home/you/.claude/agenthub-lanes/.state/lane3/logs", "lastError": null } ``` - `database` is `null` when the profile declares no `DB_PREFIX`; `redisIndex` is `null` when `REDIS` is not `1`. Both are names/indices only — never a connection string, so this endpoint never leaks the `~/.agenthub/secrets.env` password even though it derives `DATABASE_URL` internally to run hooks. - A workspace whose repository declares no `.agenthub/profile` returns `{"available": false, "searched": [...]}` with HTTP **200** — the same contract as `GET /:id/git`. Most workspaces never run a stack; that is a normal state, not a fault. - A workspace with a profile but no slot yet returns `{"available": true, "provisioned": false, "hooks": [...], "ports": {}}`. - `expected` is `PORT_BASE_ + slot`; when `port` differs, the allocator stepped aside from a number already in use and `steppedAside` is `true`. - Not folded into `GET /api/lanes` on purpose: it opens a socket per declared port and stats every pid file, and the workspace list is polled and re-broadcast on every hook. #### Boot or stop a workspace's stack ```http POST /api/lanes/:id/up { "build": true } POST /api/lanes/:id/down ``` `up` returns **202** and boots in the background, because a build can run for minutes. Progress streams as `lane_hook_output` WebSocket messages and the attempt finishes with a `lane_runtime` message carrying the fresh facts (or an `error`). `build: false` passes `--no-build` to the `boot` hook. `up` runs the profile's `boot` then `health` hooks; it does **not** run `bootstrap`. A failing `health` leaves the processes running so their logs remain readable, and records `EUNHEALTHY` in the runtime's `lastError`. `down` is synchronous, idempotent, and a no-op for a workspace that was never up: ```json { "ok": true, "killed": [40213, 40219], "runtime": { "…": "…" } } ``` Both write only `slot` and `ports` on the workspace row. Neither writes `stage`, `status`, or `notes` — in AgentHub those describe the agent's work, not the stack's state. Adopted workspaces may be brought up and down. Errors: `400 ENOPROFILE` (with the paths searched), `409 ESLOTS` (every slot taken), `409 EPORTBUSY` (with `port` and the occupying `pids`), `404 ENOLANE`. #### Run a profile hook ```http POST /api/lanes/:id/hook/:name { "args": ["--scope", "smoke"] } ``` Runs one of the profile's hooks — the surface a driving session uses for `ci-gate`, `e2e`, `migrate` and friends. Returns **202**; output streams as `lane_hook_output` and completion arrives as `lane_hook_result` with the exit `code`. `:name` is checked against a fixed allowlist (`bootstrap`, `boot`, `health`, `migrate`, `seed`, `ci-gate`, `e2e`, `regen`, `db-create`, `db-drop`) **before** anything is spawned, and `args` travels as an array of strings straight into argv — neither is ever joined into a command string. An unknown name returns `400 ENOHOOK` with the allowed list; a workspace with no slot returns `409 ENOSLOT`. #### Tail a workspace's log ```http GET /api/lanes/:id/logs/:svc?tail=65536 ``` ```json { "available": true, "svc": "api", "size": 20481, "truncated": false, "text": "…" } ``` `tail` is the number of trailing bytes (default 64 KiB, capped at 1 MiB). The resolved path is confined to the workspace's log directory after `realpath`, so a name from the request can never escape it; anything else is `404 ENOLOG`. A workspace with no slot returns `{"available": false}`. #### Workspace features Per-feature state and archive (`server/lib/lane-features.js`) — a workspace's `stage`/`status`/etc. is always the LIVE view of whichever feature it's currently on; these routes read and switch between a workspace's feature history. ```http GET /api/lanes/:id/features ``` Every feature this workspace has ever activated, archived or live, most recently touched first: ```json { "features": [ { "id": 5, "lane_id": 12, "slug": "auth-redesign", "title": "auth-redesign", "branch": "feat/auth", "pipeline": "default", "stage": "implement", "stage_since": "2026-08-04T09:00:00.000Z", "status": "running", "gate_decision": null, "ci_status": null, "qc_dev": null, "stages": {}, "links": {}, "notes": null, "archived_at": null, "created_at": "2026-08-04T09:00:00.000Z", "updated_at": "2026-08-04T09:00:00.000Z", "pipeline_name": "Default", "pipeline_nodes": [ /* same shape as a live lane's */ ], "progress": 40 } ] } ``` Each row is the hydrated `lane_features` row (`stages`/`links` parsed from JSON) plus `pipeline_name`/`pipeline_nodes`/`progress`, computed the exact same way a live workspace's are — the client renders an archived feature with the same `PipelineMap` component, no special-casing. `archived_at` is `null` for the currently-active feature, an ISO timestamp for every past one. `slug` is always the **canonicalized** form (drops a leading `feat/`, turns `/` and whitespace into `-`, keeps `[A-Za-z0-9._-]`, preserves case — **not the same rule as `worktree.js:slugify`**, which lowercases everything). ```http GET /api/lanes/:id/features/:slug ``` One feature by its canonicalized slug, same shape as an entry above, wrapped as `{ "feature": {...} }`. `404 ENOFEATURE` if that slug was never activated on this workspace; `404 ENOLANE` if the workspace itself doesn't exist. ```http POST /api/lanes/:id/features/activate { "slug": "feat/Auth Redesign", "title": "Auth redesign (optional)" } ``` Switches the workspace to a feature by slug: - If a **different** feature is currently active, it is archived first with its exact live state (stage, status, gate/CI fields, stages, links, notes) — its own `title` is never overwritten by this. - If the target slug was activated before, its saved state is restored onto the live workspace (stage, status, gate/CI fields, stages, links, notes) — this is what makes switching back to a past feature resume where it left off. - If the slug is new, a fresh feature row is created (`title` defaults to the slug itself when omitted). - Re-activating the **currently** active slug is a no-op. Response: `{ "lane": , "feature": }`. - **200** — activated (or already active). - **400** `{ "error": { "code": "EBADSLUG", "message": "slug is required" } }` — missing/empty `slug`, or the canonicalized result is empty (e.g. `"feat/"` alone). - **404** `{ "error": { "code": "ENOLANE", "message": "workspace not found" } }`. #### Workspace proof gallery Proof gallery (QC screenshots) captured at `/.playwright-mcp/proof///` and grouped by feature slug (the same slug from per-feature state). Read-only access and deletion are path-contained: every proof file is resolved, realpath'd, and checked to be inside the workspace's proof root before serving or deleting. ```http GET /api/lanes/:id/proof ``` List every feature with proof (or an activated-but-not-yet-shot feature from `lane_features`), most recently touched first: ```json { "features": [ { "slug": "auth-redesign", "groups": { "desktop": ["01-login.png", "02-signup.png"], "mobile": ["01-login.png"] }, "ticket_report": "auth-redesign/ticket/REPORT.html", "mtime": 1722755400 } ] } ``` Each feature has: - **`slug`** (string) — canonicalized feature slug - **`groups`** (object) — `{ "phase": ["image1.png", "image2.png"] }` — phase-groups with their images - **`ticket_report`** (string) — relative path to ticket report HTML, or empty if none exists - **`mtime`** (number) — Unix seconds of the most recent file touched in this feature's proof tree (0 if the feature has no proof yet) **Status codes:** - **200** — success - **404** `{ "error": { "code": "ENOLANE", "message": "workspace not found" } }` — workspace doesn't exist ```http GET /api/lanes/:id/proof/:slug/:group/:file ``` Fetch a single proof file (PNG, JPG, or HTML). The file is resolved with path containment checks before serving: **Status codes:** - **200** — file content, `Content-Type` set to `image/png`, `image/jpeg`, or `text/html` - **404** — workspace, slug, group, or file not found, or path escapes containment ```http DELETE /api/lanes/:id/proof/:slug ``` Delete proof at one of three granularities: request body `{ "group": "phase-name", "images": ["file1.png"] }` deletes specific images from a phase, `{ "group": "phase-name" }` deletes an entire phase, or empty `{}` deletes all phases **except** `ticket/`. ```json { "deleted": 3 } ``` **Status codes:** - **200** — success, returns count of deleted files - **400** `{ "error": { "code": "EBADPATH", "message": "…" } }` — invalid slug, group, or image name; or attempt to delete `ticket/` - **404** `{ "error": { "code": "ENOLANE", "message": "workspace not found" } }` — workspace doesn't exist - **404** `{ "error": { "code": "ENOFEATURE", "message": "…" } }` — slug doesn't exist ```http POST /api/lanes/:id/proof-link ``` Converge the clone-root `proof/` directory (if it exists at `/proof`) onto the canonical `.playwright-mcp/proof`. This is an explicit operation, never automatic — exposed only as `agenthub lanes proof-link`. Idempotent. **Response:** ```json { "linked": true } ``` - **`linked`** (boolean) — `true` if the link was created or fixed, `false` if the symlink already pointed to the right place or a collision was avoided **Status codes:** - **200** — success - **404** `{ "error": { "code": "ENOLANE", "message": "workspace not found" } }` — workspace doesn't exist #### Pipeline pass statistics ```http GET /api/lanes/pipeline-stats ``` How often each pipeline node was actually passed, aggregated over every recorded run and grouped by pipeline template, busiest first. Read from `lane_stage_events`, the append-only log every stage declaration writes — **not** from `lanes.stages`. That blob describes the pass in flight: it is overwritten when a node is re-entered and truncated when the workspace moves backwards, so reading it counted one run per workspace row no matter how many features that workspace shipped, and no amount of use ever moved the numbers. A run is one pass through the template: the log starts a new one when the workspace moves backwards or leaves the template's last node. Templates configured on a workspace are always listed, at zero, even before that workspace records anything — a pipeline going unused has to be visible as such. **Query parameters:** - **`lane`** — workspace id; narrows the aggregation to that workspace's own runs. Omit (or pass `all`) for every workspace. ```json { "pipelines": [ { "id": "default", "name": "Default feature pipeline", "runs": 4, "nodes": [ { "id": "plan", "label": "plan", "icon": "🧭", "gate": false, "entered": 4, "passed": 4, "withEvidence": 4, "failed": 0, "detected": 0 } ] } ], "lanes": [{ "id": 1, "title": "api lane", "cwd": "/w/api" }] } ``` - **`detected`** — runs that reached the node by inference from the hook stream with no declaration. Counted apart from `entered`: it says the work happened, not that the gate was met. A node the hooks saw is reported as such rather than as "never reached", which is what a session that never runs the pipeline commands used to look like. - **`lanes`** — every workspace, for the picker. Never narrowed by `lane`, so the response always offers the way back to the other workspaces. - **`runs`** — workspaces plus archived features recorded against this template. - **`entered`** — stage records that resolve onto this node (aliases included). - **`failed`** — records whose `result` is `"fail"`; **`passed`** is the rest, so `passed + failed === entered`. - **`withEvidence`** — the subset of passes that carry evidence. Tracked apart from `passed` because a claim and a proof are not the same fact — the same distinction the pipeline map draws between `done` and `passed-no-evidence`. **Status codes:** - **200** — success (an empty `pipelines` array when no workspace has recorded a stage yet, or when `lane` names an id that no longer exists) - **400** `{ "error": { "code": "EBADLANE", "message": "lane must be an id" } }` — `lane` is not a positive integer ### Workflows #### Skill and plugin usage ```http GET /api/workflows/skill-usage?status=active|completed ``` Skill invocations counted from `Skill` tool events — `PreToolUse` rows only, since every call also emits a `PostToolUse` and counting both would double every number. `status` filters by session lifecycle, same convention as `GET /api/workflows`; omit it (or pass `all`) for no filter. ```json { "skills": [ { "name": "agenthub:repo-onboarding", "plugin": "agenthub", "count": 12, "sessions": 5 }, { "name": "daily-report", "plugin": null, "count": 3, "sessions": 3 } ], "plugins": [ { "name": "agenthub", "skills": 1, "skillCalls": 12, "mcpCalls": 4 } ] } ``` - **`skills`** — top 30 by call count. `plugin` is the `plugin:skill` prefix, or `null` for a built-in or personal skill. - **`plugins`** — per-plugin totals: distinct skills used, their calls, and calls to the MCP tools that plugin ships (`mcp__plugin____*`), so a plugin used only through MCP does not report zero. **Status codes:** **200** always; **500** with `{ "error": { "message" } }` on a query failure. ### Locks Cross-workspace named locks (`server/lib/named-lock.js`) — the OTHER axis from a workspace's own internal serialization: a name held by one workspace at a time, across ALL workspaces, for a step that thrashes the shared machine (a build, an e2e run). Every route here is **single-shot** — it never blocks waiting for a lock to free up. A caller that wants to wait polls `POST /:name/acquire` itself (the `agenthub lock acquire` CLI does exactly this, printing a status line every ~60s of continued waiting); the server never orchestrates that loop. #### List locks ```http GET /api/locks ``` Every currently-held lock: ```json { "locks": [{ "name": "build", "holder": "lane3", "since": 1722702012, "ageSec": 41 }] } ``` `since` is a Unix **seconds** timestamp; `ageSec` is derived at read time. An empty array means nothing is held. #### Acquire a lock ```http POST /api/locks/:name/acquire { "holder": "lane3" } ``` `holder` is **required** — this route does not default it; `agenthub lock acquire` resolves `lane` for the calling workspace and sends it explicitly. A holder older than `LOCK_MAX_HOLD` (default 2700s, floored at 300s — see `docs/LANES.md#cross-workspace-named-locks`) is broken automatically before the attempt. - **200** `{ "acquired": true }` — lock claimed. - **409** `{ "acquired": false, "holder": "lane1", "since": 1722701900, "ageSec": 150 }` — already held by someone else (fresh enough not to be broken). - **400** `{ "error": { "code": "EBADHOLDER", "message": "holder is required" } }` — missing/empty `holder`. #### Release a lock ```http POST /api/locks/:name/release { "holder": "lane3" } ``` - **200** `{ "ok": true }` — released. - **409** `{ "error": { "code": "ENOTHOLDER", "message": "...", "currentHolder": "lane1" } }` — `holder` doesn't match the current owner; a release never trusts its caller, same rule every other destructive path in this project follows. - **404** `{ "error": { "code": "ENOLOCK", "message": "no such lock: build" } }` — nothing by that name is held. #### Workspace context: instructions, folders, context files, memory ```http GET /api/lanes/:id/sources PUT /api/lanes/:id/instructions {"instructions": "…" | null} POST /api/lanes/:id/sources/folder {"path": "/abs/dir"} POST /api/lanes/:id/sources/file raw body, Content-Type: application/octet-stream, X-File-Name: DELETE /api/lanes/:id/sources/:sourceId GET /api/lanes/:id/memory ``` What a workspace's home page edits (`server/lib/lane-sources.js`, `server/routes/lane-sources.js`). `GET …/sources` and every write answer the same view: ```jsonc { "instructions": "Always answer in Vietnamese.", "supported": true, // the workspace's tool can take them (claude, codex) "maxFileBytes": 10485760, "maxInstructions": 16000, "sources": [ { "id": 3, "kind": "folder", "path": "/home/u/shared", "name": "shared", "size": null, "added_at": "…", "missing": false }, { "id": 4, "kind": "file", "path": "/workspace-context/12/spec.pdf", "name": "spec.pdf", "size": 20480, "added_at": "…", "missing": false } ] } ``` - **Instructions** — the `instructions` key is required (`400 EBADFIELD` without it), a string or `null`; blank clears; over 16 000 characters is `413 ETOOBIG`. The lane is re-broadcast (`lane_update`). The text is stored in `lanes.instructions` but is NOT part of the lane payload (`GET /api/lanes`, `lane_update`) — read it here. - **Folder** — must be absolute, exist and be a directory (`400 EBADPATH`), must not be or contain the OS home (`400 EBADHOME`), and must not be the workspace's own folder or one it already has (`400 EDUP`). Stored by real path. Removing it only drops the row. - **File** — up to 10 MB (`413 ETOOBIG`), not empty (`400 EEMPTY`). AgentHub stores it under `/workspace-context//` with a name it derives from `X-File-Name` (directory parts and path characters dropped, `name (2).ext` on a clash), so a request never names a path. Removing it deletes that copy. At most 50 sources per workspace (`400 ETOOMANY`). - **Memory** — read-only: the folder's `CLAUDE.md`, `.claude/CLAUDE.md`, `CLAUDE.local.md`, `AGENTS.md`, and for a Claude workspace `/projects//memory/*.md` — `{files: [{label, path, size, mtime, truncated, content}]}`, each at most 256 KB of content. - Every write is same-origin only (`403 EBADORIGIN`); an unknown workspace is `404 ENOLANE`, an unknown source `404 ENOSOURCE`. At spawn (`spawnRun`, both `POST /api/lanes/:id/start` and `POST /api/run`) the pane gets, from these rows: Claude — `--add-dir []` first, then `--append-system-prompt-file=/workspace-prompts/.md`, a file rewritten at every spawn holding the instructions + the context file list + the extra folders; Codex — one `--add-dir ` per folder (and the context dir) and `-c developer_instructions=` (above 6 KB as the escaped TOML string, one line pointing at that file instead; nothing when that file could not be written). Any other tool gets none of it (`supported: false`). A folder or file that vanished is skipped. #### Projects (workspaces grouped by repository) ```http GET /api/projects POST /api/projects/refresh ``` Every workspace grouped under the git repository it belongs to; a workspace home's **Add folder** suggests the untracked worktrees of its own repo from it. A project's `root` is the repo's MAIN worktree top level (`git rev-parse --git-common-dir`, realpath); workspaces outside any repo form the `root: null` pseudo-project, listed last. `worktrees` is `git worktree list` for that repo (a worktree whose directory is gone is left out); `workspace_id` is the lane sitting exactly on that path, else `null` — an **untracked worktree** the UI offers to adopt. A lane on a subdirectory of a worktree is in `workspaces` but marks no worktree. `source` is `"claude"` under `/.claude/worktrees/`, `"agenthub"` under `LANES_ROOT`, else absent. ```jsonc { "projects": [ { "root": "/home/u/agenthub", "name": "agenthub", "workspaces": [12, 15], "worktrees": [ { "path": "/home/u/agenthub", "branch": "main", "main": true, "workspace_id": 12 }, { "path": "/home/u/agenthub/.claude/worktrees/wf-1", "branch": "wf-1", "main": false, "workspace_id": null, "source": "claude" } ] }, { "root": null, "name": "Folders", "workspaces": [3], "worktrees": [] } ] } ``` Both git reads are cached in memory — a directory's root for the life of the server, a repo's worktree list for 30 s — and the lane ↔ worktree match is recomputed on every call, so a new or removed workspace needs no invalidation. This route is read on demand (a workspace home's Add folder suggestions), never on the polled `GET /api/lanes`. `POST /api/projects/refresh` drops both caches first and answers the same shape; it is same-origin only (`403 EBADORIGIN`). ### Sessions #### List Sessions ```http GET /api/sessions ``` Returns all sessions, ordered by most recent activity. **Query Parameters:** | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `limit` | integer | 50 | Maximum sessions to return (1-1000) | | `offset` | integer | 0 | Pagination offset | | `status` | string | - | Filter by persisted status: `active`, `completed`, `error`, `abandoned`. The UI **Waiting** state is derived from the `awaiting_input_since` column and is not a queryable enum — filter `status=active` and inspect `awaiting_input_since` (non-null = Waiting) | | `cwd` | string | - | Exact working directory | | `tool` | string | - | One CLI's sessions: `claude`, `codex`, `antigravity` | | `lane` | integer | - | The sessions a workspace OWNS (`sessions.lane_id`): the ones its panes held. `400 INVALID_INPUT` when not an id | | `archived` | `0` \| `1` | - | `0` = not archived, `1` = archived only; omitted = both | | `sources` | string | - | Comma-separated data-source ids to include (the built-in local history is `local`; remote SSH machines use their `remote_sources.id`). Omit for all sources. Also accepted on `/api/events`, `/api/agents`, `/api/stats`, `/api/analytics`, and `/api/pricing/cost`. See [Remote Data Sources](#remote-data-sources) | **Example Request:** ```bash curl http://localhost:4820/api/sessions?limit=10&status=active ``` **Example Response:** ```json { "sessions": [ { "id": 1, "session_id": "sess_abc123", "model": "claude-sonnet-4", "status": "active", "total_cost": 1.23, "agent_count": 3, "tool_count": 12, "created_at": "2024-03-18T12:00:00Z", "updated_at": "2024-03-18T14:30:00Z" } ], "total": 42, "limit": 10, "offset": 0 } ``` **Response Schema:** ```mermaid classDiagram class SessionListResponse { +Session[] sessions +number total +number limit +number offset } class Session { +string id +string name +string status "active|completed|error|abandoned" +string cwd +string model +string started_at +string ended_at +string updated_at +string awaiting_input_since "null unless Waiting" +string awaiting_reason "notification|stop|session_start|interrupted; null unless Waiting" +number lane_id "owning workspace; null if none" +string archived_at "null unless archived" +number cost +number agent_count } SessionListResponse --> Session ``` --- #### Update Session ```http PATCH /api/sessions/:id ``` Body: any of `name`, `status`, `ended_at`, `metadata` and `archived`. `archived` (boolean, else `400 INVALID_INPUT`) sets or clears `archived_at`: the session leaves its workspace's lists and nothing is deleted. Ownership (`lane_id`) is not patchable: `bindRunSession` (`server/routes/hooks.js`) stamps the session a dashboard pane holds with that pane's lane, first writer wins. Returns `{ session }`. --- #### Get Session ```http GET /api/sessions/:id ``` Returns single session details. **Path Parameters:** | Parameter | Type | Description | |-----------|------|-------------| | `id` | string | Session ID (e.g., `sess_abc123`) | **Example Request:** ```bash curl http://localhost:4820/api/sessions/sess_abc123 ``` **Example Response:** ```json { "session": { "id": 1, "session_id": "sess_abc123", "model": "claude-sonnet-4", "status": "active", "total_cost": 1.23, "created_at": "2024-03-18T12:00:00Z", "updated_at": "2024-03-18T14:30:00Z" } } ``` **Error Responses:** | Code | Description | |------|-------------| | 404 | Session not found | | 500 | Internal server error | --- #### Get Session Stats ```http GET /api/sessions/:id/stats ``` Returns aggregated counts powering the Session Detail overview panel. All aggregation runs in SQL — the response is cheap to compute even for sessions with tens of thousands of events. **Path Parameters:** | Parameter | Type | Description | |-----------|------|-------------| | `id` | string | Session ID | **Example Request:** ```bash curl http://localhost:4820/api/sessions/sess_abc123/stats ``` **Example Response:** ```json { "session_id": "sess_abc123", "total_events": 14082, "events_by_type": [ { "event_type": "PreToolUse", "count": 5210 }, { "event_type": "PostToolUse", "count": 5208 } ], "tools_used": [ { "tool_name": "Bash", "count": 1842 }, { "tool_name": "Read", "count": 1340 } ], "error_count": 12, "first_event_at": "2026-04-26T18:59:00.000Z", "last_event_at": "2026-04-29T21:30:14.000Z", "agents": { "total": 12, "main": 1, "subagent": 11, "compaction": 5, "by_status": { "completed": 11, "working": 1 } }, "subagent_types": [ { "subagent_type": "Explore", "count": 4 } ], "tokens": { "input_tokens": 1376, "output_tokens": 760304, "cache_read_tokens": 337641891, "cache_write_tokens": 5126047 } } ``` **Error Responses:** | Code | Description | |------|-------------| | 404 | Session not found | | 500 | Internal server error | --- #### Get Session Agents ```http GET /api/sessions/:id/agents ``` Returns all agents for a session. **Path Parameters:** | Parameter | Type | Description | |-----------|------|-------------| | `id` | string | Session ID | **Example Request:** ```bash curl http://localhost:4820/api/sessions/sess_abc123/agents ``` **Example Response:** ```json { "agents": [ { "id": "sess_abc123-main", "session_id": "sess_abc123", "name": "Main Agent - my-project", "type": "main", "subagent_type": null, "status": "idle", "current_tool": null, "task": null, "started_at": "2024-03-18T12:00:00Z", "ended_at": null, "updated_at": "2024-03-18T12:05:00Z", "parent_agent_id": null, "awaiting_input_since": "2024-03-18T12:05:00Z", "awaiting_reason": "stop", "cost": 0 } ] } ``` > **Note on `cost`** — `/api/agents` and `/api/sessions/:id/agents` attach a `cost` (USD) to each agent: the agent's **own** cost, computed server-side from the per-agent token buckets stored in `agents.metadata.tokens` and priced at the current pricing rules (at the agent's start date, so promo/standard cutovers apply — see [Pricing](#pricing)). It is `0` for main agents (whose cost is the session total, reported by `/api/pricing/cost/:sessionId`), for compaction pseudo-agents, and for any subagent whose transcript is unavailable. This lets a subagent card show only what that subagent spent instead of the whole session's total. > **Note on `status` vs Waiting** — agents are persisted with one of `idle | connected | working | completed | error`. The yellow **Waiting** badge surfaced in the dashboard is a UI overlay derived from `awaiting_input_since` being non-null on a non-terminal agent (typically `idle` after a `Stop`, or `connected` right after `SessionStart`). Filter `?status=idle` on `/api/agents` and inspect `awaiting_input_since` to enumerate currently-waiting main agents. --- ### Agents #### Get Agent ```http GET /api/agents/:id ``` Returns single agent details. **Path Parameters:** | Parameter | Type | Description | |-----------|------|-------------| | `id` | string | Agent ID (e.g., `agent_xyz789`) | **Example Request:** ```bash curl http://localhost:4820/api/agents/agent_xyz789 ``` **Example Response:** ```json { "agent": { "id": 1, "agent_id": "agent_xyz789", "session_id": "sess_abc123", "agent_type": "explore", "status": "completed", "current_tool": null, "input_tokens": 1500, "output_tokens": 800, "cost": 0.45, "created_at": "2024-03-18T12:00:00Z", "updated_at": "2024-03-18T12:05:00Z" } } ``` --- #### Get Agent Tools ```http GET /api/agents/:id/tools ``` Returns tool executions for an agent. **Path Parameters:** | Parameter | Type | Description | |-----------|------|-------------| | `id` | string | Agent ID | **Example Request:** ```bash curl http://localhost:4820/api/agents/agent_xyz789/tools ``` **Example Response:** ```json { "tools": [ { "id": 1, "agent_id": "agent_xyz789", "tool_name": "bash", "duration_ms": 1234, "success": 1, "error_message": null, "created_at": "2024-03-18T12:01:00Z" }, { "id": 2, "agent_id": "agent_xyz789", "tool_name": "view", "duration_ms": 45, "success": 1, "error_message": null, "created_at": "2024-03-18T12:02:00Z" } ] } ``` **Tool Execution Flow:** ```mermaid sequenceDiagram participant Agent participant PreHook as PreToolUse Hook participant Tool as Tool Execution participant PostHook as PostToolUse Hook participant DB as Database Agent->>PreHook: Tool about to execute PreHook->>DB: Set current_tool Agent->>Tool: Execute (bash, view, etc.) Tool-->>Agent: Result Agent->>PostHook: Tool completed PostHook->>DB: Create tool_execution record PostHook->>DB: Clear current_tool PostHook->>DB: Update token counts + cost ``` --- ### Tools #### List All Tools ```http GET /api/tools ``` Returns all tool executions across all sessions. **Query Parameters:** | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `limit` | integer | 100 | Max tools to return | | `tool_name` | string | - | Filter by tool name | | `success` | boolean | - | Filter by success status | **Example Request:** ```bash curl http://localhost:4820/api/tools?limit=50&tool_name=bash ``` **Example Response:** ```json { "tools": [ { "id": 1, "agent_id": "agent_xyz789", "tool_name": "bash", "duration_ms": 1234, "success": 1, "error_message": null, "created_at": "2024-03-18T12:01:00Z" } ], "total": 156 } ``` --- ### Metrics #### Prometheus exposition ``` GET /api/metrics ``` Exposes the dashboard's live counters in the [Prometheus text-exposition format](https://prometheus.io/docs/instrumenting/exposition_formats/) (v0.0.4) so this monitoring dashboard can itself be scraped into Prometheus / Grafana. Read-only. Values are read from the same prepared statements the REST API uses, so they match the UI. Response `Content-Type: text/plain; version=0.0.4; charset=utf-8`. | Metric | Type | Labels | Meaning | | --- | --- | --- | --- | | `agenthub_up` | gauge | — | `1` when the API served the scrape | | `agenthub_build_info` | gauge | `version` | Always `1`; dashboard version rides on the label | | `agenthub_process_uptime_seconds` | gauge | — | Server process uptime | | `agenthub_process_resident_memory_bytes` | gauge | — | Server process RSS | | `agenthub_sessions` | gauge | `status` (`active`/`completed`/`error`/`abandoned`) | Sessions by status | | `agenthub_agents` | gauge | `status` (`working`/`waiting`/`completed`/`error`) | Agents by status | | `agenthub_events_total` | counter | — | Total events recorded | | `agenthub_websocket_clients` | gauge | — | Connected realtime clients | | `agenthub_remote_sources` | gauge | `enabled` (`true`/`false`) | Configured Remote Data Sources | | `agenthub_tokens_total` | counter | `kind` (`input`/`output`/`cache_read`/`cache_write`) | Cumulative token usage | Status series are always emitted (even at `0`) so a series never disappears from the exposition. The endpoint is mounted under `/api`, so it sits behind the same two guards as every other route: the **Host-header (DNS-rebinding) guard** and the optional **`DASHBOARD_TOKEN`** guard. A scraper that reaches the server as anything other than loopback (e.g. Prometheus in Docker hitting `host.docker.internal`) must be allowlisted with `DASHBOARD_ALLOWED_HOSTS`, or the scrape returns `403 EBADHOST`; if a token is set, the scrape must also send it. Example scrape config (start the server with `DASHBOARD_ALLOWED_HOSTS=host.docker.internal`): ```yaml scrape_configs: - job_name: agenthub metrics_path: /api/metrics static_configs: - targets: ["host.docker.internal:4820"] # authorization: # only if DASHBOARD_TOKEN is set # credentials: "" ``` --- ### Pricing #### List Pricing Rules ```http GET /api/pricing ``` Returns all pricing rules (default + custom). **Example Request:** ```bash curl http://localhost:4820/api/pricing ``` **Example Response:** ```json { "rules": [ { "id": 1, "pattern": "claude-sonnet-4", "input_cost_per_1m": 3.0, "output_cost_per_1m": 15.0, "is_default": true, "created_at": "2024-03-18T12:00:00Z" }, { "id": 10, "pattern": "gpt-5.1-codex", "input_cost_per_1m": 2.5, "output_cost_per_1m": 10.0, "is_default": false, "created_at": "2024-03-18T14:30:00Z" } ] } ``` **Pricing Rule Matching:** ```mermaid graph TB Model[Model Name
e.g., claude-sonnet-4] --> Match{Match Pattern?} Match -->|Exact Match| Custom[Use Custom Rule] Match -->|Substring Match| Default[Use Default Rule] Match -->|No Match| Fallback[Use Generic Fallback] Custom --> Calculate[Calculate Cost] Default --> Calculate Fallback --> Calculate Calculate --> Result[input_cost + output_cost] style Calculate fill:#10B981 ``` --- #### Create or Update Pricing Rule ```http PUT /api/pricing ``` Upsert a pricing rule, keyed by `model_pattern`. The same call creates a new rule or updates an existing one (matched on `model_pattern`). Rates are per **million** tokens. **Request Body:** ```json { "model_pattern": "claude-sonnet-5%", "display_name": "Claude Sonnet 5", "input_per_mtok": 3, "output_per_mtok": 15, "cache_read_per_mtok": 0.3, "cache_write_per_mtok": 3.75, "cache_write_1h_per_mtok": 6, "fast_input_per_mtok": 0, "fast_output_per_mtok": 0, "intro_until": "2026-08-31", "intro_input_per_mtok": 2, "intro_output_per_mtok": 10, "intro_cache_read_per_mtok": 0.2, "intro_cache_write_per_mtok": 2.5, "intro_cache_write_1h_per_mtok": 4 } ``` **Fields:** | Field | Type | Constraints | |-------|------|-------------| | `model_pattern` | string | Required. SQL-style glob; `%` matches any characters (e.g. `claude-opus-4-7%`) | | `display_name` | string | Required | | `input_per_mtok` / `output_per_mtok` | number | Standard per-MTok rates (default 0) | | `cache_read_per_mtok` / `cache_write_per_mtok` / `cache_write_1h_per_mtok` | number | Cache rates (default 0) | | `fast_input_per_mtok` / `fast_output_per_mtok` | number | Fast-mode premium rates (default 0) | | `intro_until` | string \| null | Optional promo cutoff `YYYY-MM-DD`. Usage **on or before** this date is priced at the `intro_*` rates, after it at the standard rates. Empty/`null` clears the promo (and zeroes the intro rates) | | `intro_*_per_mtok` | number | Optional introductory (promo) rates, mirroring the standard fields | The intro block is **optional and backward-compatible**: a request that omits every `intro_*`/`intro_until` field leaves any existing promo untouched, so older clients that send only the standard rates never clobber a promo. **Validation:** every `*_per_mtok` rate present in the body must be a **non-negative finite number** (numeric strings are coerced); a `NaN`, non-numeric, or negative value is rejected with `400 INVALID_INPUT` naming the offending field, and nothing is written. `intro_until` must be a `YYYY-MM-DD` date (or empty/`null` to clear the promo). **Example Request:** ```bash curl -X PUT http://localhost:4820/api/pricing \ -H "Content-Type: application/json" \ -d '{ "model_pattern": "gpt-5.1-codex", "display_name": "GPT-5.1 Codex", "input_per_mtok": 2.5, "output_per_mtok": 10.0 }' ``` **Example Response:** ```json { "pricing": { "model_pattern": "gpt-5.1-codex", "display_name": "GPT-5.1 Codex", "input_per_mtok": 2.5, "output_per_mtok": 10.0, "intro_until": null, "updated_at": "2026-07-01T14:30:00Z" } } ``` **Error Responses:** | Code | Description | |------|-------------| | 400 | Missing `model_pattern`/`display_name`, or `intro_until` not a `YYYY-MM-DD` date | | 500 | Database error | --- #### Delete Pricing Rule ```http DELETE /api/pricing/:pattern ``` Delete custom pricing rule (default rules cannot be deleted). **Path Parameters:** | Parameter | Type | Description | |-----------|------|-------------| | `pattern` | string | Pattern to delete (URL-encoded) | **Example Request:** ```bash # Pattern must be URL-encoded curl -X DELETE http://localhost:4820/api/pricing/gpt-5.1-codex ``` **Example Response:** ```json { "deleted": true } ``` **Error Responses:** | Code | Description | |------|-------------| | 404 | Pattern not found | | 403 | Cannot delete default rule | | 500 | Database error | --- ### Notifications #### Get Session Notifications ```http GET /api/sessions/:id/notifications ``` Returns notifications for a session. **Path Parameters:** | Parameter | Type | Description | |-----------|------|-------------| | `id` | string | Session ID | **Example Request:** ```bash curl http://localhost:4820/api/sessions/sess_abc123/notifications ``` **Example Response:** ```json { "notifications": [ { "id": 1, "session_id": "sess_abc123", "notification_type": "backgroundTaskComplete", "message": "Explore agent completed", "created_at": "2024-03-18T12:05:00Z" } ] } ``` ### Remote Data Sources The `/api/remote-sources/*` namespace configures **remote SSH machines** the dashboard pulls Claude Code history from, so one dashboard can consolidate sessions from several machines. **No secrets are stored** — SSH authentication defers entirely to the host's SSH stack (ssh-agent, `~/.ssh/config`, key files). Every imported session is tagged with the source's id in the `sessions.source` column (the built-in local history uses the id `local`), which powers the `sources` filter below. **RemoteSource shape:** ```json { "id": "4d1f0e2a-7b9c-4c33-8a21-9e0f7b6d4c11", "label": "Work laptop", "host": "son@studio.local", "ssh_port": 22, "identity_file": "~/.ssh/id_ed25519", "remote_home": "~/.claude", "enabled": true, "status": "ok", "last_error": null, "last_sync_at": "2026-07-22T18:41:55.117Z", "last_sync_counts": { "imported": 9, "skipped": 41, "backfilled": 0, "errors": 0, "sessions_seen": 50, "sessions_tagged": 50 }, "created_at": "2026-07-20T09:15:00.000Z", "updated_at": "2026-07-22T18:41:55.117Z" } ``` `ssh_port`, `identity_file`, `remote_home`, `last_error`, `last_sync_at`, and `last_sync_counts` are nullable. `status` is one of `idle`, `syncing`, `ok`, `error`. #### List Remote Sources ```http GET /api/remote-sources ``` Returns all configured remote sources. Response: `{ "sources": RemoteSource[] }`. #### Create Remote Source ```http POST /api/remote-sources ``` **Request Body:** | Field | Type | Required | Description | |-------|------|----------|-------------| | `label` | string | Yes | Human-readable name | | `host` | string | Yes | SSH destination (`user@host`) or a `~/.ssh/config` alias | | `ssh_port` | integer | No | SSH port (defers to SSH default / config when omitted) | | `identity_file` | string | No | Private-key path passed to ssh (`-i`) | | `remote_home` | string | No | Remote Claude home (defaults to remote `~/.claude`) | > **Cursor (informational):** Sessions imported from `~/.claude` include **Cursor** agent usage on that machine too — Cursor happens to use the same paths as Claude Code. AgentHub does not tag which app created a session. | `enabled` | boolean | No | Whether the source is eligible for syncs (default `true`) | Returns `{ "source": RemoteSource }` with HTTP **201**. **Error Responses (400):** `{ "error": { "code", "message" } }` with one of: | Code | Meaning | |------|---------| | `INVALID_LABEL` | Missing/blank `label` | | `INVALID_HOST` | Missing/invalid `host` | | `INVALID_PORT` | `ssh_port` out of range | | `INVALID_IDENTITY_FILE` | Invalid `identity_file` value | | `INVALID_REMOTE_HOME` | Invalid `remote_home` value | #### Update Remote Source ```http PATCH /api/remote-sources/:id ``` Partial update — only the keys present in the body change. Same fields (and the same validation codes) as create; both `label` and `host` are optional here. Returns `{ "source": RemoteSource }`, or **404** if the id is unknown. #### Delete Remote Source ```http DELETE /api/remote-sources/:id ``` **Query Parameters:** | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `purge` | boolean | `false` | When `true`, also delete this source's imported sessions. When omitted/`false`, those sessions are **detached** — reassigned to the `local` source so history is preserved | Returns `{ "ok": true, "purged": }` (`purged` is `true` only when `?purge=true` deleted the sessions). **404** if the id is unknown. #### Test Remote Source ```http POST /api/remote-sources/:id/test ``` Runs an SSH connectivity probe. Returns `{ "ok": , "message": , "remoteProjects?": string[] }` — `remoteProjects` lists the discovered remote project directories on success. Does not import anything. **404** if the id is unknown. #### Sync Remote Source ```http POST /api/remote-sources/:id/sync ``` Pulls Claude Code history from the remote over SSH now, through the same idempotent import pipeline used locally, tagging imported sessions with this source's id. Progress/completion is also broadcast over the WebSocket as [`remote_source.status`](#remote_sourcestatus) frames. **Example Response:** ```json { "ok": true, "imported": 9, "skipped": 41, "backfilled": 0, "errors": 0, "sessions_seen": 50, "sessions_tagged": 50 } ``` **404** if the id is unknown; **500** with `{ error: { code: "SYNC_FAILED", message } }` on SSH/import failure. #### Sync All Remote Sources ```http POST /api/remote-sources/sync-all ``` Pulls history from **every enabled** source sequentially (one SSH connection at a time). Per-source failures are isolated — one unreachable machine never aborts the others — and each outcome is returned in `results`. Always **200**. **Example Response:** ```json { "ok": true, "synced": 2, "results": [{ "id": "src_a", "ok": true }, { "id": "src_b", "ok": false, "error": "ssh exited with code 255" }] } ``` #### The `sources` filter `GET /api/sessions`, `/api/events`, `/api/agents`, `/api/stats`, and `/api/analytics` accept an optional `sources` query parameter: a comma-separated list of source ids to include (omit for all). `GET /api/sessions/facets` correspondingly returns a `sources: string[]` array (alongside `cwds`) listing the distinct `sessions.source` values so the UI can build the filter dropdown. ```bash curl "http://localhost:4820/api/sessions?sources=local,4d1f0e2a-7b9c-4c33-8a21-9e0f7b6d4c11" ``` --- ### Claude Config Explorer The `/api/cc-config/*` namespace powers the Claude Config Explorer, now the **Claude Code** tab of Settings (`/settings/agents/claude-code`). All read endpoints are pure file reads under `CLAUDE_HOME` and the project's `.claude/` dir. File mutations cover the low-risk text-file artifacts (skills, subagents, slash commands, output styles, memory), `keybindings.json`, and `settings.json` layers **via a per-key merge only** — each always creates a timestamped backup before writing. Plugin/marketplace management and MCP server add/remove are delegated to the `claude plugin …` / `claude mcp …` CLI, because `~/.claude.json` and the plugin manifests are rewritten concurrently by the running Claude Code CLI. ```http GET /api/cc-config/overview GET /api/cc-config/skills?scope=user|project|all&cwd= GET /api/cc-config/agents GET /api/cc-config/commands?scope=user|project|all&cwd= GET /api/cc-config/output-styles GET /api/cc-config/plugins GET /api/cc-config/marketplaces GET /api/cc-config/mcp GET /api/cc-config/hooks GET /api/cc-config/hook-scripts GET /api/cc-config/keybindings PUT /api/cc-config/keybindings Body: { groups: [{ context, bindings: [{ key, action }] }] } GET /api/cc-config/statusline GET /api/cc-config/settings GET /api/cc-config/memory GET /api/cc-config/file?path= GET /api/cc-config/backups[?scope=&type=] GET /api/cc-config/profiles POST /api/cc-config/profiles Body: { name? } PATCH /api/cc-config/profiles Body: { name, label } POST /api/cc-config/profiles/activate Body: { name } POST /api/cc-config/profiles/usage Body: { name } DELETE /api/cc-config/profiles Body: { name } PUT /api/cc-config/file Body: { scope, type, name?, content } DELETE /api/cc-config/file Body: { scope, type, name? } POST /api/cc-config/project-memory Body: { dir, content } PATCH /api/cc-config/settings Body: { scope, set?: { "dotted.key": value }, unset?: ["dotted.key"] } GET /api/cc-config/plugins/available POST /api/cc-config/plugins/install Body: { spec, scope? } POST /api/cc-config/plugins/action Body: { key, action: enable|disable|update|uninstall, reload? } GET /api/cc-config/plugins/update-all POST /api/cc-config/plugins/update-all Body: { reload? } POST /api/cc-config/reload Body: { kinds?: ["plugins"|"skills"] } POST /api/cc-config/marketplaces/add Body: { source, scope? } POST /api/cc-config/marketplaces/action Body: { name, action: update|remove } POST /api/cc-config/mcp/add Body: { name, scope, transport?, url?, headers?, command?, args?, env? } POST /api/cc-config/mcp/remove Body: { name, scope? } ``` The list reads take an optional `cwd` naming the project whose `.claude/` is read (default: the server's own cwd); the run console's `/` autocomplete passes the directory the run will start in, so a workspace's own project commands and skills are the ones offered. `scope` is `"user"`, `"project"`, or `"auto-memory"`. `type` is one of `skills`, `agents`, `commands`, `output-styles`, `memory`, `auto-memory`. `name` is required for everything except `memory` (which is `CLAUDE.md` itself). On `PUT`, `name` is validated against `^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$` (for `auto-memory` it must instead be a flat `*.md` filename). Settings are returned with secret-like keys (matching `/token|secret|password|api[_-]?key|auth/i`) replaced by `""`. `GET /api/cc-config/plugins` returns each installed plugin's `contributes` block: the `skills` / `agents` / `commands` / `outputStyles` / `hooks` counts, plus `contributes.items` listing the first four surfaces **by name** (`[{ name, description, file }]`) so the UI can show *which* artifacts a plugin ships, not only how many. `name` is the file's frontmatter `name` when it declares one — the string Claude Code actually addresses it by — otherwise the filename. Each surface covers both the conventional directory (`skills/`, `agents/`, `commands/`, `output-styles/`) **and** any path `plugin.json` declares under that key: a plugin that lists its commands explicitly and keeps nothing in `commands/` (this repo's own `agenthub` does) previously reported zero. A declared path that resolves outside the plugin's install directory is ignored — a third-party manifest must not make the dashboard read arbitrary files. The counts are always the matching list's length. `hooks` has no `items` list: a plugin's hooks are matcher/command pairs declared inline in `plugin.json`, not named artifacts. ### Updating everything, and reloading sessions `POST /api/cc-config/plugins/update-all` refreshes every marketplace, then updates every installed plugin, then tells the open Claude Code sessions to pick the changes up. It **returns as soon as a detached worker is spawned** — the response is an acknowledgement, not a result — and progress is polled from `GET` on the same path, which reads the worker's journal at `~/.claude/agenthub/runtime/cc-update-all.json`. That indirection is structural, not stylistic: the plugin this dashboard *itself* runs from is updated **last**, followed by `plugin-bootstrap.js --force`, which stops this server and starts the replacement. A request handler doing the work would die partway through with the remaining plugins unrun and nothing able to report why, so the journal lives outside the plugin cache the update replaces and whichever server is alive serves it. Plugin ids come from `claude plugin list --json`, never from the request body, and the "self" plugin is derived from the server's own path — no caller can nominate a different plugin for the restart. A second concurrent batch is refused with 409 `EBUSY`. Batch `status` is `running`, `done`, `partial` (finished, at least one step failed), `failed`, or `abandoned`. `abandoned` is **derived, not stored**: the worker is detached, so a reboot leaves a `running` journal with nobody to finish it, and after an hour it is reported as abandoned so the button is usable again. `POST /api/cc-config/reload` is the reload step on its own. It types `/reload-plugins` and `/reload-skills` into the dashboard's live workspace panes via `tmux send-keys`. **Both commands are scoped by Claude Code to the session that runs them** (`/reload-plugins` activates pending plugin changes "in the current session"; `/reload-skills` picks up skills changed on disk "during this session"), so nothing can reload a session from the outside — typing into a session that is already running is the only real mechanism, and it is what this does. It never spawns a `claude` process: a one-shot `claude -p "/reload-plugins"` would reload its own short-lived session, exit, and leave a junk session behind. Panes sitting at a shell prompt are skipped, since the text would run as a shell command instead; only `claude` workspaces are addressed, as Codex has no equivalent. The two commands are typed **one second apart** (`SETTLE_MS` in `server/lib/cc-reload.js`), which is why the route takes about that long to answer: Claude Code opens its slash-command menu the moment `/` is typed and the Enter that follows lands on the menu, so back-to-back sends left both commands on one composer line and the pane submitted `/reload-plugins/reload-skills` — run as `/reload-plugins` with an argument, never reloading skills at all. `lanes_total: 0` is a normal outcome, not an error. Sessions running outside the dashboard cannot be reached and must run the command themselves. `POST /api/cc-config/plugins/action` accepts `reload: true` for the counterpart behaviour: update one plugin, reload immediately. The batch reloads once at the end instead — one reload picks up every pending change, where N of them would re-scan the same directory N times. A reload is never sent after a *failed* action. `GET /api/cc-config/memory` also surfaces the per-project file-based memory store — every `*.md` under `~/.claude/projects//memory/` (the common pattern of a `MEMORY.md` index plus one file per remembered fact). Those items have `scope: "auto-memory"` and carry `project` (the `projects/` dir name), `name` (filename), `isIndex` (true for `MEMORY.md` / `INDEX-*.md`, which sort first), and parsed `frontmatter`. They are **editable**: `PUT`/`DELETE /api/cc-config/file` accept `{ scope: "auto-memory", type: "auto-memory", project, name, content? }` and create a timestamped backup under `/.cc-config-backups/auto-memory/` before mutating (an invalid `project` slug returns `EBADPROJECT`). `GET /api/cc-config/backups` lists these with `scope: "auto-memory"` and `project` set. Bodies are also readable via `GET /api/cc-config/file` (they live under `CLAUDE_HOME`). **`POST /api/{cc,codex}-config/project-memory` (a new project's memory file).** Creates `CLAUDE.md` (Claude) or `AGENTS.md` (Codex) inside the directory named by `dir` — the one write path that honours a caller-supplied directory, because bootstrapping a project the dashboard has never run in is impossible from a writer pinned to the server's own cwd (which is what `PUT /file`'s `"project"` scope means). It stays narrow: `dir` must be absolute and already exist (nothing is created for you), the filename comes from the route and is never taken from the body, and an existing file — including a symlink under that name — returns **409 `EEXISTS`** rather than being overwritten, so this endpoint can only ever create. Bad or missing directories return 400 `EBADDIR`. Unlike the other config routes it sits behind the same loopback-`Origin` guard `/api/run` uses (403 `EBADORIGIN`): a page in the user's browser could otherwise plant agent instructions in a project directory. Returns `{ file, size, created: true }`, where `file` is the realpath'd target, and broadcasts `cc_config_changed`. **`PATCH /api/cc-config/settings` (key merge).** `scope` is `"user"`, `"project"`, or `"project-local"` (`settings.local.json`). `set` maps dotted key paths to JSON values; `unset` is a list of dotted key paths to delete. The server re-reads the target file **unredacted**, applies only the named keys, backs it up under `/.cc-config-backups/settings/`, and writes atomically — so keys the UI never displayed (including secret-valued ones) survive byte-for-byte. Returns `{ path, backupPath, created, changed }`. Hooks are edited through this same route, as `set: { "hooks.PreToolUse": [{ matcher, hooks: [{ type, command, timeout? }] }] }` — i.e. `settings.json`'s own nested shape, not the flattened shape `GET /hooks` returns. Errors: `EBADSCOPE` (unknown scope), `EBADNAME` (a key segment outside `[A-Za-z0-9_$][A-Za-z0-9._$-]*`, or `__proto__`/`prototype`/`constructor`), `EREDACTED` (400 — the payload contains the `` placeholder, which would destroy a real secret), `EBADJSON` (409 — the file on disk is not valid JSON; it is left untouched rather than clobbered), `ETOOLARGE`. The project layers always resolve against the **server's** cwd; `?cwd=` is honoured on reads only, never on this write. **Plugins and marketplaces.** These five endpoints shell out to the `claude plugin …` CLI with an explicit argv array (never a shell string); mutating calls are serialized in-process. `CLAUDE_CONFIG_DIR` is pinned to `CLAUDE_HOME` only when the operator explicitly set `CLAUDE_HOME` — left unset (the default), the CLI's own default config dir already matches what `cc-discovery` reads, so the pin is left off rather than pointed at the wrong directory (see `runClaude()`'s comment in `cc-plugin-cli.js` for the incident this fixed). `source` must be `owner/repo`, an `http(s)://` URL, or an absolute path; `spec`/`key` must be `` or `@`; `scope` is `user` (default), `project` or `local`. Validation failures return 400 `EBADARG`; a missing `claude` binary returns 503 `ECLINOTFOUND`; a CLI timeout returns 504 `ETIMEOUT`; a non-zero CLI exit returns **422 `ECLIEXIT`** with the CLI's message plus `stdout`/`stderr`. Successful runs return `{ ok: true, stdout, stderr }` and broadcast `cc_config_changed`. `GET /plugins/available` proxies `claude plugin list --available --json` as `{ installed, available }`. **MCP servers.** `POST /api/cc-config/mcp/add` and `POST /api/cc-config/mcp/remove` shell out to `claude mcp add`/`claude mcp remove` the same way the plugin routes shell out to `claude plugin …` — an argv array, never a shell string, serialized on the SAME in-process queue `cc-plugin-cli.js` exports (`serialize`), so a plugin install and an MCP add can never spawn `claude` concurrently. `scope` is `user` or `local` only (required on add, optional on remove — omitted, the CLI removes from whichever scope the server exists in). This is the inverse of what it sounds like: `user` writes `~/.claude.json`'s top level, `local` writes its `projects[]` block — the exact source `GET /mcp`'s `projectScoped` bucket reads. The CLI's own `project` scope (a separate, shared `.mcp.json`) is refused with 400: `readMcpServers` never reads that file, so a server added there would report success and never appear in the list. `add` takes either `url` (+ optional `transport: "http"|"sse"`, `headers`) for a remote server, or `command` + `args` (+ optional `env`) for a stdio server — exactly one of the two forms. Validation failures return 400 `EBADARG`; a non-zero CLI exit returns 422 `ECLIEXIT`. `GET /api/cc-config/mcp` is unaffected — it still reads `~/.claude.json` directly; the client refetches it after either call succeeds. `GET /mcp`'s server objects carry `removable: false` for rows sourced from `~/.claude/settings.json` (absent/true means removable) — no CLI scope addresses them, so the panel reads this flag rather than matching the `source` display string to decide whether to offer Remove. `PUT /api/cc-config/keybindings` edits `~/.claude/keybindings.json` from a structured list of context groups (`{ groups: [{ context, bindings: [{ key, action }] }] }`). The server backs the file up first (under `/cc-config-backups/keybindings/`), preserves any top-level metadata (`$schema`/`$docs`), and replaces only the `bindings` array; duplicate contexts or duplicate keys within a context return `EBADCONTENT`. `keybindings.json` is replaced wholesale here because the live CLI does not rewrite it mid-session; `settings.json`, which it does, is only ever key-merged (see `PATCH /settings` above). **Auth profiles (`/profiles*`).** A *profile* is one Anthropic account — one quota — under a name. Switching swaps exactly two identity artifacts and nothing else: `claudeAiOauth` inside `/.credentials.json`, and `oauthAccount` + `userID` inside the `.claude.json` config file(s) (`.json` and `/.claude.json`, each rewritten only if it already exists, key-merged so `projects`/`numStartups`/everything else survives). Skills, subagents, commands, memory, plugins, marketplaces, MCP servers and settings are never read or written here — that is what makes a switch keep the whole workspace and change only the account. `mcpOAuth` also stays put: those are the machine's MCP server tokens, not account identity. On **macOS** the live `claudeAiOauth` is NOT that file — the `claude` CLI keeps it in the login Keychain (generic password, service `Claude Code-credentials`, account `$USER`), read/written via `/usr/bin/security`; the file is only a fallback (and is kept in step when one already exists). `AGENTHUB_CC_KEYCHAIN=0` pins the file. Profiles live one JSON file per profile under `/agenthub-profiles/` (dir `0700`, files `0600`) and hold live OAuth tokens, so **no route ever returns token material** — `GET /profiles` answers `{ items, active }` with identity metadata only (`name`, `label`, `savedAt`, `active`, `accountUuid`, `email`, `displayName`, `organization`, `seatTier`, `subscriptionType`, `expiresAt`). **`POST /profiles/usage` (how much quota this account has spent).** Answers `{ name, refreshed, fiveHour, sevenDay, checkedAt }`, where each window is `{ utilization, resetsAt }` — a percentage and a rollover time, nothing else. There is no local source for this: nothing under `CLAUDE_HOME` records a utilization, and the credentials file carries only `subscriptionType` and `rateLimitTier`, so the server asks the same endpoint the CLI's own `/usage` reads (`GET https://api.anthropic.com/api/oauth/usage`) with that profile's OAuth token. It is a **POST**, and behind the same-origin guard, because answering it is a write. A saved profile's access token lasts hours, so every profile that is not the active one is normally expired; reading its usage means refreshing it first, and the refresh **rotates the stored credentials** — Anthropic retires the refresh token it was handed. The new pair is therefore written straight back into the profile file (atomic temp + rename at `0600`, every other field preserved), because a refresh whose result is dropped leaves an account that can never be activated again without a fresh `claude auth login`. A token that is still valid is used as-is and nothing is rewritten; a token that looks valid but is refused (401) is retried once through the refresh path. **The account that is logged in right now is the exception, and it is read from the CLI.** A refresh token is single use, so every refresh Claude Code performs on its own account retires the copy sitting in that account's profile file — the saved credentials of the LIVE account are the one set guaranteed to be rejected, with `invalid_grant`, however recently the profile was saved. `cc-profiles.liveCredentialsFor` therefore matches the profile's `accountUuid` against `.credentials.json` and, on a hit, uses what the CLI is holding. That token is never refreshed and that file is never written: rotating it would log the user out of their own terminal. An expired live token answers `ELIVEEXPIRED` (409) — using Claude Code once makes the CLI refresh it. **Nothing calls this on a timer**, but opening the Profiles modal does ask for every saved account at once — comparing accounts is the only reason the panel exists, and a button per row made the user do that by hand. What keeps that affordable is the pair of rules above: the live account costs a plain read, and any other profile is refreshed only when its token has actually expired, which leaves it valid for hours of further opens. Each row resolves on its own, so one superseded account still lets its neighbours report. Errors: `ENOTFOUND` (404), `ENOREFRESH`/`ENOAUTH` (409 — the profile has no usable token, re-save it from a login), `ESTALE` (409 — the refresh token was already spent by a newer login or refresh; activate the account once and save the profile again), `ELIVEEXPIRED` (409), `EUNAUTHORIZED` (401), anything upstream 502. See `server/lib/cc-usage.js`. A profile has two names, and the split is what lets a profile be called `Tài khoản chính`. `name` is the internal identifier every mutation route takes, and it is the filename, so it must match `^[a-zA-Z0-9][a-zA-Z0-9._-]{0,39}$`; callers normally never choose it, because `POST /profiles` derives it from the account. `label` is the display name the user edits with `PATCH /profiles`: free-form 1-60 characters, spaces and diacritics allowed since it is never used as a path, stored trimmed, rejected for control characters (`EBADLABEL`), and unique across profiles case-insensitively (`ELABELTAKEN`). A rename rewrites the label in place and **does not move `name`**, so it cannot half-fail and leave a profile unreachable. Profiles written before labels existed report `label` equal to their `name`. One account is one profile: `POST /profiles` refuses with `EDUPLICATE` when another profile already holds the logged-in account, naming the one that does. Two profiles of a single account would both report `active: true`, leaving nothing to switch between — and, under a blanket active-guard on delete, neither would ever be removable. Re-posting an account into its OWN profile is the token-refresh path, stays allowed, and preserves that profile's label. The dashboard **cannot log an account in** — only `claude auth login` mints tokens. Adding a profile is therefore always "log in from a terminal, then `POST /profiles` to snapshot what the CLI wrote". `POST /profiles/activate` re-snapshots the outgoing account into its own profile first (reported as `savedOutgoing`), so tokens Claude Code refreshed since the last save are not lost, and returns `{ ok, name, savedOutgoing, written }`. Errors: `EBADNAME` / `EBADLABEL` (400), `ENOTFOUND` (404 — no such profile), `EBADJSON` (409 — a config file on disk is unparseable; nothing is written), `ENOAUTH` (409 — nobody is logged in to snapshot), `EDUPLICATE` (409 — another profile already holds this account), `ELABELTAKEN` (409 — another profile already uses that label), `EUNSAVED` (409 — the live account is not saved as a profile, and switching away would discard the only copy of its credentials), `EACTIVE` (409 — refusing to delete the **last** saved copy of the live account; a redundant copy is deletable, which is what makes an accidental duplicate cleanable). Mutations broadcast `cc_config_changed` with `type: "profile"`. A switch only takes effect for **new** Claude Code sessions, and a session still running will rewrite the config on exit — close them first. Backup paths look like `/cc-config-backups//..bak[.dir]` — outside the directories Claude Code scans, so a deleted skill cannot resurface as a backup-named one. The Backups modal in the UI auto-builds `mv` restore commands. ### Codex Config Explorer The `/api/codex-config/*` namespace powers the **Codex** page of Settings (`/settings/agents/codex`) — the Codex CLI counterpart of the Claude Config Explorer above. Codex has a narrower scope union than Claude Code: `"user"` or `"project"` only, no `"project-local"` and no per-project file-based memory. Reads for skills/agents/rules/memory/config are pure file reads (`server/lib/codex-discovery.js`); MCP servers, plugins, and marketplaces have no on-disk reader and are read *and* mutated entirely through the `codex` CLI (`server/lib/codex-cli.js`), because the CLI owns `config.toml`'s schema. ```http GET /api/codex-config/overview GET /api/codex-config/skills?scope=user|project|all GET /api/codex-config/agents?scope=user|project|all GET /api/codex-config/rules?scope=user|project|all GET /api/codex-config/memory GET /api/codex-config/config GET /api/codex-config/file?path= PUT /api/codex-config/file Body: { scope, type, name?, content } DELETE /api/codex-config/file Body: { scope, type, name? } POST /api/codex-config/project-memory Body: { dir, content } GET /api/codex-config/backups[?scope=&type=] GET /api/codex-config/mcp GET /api/codex-config/plugins GET /api/codex-config/marketplaces POST /api/codex-config/mcp/add Body: { name, url, bearerTokenEnvVar? } | { name, command, args?, env? } POST /api/codex-config/mcp/remove Body: { name } POST /api/codex-config/plugins/action Body: { spec, action: add|remove } POST /api/codex-config/marketplaces/add Body: { url } POST /api/codex-config/marketplaces/action Body: { name, action: remove } ``` `type` is one of `skills`, `agents`, `rules`, `memory`, `config`. `name` is required for `skills`/`agents`/`rules` and forbidden for `memory`/`config` (each is a single fixed file per scope — `AGENTS.md` and `config.toml` respectively). `PUT`/`DELETE` always back the previous content up first (`server/lib/codex-mutate.js`) and always resolve `project` scope against the **dashboard server's own cwd** — unlike the read routes, there is no `?cwd=` override on a write, for the same reason `cc-config.js`'s `PATCH /settings` refuses one. Mutation errors: `EBADTYPE`/`EBADSCOPE`/`EBADNAME`/`EBADCONTENT`/`EOUTOFROOT` (400), `ETOOLARGE` (413), `ENOTFOUND` (404). Every successful write/delete broadcasts `codex_config_changed`. `GET /mcp`, `/plugins`, `/marketplaces` proxy `codex mcp list --json` / `codex plugin list --json` / `codex plugin marketplace list --json`; a fresh install with none of a kind returns `{ mcp: [] }` etc. rather than a parse error. Unlike `mcp list --json` (a bare array), `plugin list --json` and `plugin marketplace list --json` return `{installed, available}` / `{marketplaces}` objects — `server/lib/codex-cli.js` unwraps those down to a plain array before the route ever sees them, so every list route's contract stays "the named field is a list"; the client's `Array.isArray` coercion is only a defensive fallback for CLI output that fails to parse at all. The add/remove routes shell out to `codex …` with an explicit argv array (never a shell string); a non-zero CLI exit is reported as **422 `ECLIEXIT`** with `stdout`/`stderr` preserved, never a 500. `POST /mcp/add` takes either `{ name, url, bearerTokenEnvVar? }` (HTTP transport) or `{ name, command, args?, env? }` (stdio transport) — never both, mirroring `codex mcp add`'s own mutually-exclusive flags. `POST /marketplaces/add`'s `url` field is misnamed for history but accepts the same source shapes as `codex plugin marketplace add`: `owner/repo`, an http(s) git URL, or an absolute local path (ssh remotes are out of scope). Other CLI errors: `EBADARG` (400), `ECLINOTFOUND` (503 — the `codex` binary isn't on `PATH`), `ETIMEOUT` (504). Because `CodexMcpServer`/`CodexPlugin`/`CodexMarketplace` are opaque JSON blobs from the CLI (`[key: string]: unknown`) rather than a shape the dashboard controls, the Codex tab renders them as generic key/value cards instead of the richly-typed plugin/MCP cards the Claude Code tab shows. ### Run Claude via tmux+PTY The `/api/run/*` namespace starts and manages `claude` subprocesses in tmux-backed pseudoterminals, one session per workspace. The Workspace page renders an interactive xterm.js terminal attached to the session over `/ws-pty/:runId` (binary PTY frames, not JSON). Every route enforces a same-origin / loopback-Origin guard; browser requests must come from `localhost`, `127.0.0.1`, `::1`, or `0.0.0.0`. CLI / curl requests with no `Origin` header pass through. When `DASHBOARD_TOKEN` is set, a valid token is also required here (like the rest of `/api/*` — see [Authentication](#authentication)). **`tmux` must be installed on the dashboard server** (same operational requirement as better-sqlite3's native module). ```http GET /api/run List all live runs (computed fresh from tmux state) GET /api/run/tmux { available: bool } — whether tmux is on PATH GET /api/run/binary?tool= { found, path } for the `claude`, `codex` or `agy` binary GET /api/run/cwds Suggested cwds (dashboard, home, recent) GET /api/run/history?limit=&laneId= Persisted run history; laneId narrows to one lane's runs GET /api/run/files?cwd=&q= Fuzzy file search inside cwd for the @-file autocomplete POST /api/run/drop-image Raw image body (png/jpeg/gif/webp, ≤20 MB) → {path}: saved 0600 under /agenthub-drops-/ with a random name, pruned after a day; the terminal pastes the path (skips node_modules, .git, dist, build, .next, .cache, coverage, vendor) POST /api/run Start/attach run — Body: { laneId, cwd?, model?, permissionMode?, effort?, resumeSessionId?, initialPrompt?, sandbox?, approval?, resumeLast?, bypass? } GET /api/run/:id Run handle (returns live run state) DELETE /api/run/:id Kill (SIGTERM → SIGKILL after 5 s) ``` `:id` must be a workspace pane name, `agenthub-lane-`; anything else answers 404 without reaching tmux, so these two routes can never touch a tmux session the dashboard did not start. **`GET /api/run/binary`:** Probes PATH for a workspace tool's CLI, looked up in the AI Tools catalog (`?tool=`, default `claude`; an unknown id is `400 EBADTOOL`). Always a fresh look, not the catalog's cached detection. Returns `{ found: bool, path: string | null }`. **`bypass: true`** (both `POST /api/run` and `POST /api/lanes/:id/start`) appends the workspace tool's catalog bypass args/env for that run only; Codex's replaces `-s`/`-a`, Claude has none. A workspace whose tool is no longer in the catalog answers `400 ENOTOOL`. **`POST /api/run` (start/attach):** Requires `laneId` (the workspace this run belongs to). Creates or attaches an existing tmux session named `agenthub-lane-` in the workspace's working directory. If that session already exists and its pane is idling at a shell prompt, the appropriate command line (including `--resume` and any initial prompt) is typed into that pane instead of being dropped; if the pane is running a program, the request adopts the session unchanged. Optionally accepts `initialPrompt` to immediately type/send into the session (if empty or omitted, the session is created/attached with no initial input). Returns `{ id, laneId, status, cwd, model, permissionMode, effort, resumeSessionId, sessionId, startedAt, promptPreview }` where `id` is the tmux session name. The dashboard self-heals a workspace's `run_id`/`status` on every read if the tmux session has been killed externally. `permissionMode` (`auto` default, or `acceptEdits` / `default` / `plan` / `bypassPermissions`) is the mode the pane starts in — `auto` is the CLI's own classifier mode: it asks only for what it reads as risky. The pane's argv also carries `--allow-dangerously-skip-permissions`, which only makes **bypass permissions** selectable in the pane's `shift+tab` cycle — it does not enable it. **PTY streaming:** Frames from the tmux pane are streamed to the client over `/ws-pty/:runId` as binary WebSocket frames (not JSON). The Workspace page's TerminalView component feeds these frames to xterm.js for live rendering. Simultaneously, `agenthub lanes shell` can attach the same session via a real local terminal, staying in sync with the browser view. Every history row carries `lane_id` (the workspace whose run it belongs to) and `tool` (the CLI that was invoked: `"claude"` or `"codex"`). A run's `id` is its tmux pane name, which each Start in that pane reuses, so the run it replaces is kept as its own row with `id` = `@` (status `abandoned` if it never recorded an end). A row still marked `running` is flipped to `abandoned` once its tmux session is gone — checked at server start and on the 10 s run-heal beat (`DASHBOARD_RUN_HEAL_MS`); a pane that survived a server restart stays `running`. `GET /api/run/history?laneId=` returns only that workspace's runs. Spawned Claude processes fire the dashboard's hooks like any other CLI session, so they show up in `/api/sessions`, and the Dashboard's Analytics tab (Workflow sub-tab included) automatically. Codex runs do not emit these hooks; they are recorded only in run history and `dashboard_runs`. --- ### AI Tools ``` GET /api/ai-tools Catalog + detection — { tools: [...], default } POST /api/ai-tools/refresh Re-read the login shell's PATH, re-detect, same body PUT /api/ai-tools/:id Body: { enabled?: boolean, default?: true, defaultModel?: string|null } — same body GET /api/ai-tools/:id/models { flag, models: [{ id, label, hint? }], defaultModel } — the tool's own list GET /api/ai-tools/:id/usage { sessions, cost } — sessions with tool = id, their tokens priced GET /api/ai-tools/:id/config { files: [{ index, path, format: "json"|"jsonc"|"text", exists, size }] } GET /api/ai-tools/:id/config/:i { path, format, text, sha } PUT /api/ai-tools/:id/config/:i Body: { text, baseSha } → { sha, backup } POST /api/ai-tools/:id/install Start the catalog's install job → 202 { job } POST /api/ai-tools/:id/update Start the catalog's update job → 202 { job } POST /api/ai-tools/update-all One job: every npm-managed tool with a newer version + every self updater GET /api/ai-tools/job The current or last job, or null GET /api/ai-tools/versions { [id]: { npmManaged, installed, latest, updateAvailable } } GET /api/ai-tools/:id/icon The tool's favicon, fetched once by the server; 204 → letter avatar ``` Each tool: `{ id, label, command, homepageUrl, installed, path, enabled, source: "builtin"|"custom", launcher, prompt: { mode }, resume: bool, bypass: bool, routerCapable: bool }` — flags only, never the arg arrays. Each tool also carries `modelFlag` (the CLI takes a model: Claude, Codex, or a catalog `model: { flag, vendor? }` field) and `defaultModel` (what a new run starts with, `null` = the CLI's own; a `PUT` with `""`/`null` clears it, an id that is not a plain model name is `400 EBADMODEL`). The config files are only those a built-in or release catalog file lists in `config` (`~/`-relative, no `..`, no credential-looking name); a read or save answers `404 ENOFILE` (no such index) / `ENOENT` (missing — never created), `403 ESECRET` (the name, or a symlink target's, looks like a credential), `413 ETOOBIG` (> 1 MB), `415 EBINARY`, `400 EBADSYNTAX` (JSON/JSONC that does not parse), `409 ESTALE` (the file is no longer at `baseSha`); a save backs the old text up under `/ai-tool-config-backups//` and is same-origin only. `GET /:id/models` reads each tool's own source: Codex's `$CODEX_HOME/models_cache.json` (listed entries by priority — nothing else from that file), Claude's aliases named after the newest priced version plus the priced pinned versions, a catalog tool's vendor-priced ids plus the models its own sessions used; `flag: false` and `[]` for a tool with no model flag, `404 ENOTOOL` for an unknown id. `default` is the effective default: the stored one if installed and enabled, else `claude` if installed and enabled, else the first installed enabled tool, else `null`. `PUT` answers `404 ENOTOOL` for an unknown id, `400 EBADDEFAULT` for a default that is not installed or disabled, `400 EBADFIELD` for a non-boolean `enabled`; disabling the default clears it. Writes are same-origin only. State lives in `/ai-tools.json`. Each tool also carries `install` (`{kind:"npm", package}` or `{kind:"script", url}`, else null) and `update` (`{kind:"npm"}`, `{kind:"script"}`, `{kind:"self", args}`, else null), and the body carries `catalog: { source: "builtin"|"remote", tag, fetchedAt }` — `remote` while a copy of the newest release's catalog, newer than this build, is in use (synced daily, off with `AGENTHUB_AI_TOOLS_SYNC=0`). **Install / update jobs.** Commands come only from built-in or release catalog files, never from the request or `DASHBOARD_AI_TOOLS_DIR`. npm is the login shell's (`npm install -g @latest`); a script is downloaded by the server (https, same site as the tool's homepage, ≤ 1 MB) and run as `bash `; `self` runs ` ...args`. One job server-wide; the job is `{ id, tool, action, status: "running"|"ok"|"failed", startedAt, endedAt, exitCode, log }` (last 256 KB, 10-minute timeout) and lives in memory. A successful install enables the tool. Errors: `404 ENOTOOL`; `400 ENOINSTALL`/`ENOUPDATE`/`ENOTHING`; `409 EINSTALLED`/`ENOTINSTALLED`/`ENOTNPM` (npm update of a tool whose binary is not under `npm prefix -g`)/`ENONPM`/`EBUSY`. Icons are the root `/favicon.ico`, raster only by magic bytes (never SVG), ≤ 256 KB, cached in `/runtime/ai-tool-icons/`, served with `nosniff` and `Content-Security-Policy: sandbox`; an `` passes the dashboard token as `?token=`. The client shows its own shipped mark instead where it has one (`client/public/ai-tools/.svg` — claude, codex, openclaw, and hermes as a `-black`/`-white` pair swapped by the theme; `BUNDLED` in `client/src/components/AiToolIcon.tsx`), so this route is asked only for the other tools. ### AI Router profiles ``` GET /api/ai-routers Every saved profile, the built-in `native` one first POST /api/ai-routers Create — Body: { label, baseUrl, apiKey?, model, models? } POST /api/ai-routers/test Probe an endpoint — Body: { baseUrl, model, apiKey?, name? } PATCH /api/ai-routers/:name Update the same fields, all optional DELETE /api/ai-routers/:name Delete one saved profile ``` A **router profile** is an endpoint that stands in front of Claude Code or Codex (9Router, OpenRouter, a self-hosted gateway) plus the model names to use against it. It powers the **AI Router** page of Settings (`/settings/ai-router`), which stores profiles and attaches nothing — the tab's **Test** button (`POST /api/ai-routers/test`, below) is its only outbound call. A profile is chosen per NEW SESSION, not per workspace: the **AI Router** select beside the model picker in the workspace home's prompt box and in a pane's run form (shown only for Claude/Codex and only when a profile beyond Native is saved; the last pick is remembered in `agenthub.session.router`). `models` carries the five per-tier names (`opus`, `sonnet`, `haiku`, `smallFast`, `subagent`). Any tier omitted is filled from `model`, so a router that answers to one symbolic name needs one field, not six. **No response here ever contains key material.** A saved profile reports `hasKey: true|false` and there is deliberately no `GET /:name` — a route returning one profile in full would be the single way an API key could leave the server. Profiles live one JSON file each under `/agenthub-routers/` (dir `0700`, files `0600`). An omitted `apiKey` on `PATCH` keeps the stored one; the edit form cannot display a key, so it has none to send back. **`POST /api/ai-routers/test`** answers the question saving cannot: does this endpoint, with this key, actually serve this model? It sends one Anthropic-style message capped at a single output token to `/v1/messages` (a 15 s timeout), which is the wire shape a claude workspace's eight env keys point at — a Codex-only router is not covered. A router that answers is a `200` here whatever it replies: `{ ok, status, message }` carries the router's own words (truncated to 300 characters), and `status` is `null` when nothing answered at all. Only bad input is a 4xx. The stored key is only ever sent to the endpoint it was stored against. A blank `apiKey` falls back to the key of the profile named by `name`, but **only** while the submitted `baseUrl` still equals the saved one — so testing a retyped endpoint needs a retyped key (`400 EBADKEY`). Without that rule this route would be a way to make the server POST a saved API key to any URL a browser names. `native` is a built-in profile, not the absence of one: empty `baseUrl`/`apiKey` and the vendor's own model names, so switching back is the same write path as switching to a router. It answers `409 EBUILTIN` to any update, delete, or attempt to shadow its name. Other errors: `400 EBADLABEL` / `EBADURL` (an endpoint must be `http:` or `https:`) / `EBADMODEL`, `404 ENOTFOUND`. **Starting a session on a router.** `POST /api/lanes/:id/start` and `POST /api/run` take `router: ""` (omitted, `""` or `"native"` = the vendor's own API). Only the name comes from the request; the key and endpoint come from the store. An unknown name is `400 EBADROUTER`, a router on a tool other than Claude/Codex `400 EUNSUPPORTED`. A resume (`resumeSessionId`, `resume`) that names no router goes back to the one its session last ran on (`dashboard_runs.router`), or native once that profile is deleted. Each spawn (re)writes the profile's files: - **Claude** gets `--settings=/router-settings/.json` (dir `0700`, file `0600`): an `env` block with the eight keys `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL`, `ANTHROPIC_SMALL_FAST_MODEL`, `CLAUDE_CODE_SUBAGENT_MODEL` (an empty one left out). The command-line layer outranks the project-local and user settings, so two sessions of one workspace can run on two routers, and only the path is in argv. Native adds nothing, so a router the user set in their own `~/.claude/settings.json` still applies to a native session. - **Codex** gets `-p ` and `$CODEX_HOME/.config.toml`, the layer that flag loads on top of the base config (never touched). The layer sets `wire_api = "responses"` (codex-cli 0.149 refuses `"chat"`); `env_key` is written only when the profile has a key, and the key reaches the pane as `AGENTHUB_ROUTER_KEY` through tmux's own `-e`, never as typed text. `PATCH` rewrites the profile's files that exist (a live Claude session reads its file again; the next Codex session gets the new layer) and `DELETE` removes both. Workspaces no longer carry a router: `POST /api/lanes/:id/router/apply` is gone, and at every start the server takes the eight keys an older build wrote into a workspace's `.claude/settings.local.json` back out and clears `lanes.router_profile` (a file that is not valid JSON is left alone and retried next start). --- ## WebSocket API ### Connection ```javascript const ws = new WebSocket('ws://localhost:4820/ws'); ws.onopen = () => { console.log('Connected to Agent Dashboard'); }; ws.onmessage = (event) => { const message = JSON.parse(event.data); console.log('Received:', message); }; ws.onerror = (error) => { console.error('WebSocket error:', error); }; ws.onclose = () => { console.log('Disconnected'); }; ``` When `DASHBOARD_TOKEN` is configured, pass the token as `?token=` on the `/ws` upgrade (an `x-dashboard-token` header also works): ```javascript const ws = new WebSocket('ws://localhost:4820/ws?token=YOUR_DASHBOARD_TOKEN'); ``` ### WebSocket Lifecycle ```mermaid stateDiagram-v2 [*] --> Connecting: new WebSocket() Connecting --> Connected: onopen Connecting --> Disconnected: onerror Connected --> Connected: onmessage Connected --> Disconnected: onclose Connected --> Disconnected: onerror Disconnected --> Connecting: Reconnect Disconnected --> [*] note right of Connected Heartbeat: ping every 30s Broadcast: Real-time events end note ``` ### Event Types Server broadcasts JSON messages to all connected clients: #### session.created Sent when a new session is created. ```json { "type": "session.created", "data": { "id": 1, "session_id": "sess_abc123", "model": "claude-sonnet-4", "status": "active", "total_cost": 0, "created_at": "2024-03-18T12:00:00Z", "updated_at": "2024-03-18T12:00:00Z" } } ``` #### session.updated Sent when session data changes (status, cost, etc.). ```json { "type": "session.updated", "data": { "id": 1, "session_id": "sess_abc123", "model": "claude-sonnet-4", "status": "completed", "total_cost": 1.23, "created_at": "2024-03-18T12:00:00Z", "updated_at": "2024-03-18T14:30:00Z" } } ``` #### agent.created Sent when a new agent starts. ```json { "type": "agent.created", "data": { "id": 1, "agent_id": "agent_xyz789", "session_id": "sess_abc123", "agent_type": "explore", "status": "running", "current_tool": null, "input_tokens": 0, "output_tokens": 0, "cost": 0, "created_at": "2024-03-18T12:00:00Z", "updated_at": "2024-03-18T12:00:00Z" } } ``` #### agent.updated Sent when agent data changes (tokens, status, current_tool). ```json { "type": "agent.updated", "data": { "id": 1, "agent_id": "agent_xyz789", "session_id": "sess_abc123", "agent_type": "explore", "status": "completed", "current_tool": null, "input_tokens": 1500, "output_tokens": 800, "cost": 0.45, "created_at": "2024-03-18T12:00:00Z", "updated_at": "2024-03-18T12:05:00Z" } } ``` #### tool.executed Sent when a tool execution completes. ```json { "type": "tool.executed", "data": { "id": 1, "agent_id": "agent_xyz789", "tool_name": "bash", "duration_ms": 1234, "success": 1, "error_message": null, "created_at": "2024-03-18T12:01:00Z" } } ``` #### notification.received Sent when a notification is created. ```json { "type": "notification.received", "data": { "id": 1, "session_id": "sess_abc123", "notification_type": "backgroundTaskComplete", "message": "Explore agent completed", "created_at": "2024-03-18T12:05:00Z" } } ``` #### /ws-pty/:runId — PTY frames A dedicated binary WebSocket stream (not JSON-framed) for tmux-backed PTY transport. Established by the Workspace TerminalView component on workspace load; endpoint is `/ws-pty/:runId` where `runId` comes from `POST /api/run`. Frames are raw PTY output (stdin echoes, command output, prompt updates, terminal control sequences) as binary blobs; the client feeds each frame to xterm.js for live rendering. The same tmux session can have multiple simultaneous clients (browser Workspace, `agenthub lanes shell`, other tools), all receiving the same frames live-synced. **The attach URL carries the client's size** (`/ws-pty/:runId?cols=&rows=`, integers in `[2, 1000]`, else 80×24): tmux resizes the window to whichever client attached most recently, so spawning the attach at a default size and correcting it from the first `resize` message a beat later made the pane's program redraw its whole UI at 80 columns — and everything painted at that width stayed in the scrollback, surfacing as torn left-margin fragments the moment the user scrolled back (issue #33). Resize events after that: the client sends a `{"type":"resize","cols","rows"}` text frame and the server applies it as a `TIOCSWINSZ` ioctl down the pane's pty, so window-sensitive commands (e.g. pagers, text editors) adapt to the viewport size. The client reports its size from **xterm's own `onResize`**, not from the container's `ResizeObserver` — cols also move when the webfont finishes loading or the page zooms, neither of which resizes the observed element — and re-asserts it whenever the terminal regains focus, because `window-size latest` lets a second attach client (another tab, `agenthub lanes shell`) resize the tmux window out from under this one. Keeping the two widths equal is not cosmetic: a tmux pane **wider** than xterm makes every over-long row autowrap its tail onto the next row's left margin, and tmux never repaints a row it believes unchanged — so stray characters stay glued to the left edge of blank lines, visible as soon as a scroll repaints history. A zero size (the console collapses with CSS, leaving the container 0×0) is never reported. The WebSocket connection inherits the same loopback same-origin guard and optional token auth as other `/api/*` routes. The client re-attaches automatically 1.5 s after an unexpected close (server restart, network blip) — tmux keeps the session alive, so the re-attach repaints the pane in full. It stops retrying only after the server's one-shot `{"type":"exit"}` frame, which means the pane process itself ended — the Workspace takes that frame as the signal to restore the run setup form, since there is nothing left to attach to. Without that retry a dropped socket left the pane frozen on its last painted frame: it still looked live, but no keystroke and no mouse report (wheel scroll included) reached tmux again. #### cc_config_changed Broadcast whenever Claude Code configuration changes — either by dashboard mutations on `PUT/DELETE /api/cc-config/file` (`source: "dashboard"`) or by `lib/cc-watcher.js` picking up external `fs.watch` events on `~/.claude/` and `~/.claude.json` (`source: "fs"`, debounced at 500 ms). The Config Explorer page subscribes and refetches automatically. ```json { "type": "cc_config_changed", "data": { "source": "dashboard", "action": "write", "scope": "user", "type": "skill", "name": "my-skill" } } { "type": "cc_config_changed", "data": { "source": "fs", "paths": ["/Users/foo/.claude/settings.json"] } } ``` #### codex_config_changed The Codex counterpart of `cc_config_changed` — broadcast by `routes/codex-config.js` after every successful mutation: `PUT`/`DELETE /api/codex-config/file`, and the CLI-backed `mcp/add`, `mcp/remove`, `plugins/action`, `marketplaces/add`, `marketplaces/action` routes. Always `source: "dashboard"` — there is no filesystem watcher on `$CODEX_HOME` (unlike the Claude side's `cc-watcher.js`). The Codex Config page subscribes and refetches automatically. ```json { "type": "codex_config_changed", "data": { "source": "dashboard", "action": "write", "scope": "user", "type": "rules", "name": "default" } } { "type": "codex_config_changed", "data": { "source": "dashboard", "action": "add", "type": "mcp", "name": "docs" } } ``` #### remote_data.updated Broadcast once per successful remote sync (background poller, manual **Sync now**, or immediate pull after add/re-enable). Clients use this — and the per-session `session_created` / `session_updated` frames emitted in the same pass — to refetch sessions, costs, and analytics without polling. ```json { "type": "remote_data.updated", "data": { "sourceId": "src_a1b2c3", "source": "src_a1b2c3", "label": "dev-box", "counters": { "imported": 1, "skipped": 0, "sessions_tagged": 3 }, "last_sync_at": "2026-07-26T21:15:00.000Z" } } ``` #### remote_source.status Broadcast when a remote data source changes sync state (during/after `POST /api/remote-sources/:id/sync`) or is deleted. `status` is one of `idle`, `syncing`, `ok`, `error`, or `deleted`. `error` and `last_sync_at` are optional and present when relevant. See [Remote Data Sources](#remote-data-sources). ```json { "type": "remote_source.status", "data": { "id": "4d1f0e2a-7b9c-4c33-8a21-9e0f7b6d4c11", "status": "syncing" } } { "type": "remote_source.status", "data": { "id": "4d1f0e2a-7b9c-4c33-8a21-9e0f7b6d4c11", "status": "ok", "last_sync_at": "2026-07-22T18:41:55.117Z" } } { "type": "remote_source.status", "data": { "id": "4d1f0e2a-7b9c-4c33-8a21-9e0f7b6d4c11", "status": "error", "error": "ssh exited with code 255" } } { "type": "remote_source.status", "data": { "id": "4d1f0e2a-7b9c-4c33-8a21-9e0f7b6d4c11", "status": "deleted" } } ``` ### Event Flow ```mermaid sequenceDiagram participant Hook as Hook Handler participant Server as Express Server participant DB as SQLite participant WS as WebSocket Server participant Client1 as Client 1 participant Client2 as Client 2 Hook->>Server: POST /hooks/post-tool-use Server->>DB: Create tool_execution DB-->>Server: Inserted row Server->>WS: broadcast({ type: 'tool.executed', data }) par Broadcast to all clients WS->>Client1: { type: 'tool.executed', ... } WS->>Client2: { type: 'tool.executed', ... } end Server-->>Hook: 200 OK ``` --- ## Error Handling ### Error Response Format All error responses follow this structure: ```json { "error": "Human-readable error message", "code": "ERROR_CODE", "details": { "field": "Additional context" } } ``` ### HTTP Status Codes | Code | Meaning | Example | |------|---------|---------| | 200 | Success | Resource retrieved | | 201 | Created | Resource created | | 400 | Bad Request | Invalid JSON, missing fields | | 404 | Not Found | Session/agent not found | | 409 | Conflict | Duplicate pattern | | 500 | Server Error | Database error | ### Error Examples **400 Bad Request:** ```json { "error": "Missing required field: pattern", "code": "VALIDATION_ERROR", "details": { "field": "pattern", "message": "Pattern is required" } } ``` **404 Not Found:** ```json { "error": "Session not found", "code": "NOT_FOUND", "details": { "session_id": "sess_invalid" } } ``` **409 Conflict:** ```json { "error": "Pricing rule already exists", "code": "DUPLICATE_PATTERN", "details": { "pattern": "claude-sonnet-4" } } ``` --- ## Rate Limiting Currently, no rate limiting is enforced. For production deployments, implement rate limiting: ```javascript // Using express-rate-limit import rateLimit from 'express-rate-limit'; const limiter = rateLimit({ windowMs: 15 * 60 * 1000, // 15 minutes max: 100, // Limit each IP to 100 requests per windowMs message: 'Too many requests, please try again later.' }); app.use('/api/', limiter); ``` --- ## Pagination For endpoints returning lists, use `limit` and `offset`: ```http GET /api/sessions?limit=20&offset=40 ``` **Pagination Pattern:** ```mermaid graph LR Page1[Page 1
offset=0
limit=20] --> Page2[Page 2
offset=20
limit=20] Page2 --> Page3[Page 3
offset=40
limit=20] Page3 --> PageN[Page N
offset=N*20
limit=20] style Page1 fill:#3B82F6 ``` **Response includes pagination metadata:** ```json { "sessions": [...], "total": 156, "limit": 20, "offset": 40, "has_more": true } ``` --- ## Examples ### Full Session Workflow ```javascript // 1. List sessions const sessions = await fetch('http://localhost:4820/api/sessions'); const { sessions: sessionList } = await sessions.json(); // 2. Get specific session const sessionId = sessionList[0].session_id; const session = await fetch(`http://localhost:4820/api/sessions/${sessionId}`); const sessionData = await session.json(); // 3. Get session agents const agents = await fetch(`http://localhost:4820/api/sessions/${sessionId}/agents`); const { agents: agentList } = await agents.json(); // 4. Get agent tools const agentId = agentList[0].agent_id; const tools = await fetch(`http://localhost:4820/api/agents/${agentId}/tools`); const { tools: toolList } = await tools.json(); console.log('Session:', sessionData); console.log('Agents:', agentList); console.log('Tools:', toolList); ``` ### Real-time Monitoring ```javascript // Connect to WebSocket const ws = new WebSocket('ws://localhost:4820/ws'); ws.onopen = () => { console.log('Connected to real-time stream'); }; ws.onmessage = (event) => { const message = JSON.parse(event.data); switch (message.type) { case 'session.created': console.log('New session:', message.data.session_id); break; case 'agent.updated': console.log('Agent updated:', message.data.agent_id); console.log('Cost:', message.data.cost); break; case 'tool.executed': console.log('Tool executed:', message.data.tool_name); console.log('Duration:', message.data.duration_ms, 'ms'); break; } }; ``` ### Creating Pricing Rules ```javascript // Create custom rule const response = await fetch('http://localhost:4820/api/pricing', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ pattern: 'my-custom-model', input_cost_per_1m: 5.0, output_cost_per_1m: 20.0 }) }); const { rule } = await response.json(); console.log('Created rule:', rule); // List all rules const rules = await fetch('http://localhost:4820/api/pricing'); const { rules: ruleList } = await rules.json(); console.log('All rules:', ruleList); // Delete rule await fetch('http://localhost:4820/api/pricing/my-custom-model', { method: 'DELETE' }); ``` --- ## Summary The Agent Dashboard API provides: - ✅ **RESTful endpoints** for querying sessions, agents, tools, pricing - ✅ **WebSocket streaming** for real-time updates - ✅ **Type-safe responses** with consistent JSON structure - ✅ **Error handling** with descriptive error codes - ✅ **Pagination** for large datasets - ✅ **Pricing management** with custom rule support For interactive API exploration with live request/response examples, see the built-in Swagger UI at `/api/docs` and ReDoc at `/api/redoc`. For MCP integration, see [MCP.md](./MCP.md).