Skip to content

API.md

Latest commit

 

History

History
618 lines (548 loc) · 38.4 KB

API.md

File metadata and controls

618 lines (548 loc) · 38.4 KB
Raw

API, MCP, and the permissions model

Vogt exposes one operation registry (src/vogt/registry) through three transports — HTTP, the CLI, and MCP — sitting behind a session engine / front door. Every capability is generated from that one registry, so the three transports never drift.

The endpoints themselves are self-describing (FastAPI emits OpenAPI), but which process, which port, and which token was never written down in one place. This is that map. Read it before reaching for a token — a request to the wrong surface, or with the wrong bearer, is a 401/404 that looks like a bug and is not.

The two processes

Process What it is Port Serves
Core (vogt serve) The tracker: projects, work items, tokens, the store. A FastAPI app. 8000 (container) /api/* operations, /mcp, and the generated docs /openapi.json, /docs, /redoc
Engine / front door The session + PWA host that fronts the core in a deployment. A Rust server. e.g. 8910 on the estate the PWA, /api/status, /api/auth/check, /api/sessions, /healthz, /readyz, the assistant — and it proxies /api/vogt/*, /mcp, /api/auth/login and /api/install/* through to the core

In a deployed stack the engine is the front door: the core is not exposed directly, and callers reach it through the engine's /api/vogt and /mcp proxies (engine/server/src/app.rs, MACHINE_NAMESPACES = ["/api", "/mcp"]). Everything else on the engine is the engine's own.

Three ways to call one operation

  1. HTTP — on the core, at {API_PREFIX=/api}/<operation route>. Because the core is FastAPI, you get for free (FR-A4):

    • /openapi.json — the machine-readable spec.
    • /docs — interactive Swagger UI.
    • /redoc — ReDoc.

    These live at the core root (http://<core>:8000/docs), not under /api, and the front door proxies /api/vogt, not /docs — so Swagger is normally reachable only from inside the deployment.

  2. CLI — vogt <group> <op> operates on the local store directly, with no bearer. Inside the core container that store is the core's store, and loopback access is effectively admin — which is how vogt token issue mints a token when no admin bearer exists. (A pod wired to a remote core still defaults to the local store and will say not_initialized; set VOGT_CORE_URL + VOGT_HTTP_TOKEN and call the HTTP API instead — see the CLI hint added in #729.)

  3. MCP — the same operations as tools over /mcp (JSON-RPC, streamable HTTP), proxied by the engine to the core. The vogt-mcp-remote stdio bridge fronts it for agent clients (src/vogt/adapters/mcp/).

Tokens — which bearer each surface accepts

The core is the only identity authority. Every credential a client holds is a core token bound to an actor, and the engine accepts all of them: it keeps no token table of its own and resolves a bearer by asking the core (GET /api/auth/whoami, cached for seconds), so one credential opens both doors. The one exception is the engine's optional break-glass ENGINE_TOKEN, a static credential the core has never heard of: it 401s the core, and on /api/vogt the engine substitutes the stack secret for it.

Token tokens.kind Authenticates Typical scopes Where it comes from
Session (a person's login) session the core — /api/*, /mcp — and the engine the scopes on the login: read,work.write,project.write by default, admin for the first operator POST /api/auth/login with a username and password; expires after session_ttl_days (30) or at auth.logout
API token (an agent's credential) api the core and the engine as issued vogt token issue (admin)
Stack secret (deploy/vogt-core-token) api the core, as the front-door actor; the engine, as vogt-core (sessions, history, agent-clis-write) VOGT_BOOTSTRAP_CORE_TOKEN_SCOPES the file both halves read, adopted at init (#199); server-side only, never in a browser
Coding-session token (session.start) agent the core, per session agent_session_scopes — default everything except admin minted per session (#726)
Brokered agent token — the core, as a shell/agent session's VOGT_HTTP_TOKEN deployment-chosen ENGINE_AGENT_AUTH_VOGT_SECRET_NAME, brokered from the secrets manager at session launch
Break-glass token (ENGINE_TOKEN, optional) none the engine only — full capability, no actor — deploy/.env; its Vogt calls are made with the stack secret

Concretely: GET /api/auth/check on :8910 accepts a session or an API token and answers with identity: {name, scopes, capabilities} — the core actor's identity_ref, or primary / vogt-core for the two static credentials — and /api/vogt/* forwards the same bearer to the core, so POST /api/vogt/projects is audited to the person or agent who sent it. A 401 from the engine means nobody recognises the bearer; a 503 means the core could not be asked, which is an outage rather than a wrong credential, and the engine says so instead of collapsing the two.

The permissions model (scopes)

Every core operation passes two gates (FR-S5): authenticate (who is this) then authorize (may they do it), and the decision is recorded either way. Scopes are instance-wide — an agent with work.write can write to every project (DESIGN.md §4.1).

Scope Gates
read every read, plus writes that touch only the caller's own state (auth.logout, preference.set)
work.write work-item writes — create, transition, comment
project.write project register/import and project-level writes
writeback exactly forge.writeback (arming forge write-back)
admin token minting, actor creation, password logins (user.*), and instance ops — init, migrate, backup, restore, clone, import, serve
  • The default session scope set is read,work.write,project.write,writeback (agent_session_scopes, #726) — everything except admin, applied to every session however it was launched. Narrow it in config only if this instance truly wants to.
  • Loopback is admin. The CLI acting on the core's own store bypasses the bearer gate, so vogt token issue inside the core container is the way to mint or widen a token when no admin bearer is available.
  • A 403 names the requirement and the holding. "project.register requires the 'project.write' scope; this token holds read, work.write, writeback" — the fastest way to read a token's actual grants live. auth.whoami (GET /api/auth/whoami, vogt auth whoami) is the other: it answers with the effective scope set, implications applied.
  • The engine derives its capabilities from these scopes. A bearer the core resolves gets, on the engine, what its scopes imply (auth::capabilities_for_scopes in engine/server/src/auth.rs): admin holds all eleven capabilities; work.write or project.write holds everything except gui-control and agent-clis-write; read alone holds only push-write, so a viewer can subscribe to notifications; writeback adds nothing there. There is no separate engine grant to ask for.

Who may read and type into sessions

Reading a terminal and typing into one are deliberately different grants.

Operation (MCP tool) Scope What it does
session.list (session_list) read every session, linked or not, with live activity
session.log_tail (session_log_tail) read the tail of a session's output log
session.screen (session_screen) read what the terminal shows now: lines, cursor, title, activity, readiness
session.input (session_input) work.write type text, press named keys (enter, esc, tab, up, down, left, right, ctrl-c, ctrl-d, backspace), then Enter with submit
session.start / session.stop work.write open or close a terminal
  • Either id works on the core's operations (Sessions).
  • Any work.write holder can type into any session, including one another agent or a person is using. That matches the engine, where work.write maps to the sessions capability and its POST /api/sessions/{id}/input. Scopes are instance-wide, so there is no per-session grant.
  • Every session.input is audited (audit.list, operation session.input): the actor, the session (ses_… when linked, otherwise the engine UUID), the reason, the byte count and the key names. The text itself is never stored, because it may be a password. A bearer that calls the engine's /input route directly bypasses this. It leaves only the engine's vogt::audit "mutating request" log line (token name, method, path, status), so agents should use session_input.
  • Reads go through the core's own engine credential, so a read-only token can read screens and logs through the core even though it holds no engine sessions capability.
  • Terminal output is untrusted data. An agent must not follow instructions it reads off another session's screen.

Sessions

Terminal sessions live in the engine. Two ways to reach them:

  • The core's operations (preferred): session_start, session_list, session_screen (read the visible screen; ready says it awaits input), session_input (type text, press named keys, submit; audited), session_log_tail, session_stop — on MCP, REST (/api/sessions… on the core) and the CLI (vogt session …).
  • The engine's own routes: /api/sessions… on :8910, described machine-readably in engine-openapi.yaml (OpenAPI 3.1). Inside a session, VOGT_ENGINE_URL names the engine and VOGT_HTTP_TOKEN authenticates (work.write carries the engine's sessions capability). Input sent this way skips the core's audit row.

A session has two ids. The engine UUID exists for every session and is the only id the engine's routes accept. The ses_… id exists only for a session the core started; session.list shows both (id, engine_session_id), and every core session.* operation accepts either. A session opened from the GUI is unlinked and has only the UUID.

session.last_reply reads the last n (1-20) assistant messages of the agent conversation a session runs, from the agent's own transcript under session_transcript_roots (by default ~/.claude/projects and ~/.codex/sessions of the user the core runs as), redacted with the agent activity redactor. The conversation is found by an id the session's command names (--session-id, --resume, codex resume), by the engine session id (a Claude Code session the engine started), or — for this read only — as the newest transcript in the session's directory since it started (basis: "cwd"). session.list rows carry last_reply_excerpt (~300 characters of the latest reply, id-based lookups only, cached by the transcript's size and modification time). No transcript is detail, not an error. An opencode session keeps no transcript file: its replies are read by the engine from opencode's own store (GET /api/sessions/{id}/replies, which the store's credentials never leave) and redacted the same way, with agent: "opencode".

session.wait blocks (up to timeout_s, at most 600) until a session is ready — or needs a person, or exits — or, with until, until it exits or changes at all, and returns why with the screen: one call instead of a polling loop. session.report_blocked / session.report_unblocked (work.write, audited) let an agent say it is blocked on a person; the report shows as blocked on session.list and session.screen, raises an Inbox session.blocked entry and a push. session.start takes autopilot (see AGENT_GUIDE.md).

Rows of session.list and session.sweep carry running. It holds the agent, model and reasoning effort the session is actually running, each with its basis:

  • transcript: what Claude Code or Codex recorded for its latest turn, so a model the CLI defaulted to, or one switched mid-session, is the one shown;
  • command: a --model, --effort, -m or -c model_reasoning_effort= flag;
  • asked: what session.start asked for.

The row's own model and effort stay what was asked. An unknown is null, never guessed. template is also filled in for an unlinked session when the engine knows it.

Rows of session.list and session.sweep carry resources: the RSS, CPU (percent of one core over the last ~10 s) and process count of the session's whole process tree, as the engine last sampled them, with over_threshold past the deployment's ENGINE_SESSION_RSS_WARN. session.list with order: "rss" lists the heaviest first.

session.input reports what became of the input. submitted is true when Enter was pressed, by submit or as one of the keys. delivery is:

  • typed: no Enter;
  • delivered: a turn started after it;
  • queued: a turn was already running, or the agent shows its queued-message hint;
  • unconfirmed: nothing observable within about 2 s.

delivery_evidence gives the reason. With confirm: false, the call returns without watching. A refused input (no such session, or a session that cannot be woken) is an error, not a delivery value.

A session stopped through session.stop reads activity: "stopped", with stopped_by and stop_reason on its row, whatever its exit code. The core passes the caller's identity and reason to the engine before the kill. errored means a non-zero exit nobody asked for, so routinely reaped child sessions no longer look like crashes (WI-913).

session.start takes permission_mode:

  • default: Claude Code's own mode (auto) plus the deployment's driven-session policy. Routine work, including merging its own green PR in a listed repository, proceeds. Prod-mutating, destructive, shared-resource and secret-exposing actions are denied.
  • accept_edits: file edits are accepted and everything else asks.
  • bypass: no permission checks, for one trusted task. Only a person may grant it; an agent caller gets 403 bypass_refused. It is recorded on the session.started event. "An agent" includes one in a session the engine started itself (the GUI, a protected template): session.token (below) gives such a session its own agent credential.

session.token (work.write, audited, POST /api/sessions/token) is the session engine's call, refused to every other caller (403 engine_only). For an agent session the engine starts without a credential of its own (Claude Code, Codex or opencode from the GUI or a protected template), it mints a token bound to the agent actor agent:engine:<engine id>, with agent_session_scopes (what session.start gives its own sessions). revoke: true revokes them when the session ends, and a new mint (a wake) supersedes the last. Without it, such a session ran with the pod's brokered token, which is bound to a person, so its agent counted as that person: it could grant bypass, and its writes were attributed to them (WI-926). A plain shell keeps the pod's token, because the person at it is a person.

The posture shows on session rows as permission_mode. See ENGINE.md, "Permission posture".

session.answer (work.write, audited) answers the dialog a session shows. The session must be awaiting-approval, which covers permission dialogs and the startup gates folder-trust, external-imports and read-outside-cwd (approval.kind). Choose by option (number) or label, with expect_question so a dialog that changed is refused. The engine moves the highlight itself and reports dismissed. approval.options on the list, screen and sweep rows lists the menu.

session.sweep (read) is the oversight table, built in one call. It has a row for every live and hibernated session, ordered by who needs attention: approval, blocked, waiting (at its prompt, wanting the next instruction), stalled (running, but silent for stall_after_minutes, default 10), running, idle, hibernated. Each row carries the reason, the full session.list row (turn timing, last_reply_excerpt, blocked, approval) and the last screen_lines lines of its screen. counts gives the rows per class and needs_you. Use it instead of a session_screen per session.

session.hibernate (work.write, audited) stops a session's processes to free their memory and revokes its token. The session stays listed with activity: "hibernated", a hibernation (at, trigger, reason, resumable) and its last screen. session.wake starts it again under the same id by resuming its agent conversation (conversation_id). It mints a new token for the same actor and revokes the old one. session.input on a hibernated session wakes it, waits until it is ready (wake_timeout_s, default 120) and then types; the result says woke. session.screen and session.wait never wake: a wait answers at once with outcome: "hibernated" and the kept screen. session.keep_awake pins a session against the engine's idle policy. session.set_role (work.write, audited) nominates a session as oversight — the one supervising the others — or makes it a worker again; session.start takes the same role. It is a person's nomination: an agent principal gets 403 role_refused, because the role is what lets a session ask for grants on another session's behalf (below), and a session that could nominate itself would make that rule self-service. An oversight session is pinned awake as it becomes one, rows carry role, and the GUI lists oversight sessions first (WI-957).

session.bind_work (POST /sessions/work-item, work.write, audited) declares which work item a session serves — work_item: "WI-7" — or that it serves none (work_item: null); rebinding is one call (WI-998). One current item per session: the sequence of bindings is the audit log (audit.list(entity_id=<ses_…>), events session.work_bound / session.work_unbound). Any work.write principal may bind, including the session itself (omit id inside a session Vogt started) and an overseer for its children. Binding never moves the terminal or the item's state, is allowed on a finished item, records the item's declared branch as a start does, and reports project_mismatch when the item is filed under another project. A stopped session's binding is history and is refused (409). The core row is written first, then the engine's work_item label; the result's engine_label (written, not_found, unavailable) says whether the label landed, which is never fatal. A session the GUI started has no core row: it is bound by the engine label alone, and session.list reports it with linked: false. A session started for an item gets VOGT_WORK_ITEM in its environment. Session rows carry work_item_title and work_item_state; session.history_list rows carry work_item. A work.transition into a finished state answers live_sessions — the sessions still bound and running or hibernated — as a warning: it never refuses and never unbinds. Inbox entries about a session (session.blocked, session.attention) carry the bound item as work_item_ref.

session.grant_request (work.write, audited) asks a person to approve one named credential (secret_name, project_id, optional var; uses once or ttl; ttl_seconds 60 to 86 400) for one live session (target). A session may ask for itself. Asking for another session requires the caller to be an oversight session. The request appears in the Inbox as session.grant_request, with an action of kind grant. session.grant_decide (approve | deny) is refused for every agent principal: only a person decides. An approval is applied to the session by the engine before it is recorded, so an engine refusal leaves the request pending with its reason. session.grant_revoke withdraws a pending grant or revokes an approved one at once; a person or the asker may. session.grant_list (read) lists grants by state (pending, approved, denied, revoked, expired) or target; a person sees every grant, an agent only its own session's. Rows carry names, never a value. The Inbox entry names the target as the person knows it (title, role, agent, project) and says who is asking and whether it is asking for itself; those come from the engine and the core, not from the request. The engine half and the session's vogt-agent-auth fetch VAR are ENGINE.md §9, and the design is design/oversight-grants.md.

Only a session whose conversation id the engine knows can hibernate: Claude Code started by Vogt, or any resume. A shell needs allow_shell, and wakes as a fresh shell. The engine side is ENGINE.md, "Hibernation".

Rows of session.list and session.screen carry the engine's live turn_started_at (when the agent last went to work from rest) and last_output_at (when the terminal last printed), which tell a long turn from a hung one; and, while activity is awaiting-approval (an agent CLI's permission dialog), an approval with the question, the command_excerpt and deadline_seconds before the CLI denies by itself. Such a session is an Inbox entry "… is asking for approval". session.screen takes scrollback_lines (0–2000) for the history above the screen.

The step-by-step recipe (start with a task, wait until ready, read, answer menus, stop), the activity states and the safety rules are in ENGINE.md, "Driving a session".

Quick reference

# Core (inside the deployment)
GET  http://<core>:8000/api/status            # core token
GET  http://<core>:8000/docs                   # Swagger UI (internal)
GET  http://<core>:8000/openapi.json           # raw spec

# Engine / front door
GET  http://<engine>:8910/api/status           # any core token (session or API), or ENGINE_TOKEN
GET  http://<engine>:8910/readyz               # unauthenticated health
POST http://<engine>:8910/api/auth/login       # {username, password} -> {actor, token, secret}; unauthenticated
GET  http://<engine>:8910/api/vogt/auth/whoami # who this bearer is, with effective scopes
POST http://<engine>:8910/api/vogt/auth/logout # revoke the bearer this call carries
POST http://<engine>:8910/api/vogt/...         # proxied to the core, caller's bearer forwarded
POST http://<engine>:8910/mcp                  # proxied to the core (MCP)
GET  http://<engine>:8910/api/sessions         # engine sessions; spec: docs/engine-openapi.yaml
GET  http://<engine>:8910/api/sessions/<uuid>/screen  # rendered screen (`sessions` capability)

# People (admin, via loopback in the core container); the password is read
# from stdin, a file, or a hidden prompt — never from argv
docker exec -i <core-container> \
  vogt user create --username ada --display-name "Ada Lovelace" \
  --scopes read,work.write,project.write --password-stdin --reason "<why>" < ada-password
docker exec -i <core-container> vogt user passwd --username ada --password-stdin --reason "<why>" < new-password
docker exec <core-container> vogt user list
docker exec <core-container> vogt user remove --username ada --reason "<why>"

# Agents: mint / widen an API token (admin, via loopback in the core container)
docker exec <core-container> \
  vogt token issue --actor <ref> --name <n> --scopes read,work.write,project.write,writeback --reason "<why>"

The Inbox: who caused it, saved filters, and the badge

  • Actor fields. Every inbox.list entry carries actor_login, actor_kind (human | bot, null when unresolved) and actor_relation (org_member | external | unknown). A GitHub notification thread names no author, so the notifications collector follows the thread's latest_comment_url (else the subject) at collect time, cached per (url, updated_at) and bounded per sweep, and stores the raw facts (login, user_type, association, org_member) on the observation's actor block. Reads classify from those stored facts and never call the forge. External means not a member of the repository's owning org: the org's member list (cached for an hour) is the source of truth, a reported MEMBER/OWNER association also counts as a member, outside collaborators are external, and with no readable list the association decides. A bot is user.type == "Bot", a login ending [bot], or a login on inbox_bot_logins (default dependabot, renovate, renovate-bot, github-actions), and is never external. Drift, CI and agent entries are the instance itself: bot, org_member. Issue and PR observations also keep author_type and author_association.
  • inbox.list --actor — any (default), external, org, bot, server-side, so paging and counts agree with the filter; a cursor belongs to its filter. Under external, actor_unknown_hidden says how many otherwise-matching entries were hidden because their author is unknown.
  • preference.get / preference.set (GET/POST /api/preferences, vogt preference get|set, MCP preference_get/preference_set) — the caller's own settings, a JSON object per namespaced key, versioned. set takes value (JSON text from the CLI; {} clears), optional expected_version (0 = only if never written; a mismatch is a 409 preference_version_conflict) and a reason; it is audited like any declared write and needs only read, because it can only write the caller's own row. inbox.filter is validated: {"sources": [...] | null, "actor": "any|external|org|bot", "triage_states": ["active", ...]}.
  • place.metrics — inbox_active is the badge: the count under the caller's saved inbox.filter (the same answer inbox.list gives under it; free-text search is client-side and never counted). inbox_active_unfiltered is every active entry and inbox_filter the filter applied (null = none). The count reads only stored fields, and one Inbox projection serves every badge read until the declared revision or the event feed moves (at most 5 s).

Agent activity: what agents did, searchable

Opt-in. With agent_activity_roots set (claude = "~/.claude/projects", codex = "~/.codex/sessions"), every sweep's agent-activity collector reads new transcript lines, at most agent_activity_max_bytes_per_sweep (32 MiB) per sweep, newest files first, and stores one row per tool call in the observed store. Without roots the collector is not registered, and both reads say so in detail rather than returning an empty list.

Operation (MCP tool) Route CLI Scope
agent_activity.search (agent_activity_search) GET /api/agent-activity vogt agent-activity search read
agent_activity.summary (agent_activity_summary) GET /api/agent-activity/summary vogt agent-activity summary read
  • search filters by q (case-insensitive substring of the tool name, the call summary or the error excerpt), service (an exact tag such as github, docker, komodo or infisical), tool, errors_only, since, project (calls made in the project root or under it, worktrees included) and session. Every filter narrows. Results are newest first and paged with limit (≤ 500) and offset, and next_offset is set while a full page came back. Each event carries at, finished_at, duration_ms, agent (claude | codex), agent_session_id, vogt_session_id, project, cwd, tool, summary, services, error and excerpt.
  • summary returns one row per agent conversation, most recently active first, narrowed by session, project and since. Each row has calls, errors, error_rate, tool_wait_ms (wall-clock time spent waiting on tool results), unfinished, tools (calls per tool) and services (calls per tag).
  • session takes a Vogt ses_… id, an engine session id, or the agent's own conversation id. A Claude Code session that Vogt started uses the engine session id as its conversation id, so such a session links (vogt_session_id). Codex conversations, and Claude sessions resumed under an older id, have no link.
  • Redaction happens at ingest. The summary and the excerpt are redacted before they are stored. Redaction removes token, key, JWT and PEM shapes, credential-named assignments, flags and JSON fields, Authorization headers, URL user-info, and long random strings. Only a failed call keeps an excerpt, a redacted head and tail of about 400 characters. Raw output is never stored. Output from a call that dumps configuration or environment (.config.environment, printenv, kubeconfig reads, .env files, secrets CLIs) is replaced with [withheld: …], and so is output shaped like a kubeconfig or an env listing.
  • Tags and the error flag are heuristics. Built-in service patterns can be extended or removed with agent_activity_services. A call is an error when the agent flagged it, when its wrapper reported a failing exit status, or when the output starts with a failure line. File and search tools (Read, Grep, …) count only the agent's own flag.
  • The index is local to the instance and is never synced to a forge. It can be regenerated: clearing the agent_activity* tables re-reads the transcripts from the beginning on the next sweeps.

CI watching and deployed versions

  • Watched-ref CI alerts. forge-checks reads the newest runs plus one bounded page of pushed runs only (GitHub actions/runs?event=push, 50), so a tag or default-branch run is not pushed off the page by pull-request churn. Check subjects are now ci:{repo}@{sha}:{workflow}@{ref} — the ref joined the key because one commit is built on main and again on the tag cut from it. A failed run on a watched ref (ci_alert_branches, ci_alert_tags) has its failed jobs looked up (failed_jobs: name, conclusion, log URL), at most 5 new lookups per project per sweep; a looked up list is carried forward from the previous observation. inbox.list raises one ci entry of kind ci.ref_failure per workflow lane whose newest decisive run failed — source_url is the failed job's log — and the entry disappears when a later run in the lane succeeds. Its entry_key is the run (id, attempt, conclusion), so an archived alert stays archived when the job list arrives a sweep later.
  • Bound-branch CI. inbox.list raises a ci.branch_concluded entry, with work_item_ref, for the settled newest revision of every branch an open work item is bound to. After each sweep that ran forge-checks, the core publishes one ci.branch_concluded event (entity <ref>:<branch>@<sha>:<state>, summary: work_item, branch, revision, state, failing, sessions_notified) per fresh conclusion (last run finished within 6 hours) that has no such event yet, and, unless ci_watch_notify_sessions is off, types a one-line notice plus Enter into each live session started for the item. Subscribe to the event feed to wake on it; nothing needs to poll a forge.
  • deployed.versions (GET /api/deployed-versions, vogt deployed-versions, MCP deployed_versions; read) — one row per lane in deploy_lanes: name (the configured lane name; also echoed as lane), status (at_head | behind | diverged | unknown | not_collected), deployed_sha and whether it came from the running instance (live, its version endpoint) or the pipeline receipt, version, source_tag, receipt_status, head_sha, commits_behind, unpromoted_commits (sha, subject, work item refs) and unpromoted_work_items (ref, title, state), plus detail when a source could not be read. Filters: project, lane. The deploy-lanes collector (registered only when lanes are configured) does the reading — a receipt through the forge configured for its host, the version URL without credentials, then a forge compare of the deployed SHA against the lane's branch — so this read makes no network call. With no lanes configured it answers configured: 0 and says so; a configured lane no sweep has read is not_collected, never at_head. A receipt whose status (or live_smoke.status) is failed raises a deploy.failed Inbox entry.

Export and import

Operation Surfaces Scope What it does
export CLI, POST /api/instance/export, MCP export read writes the declared entities as JSON (format 2: comments, relations, the initiative link, timestamps, the clone stamp; never a credential) to a path on the core's filesystem; project narrows it to one project
import CLI only (local-only, like restore and clone) admin merges such a file into this instance; a dry-run report unless --apply --confirm, then one audited write; --strict refuses any both-sides change

The result of import is the same in a dry run and an apply: created, updated, conflicted, skipped and unchanged totals, a per-entity tally (by_entity), the baseline it measured change against (base, base_source), and one changes entry per entity not left unchanged — with ref (this instance's) and incoming_ref (the export's) for a work item. The matching rules and the conflict policy are in DEPLOYMENT.md §5.

Calling work and project operations from an agent

The work tools are shaped so an agent's first call succeeds and its result fits in context.

  • Parameter aliases. A common name is accepted for the field it means, on every transport that validates through the registry (MCP, and the run_raw path generally): work.get and work.transition take id for ref; work.transition takes to or state for to_state; work.list takes status or state for states (one state, a comma-separated string, or a list) and text, search or q for query; project.brief takes project or id for slug. Naming an alias and its field is refused as ambiguous. Each alias is documented on its field in the tool schema.
  • Errors that say what to change. A call whose arguments do not fit fails invalid_params, naming each missing or unknown parameter and listing the parameters the tool does take. reason is never defaulted — every write is audited and the registry refuses to build a write with an optional reason — so a missing one is told exactly that, with an example.
  • Transitions. A refused edge (transition.not_allowed) lists the edges allowed from the current state and the shortest path to the target. work.transition with walk=true takes that path, one ordinary audited transition per edge, each recording the caller's reason annotated (walk 2/3: in_progress -> review); the result's walked lists the states passed through. Only the workflow's own edges are walked and finished states are never passed through, so a walk to done goes via review and cannot close and reopen an issue on the way. A depends_on blocker or an upstream write-through refusal is checked before the first hop, so a walk that would stop part-way is refused before it moves anything.
  • Summary mode and paging. work.list, backlog and project.brief take mode: summary (the default) returns compact rows — work.list items carry only ref, title, kind, state, priority and project_slug; backlog and project.brief rows keep their ranking fields but drop the embedded item (bodies) — and full returns everything. The PWA asks for full. work.list and backlog return next_offset (null on the last page). work.list --query matches title, body and ref, case-insensitively; naming a finished state in states includes finished items without include_finished.
  • Can I create here? Each project.list entry carries writable and writable_reason: whether a default work.create (no local_only) would land there now — forge-linked, write-back policy permits create, a forge credential resolves, the repo URL parses — and, if not, whether it would refuse project_not_linked or upstream_write_refused and how to fix it. local_only=true creates a local record on any project.
  • Unlinked projects. A project-scoped work.list on an unlinked project answers items: [] with link_state: "unlinked"; when the project holds open native items, detail says how many, names a few refs, and that they are still reachable by ref. Native items (WI-n) on an unlinked project take comments, transitions (including to done) and field edits; only a default work.create and label edits refuse project_not_linked, and that refusal says so.

Deploy diagnostics

instance.diagnostics (GET /api/instance/diagnostics, vogt diagnostics, MCP instance_diagnostics; read scope) answers "is this instance what it should be, and is it well" in one read, so confirming a deploy needs neither tailnet access nor the orchestrator:

  • vogt_version, image_digest (as the deployment stated it through VOGT_IMAGE_DIGEST; null when unstated, never guessed), instance_id, started_at and uptime_seconds of the core process;
  • checks — named readiness checks (declared_store, observed_store schema against this build, engine liveness, collection freshness), each ok, degraded, failing or not_configured, rolled up into status;
  • migrations — applied, expected and pending per store;
  • recent_log — the newest log_lines (default 20, at most 200) warning-or-worse lines this core process logged, with URL credentials, bearer values, token shapes and secret-named key=value pairs redacted. capturing: false (a one-shot CLI process) means nothing is retained, not that nothing went wrong. Only the core's own log is here; the engine's log is not reachable from the core.
  • peer — with peer=true, the same answer from the instance at diagnostics_peer_url (e.g. prod's https://…/api/vogt from dev), authenticated with the read-scoped token in diagnostics_peer_token_file. Reported as not_requested, not_configured, ok (with the peer's answer, as it sent it), unreachable, refused or invalid_response. The peer is asked with peer=false, so two instances configured as each other's peer never recurse.

See also

  • DESIGN.md §4 — the security model (FR-S*), scopes, and per-project scope deferral.
  • ENGINE.md — the engine, the agent-auth broker, and identity passthrough.
  • CONFIG.md — generated config reference (agent_session_scopes, session_ttl_days, bootstrap_*_token_*, ENGINE_AGENT_AUTH_*).