Security & access tokens
Itervox serves its dashboard and REST/SSE API from one daemon. This page covers who can do what on it.
The bootstrap token
Section titled “The bootstrap token”On every bind — loopback included — the daemon requires a bearer token
unless you set server.allow_unauthenticated: true. That token is the
bootstrap token, and it is always admin:
ITERVOX_API_TOKENfrom the environment or.itervox/.env(pin one withitervox secret set ITERVOX_API_TOKEN), orITERVOX_SUPERVISOR_TOKEN, which the macOS menu-bar app passes from the Keychain, or- an ephemeral token the daemon generates at startup (printed once on a
terminal, otherwise written to
<logs-dir>/api-token).
Nothing about it changes with token scopes: existing dashboards, the Mac app,
itervox watch and other CLI clients keep working as admin.
Scoped tokens
Section titled “Scoped tokens”To give a teammate, a CI job or a tool less than full control, create a stored token with a scope. Scopes are ordered; each includes the ones below it.
| Scope | Can |
|---|---|
viewer | Watch: every GET route and the live SSE streams (board, logs, sessions, history, settings values). Secrets are redacted: inline env-assignment values in agent and profile commands (ANTHROPIC_API_KEY=*** claude), credentials in URLs, known key shapes, and the raw text of settings files. |
operator | Run the fleet: dispatch and issue control (cancel, resume, terminate, move state, profile and backend overrides), steering messages, line comments and PR reviews from the Changes tab (#238), input replies and approvals, pause/resume all dispatch, memory edits, clearing logs, outbox retries, a read-only live terminal of a tmux session. Same redaction as viewer. |
admin | Everything: settings, tokens, tmux control (New session, keys, kill), a read-write live terminal when sessions.terminal_write is on, workspace reset, the automations configuration and the rules editor. Sees secrets as written. |
Tracker API keys and webhook secrets are never served by any route at any
scope: WORKFLOW.md holds $VAR references that the daemon resolves in
memory.
Managing tokens from the command line
Section titled “Managing tokens from the command line”itervox token edits .itervox/tokens.json next to WORKFLOW.md directly,
so it works whether or not the daemon is running. A running daemon notices
the change within a second — no restart.
# A read-only token for a teammate, valid for 90 days.itervox token create --name "alex laptop" --scope viewer --expires 90d
# An operator token for a bot, captured straight into a file:itervox token create --name ci --scope operator > ci-token
itervox token list # id, name, scope, created, last used, expiryitervox token rotate tok_1a2b3c4d5e6f # new secret, same id/name/scopeitervox token rotate # no id: the one stored admin tokenitervox token revoke tok_1a2b3c4d5e6fThe new secret (it starts with itx_) is printed once, alone on stdout;
the details go to stderr. Store it right away: the file keeps only its
SHA-256 hash. --expires takes 90d, 12h, a date (2027-01-31) or an
RFC 3339 time; expired tokens are refused. --workflow points at another
project’s WORKFLOW.md.
Managing tokens from the dashboard
Section titled “Managing tokens from the dashboard”Settings → Access (admin only) lists the stored tokens with their scope, creation, last use and expiry, creates new ones and rotates or revokes them. A created or rotated secret is shown once with a copy button.
Rotation and revocation
Section titled “Rotation and revocation”Rotating gives a token a new secret and keeps its id, name, scope and expiry; revoking deletes it. Either way the old secret stops working:
- at once, when done through the dashboard or API;
- within one second, when done with
itervox tokenin another process — the daemon checks the file’s identity and modification time at most every 200 ms.
The bootstrap token is not in the store. To change it, set a new
ITERVOX_API_TOKEN and restart (an auto-generated one changes on every
restart). For an admin credential you can rotate without a restart, create a
stored admin token and use that instead.
The token file
Section titled “The token file”.itervox/tokens.json, mode0600, ignored by the.itervox/.gitignorethatitervox initwrites (and the daemon self-heals). Never commit it.- It holds
id,name,scope,hash,created,lastUsedandexpiresper token — never a secret.lastUsedis written at most about once a minute per token. - Writes are atomic and serialized across processes with a lock file
(
tokens.json.lock). - If the file is unreadable or invalid, the daemon refuses every stored token (the bootstrap token keeps working so you can fix it) and never overwrites it.
itervox mcpcreates its own stored token namedmcp(viewer unless started with--token-scope operator) and remembers its secret in.itervox/mcp-token.json(mode0600, gitignored). Revoke it like any other token; the nextitervox mcpstart creates a new one.
What the dashboard shows each scope
Section titled “What the dashboard shows each scope”The dashboard reads your scope from the live snapshot (callerScope) and
hides controls you cannot use: settings and Access for non-admins, the
pause-dispatch toggle and input-reply boxes for viewers. The server enforces
scopes regardless; a refused call answers 403 insufficient_scope naming the
scope it needs, and the dashboard shows that as a toast.
Every token create, revoke and rotate is logged (apitokens: token created,
… revoked, … rotated) with the token’s id, name, scope and who did it
(cli, dashboard:bootstrap or dashboard:<token id>) — never the secret.
itx_… secrets are also masked by the log redactor.
Unauthenticated mode
Section titled “Unauthenticated mode”server.allow_unauthenticated: true turns authentication off: every caller
is admin, exactly as before scopes existed, stored tokens are not
consulted, and the token routes answer 503 tokens_unavailable. The daemon
logs a warning at startup. Cross-origin state-changing requests and
DNS-rebinding Host headers are still refused. Use it only on a fully local,
trusted machine.
The live terminal
Section titled “The live terminal”The Sessions panel’s live terminal is tmux attach-session in a pseudo-terminal the daemon owns, streamed over a WebSocket. What it can reach:
- Which sessions: only the ones the panel may already control — tmux sessions itervox started with New session, and a hand-started session in a matched tmux pane with
sessions.tmux_controlon. - Read-only (operator, and admin by default):
tmux attach-session -r, and the daemon writes nothing the browser sends into it. - Read-write (admin, only with
sessions.terminal_write: true): every key reaches the session — and tmux, so a new window is a shell on the daemon’s host as the daemon’s user. Treat it as a remote shell; keep it off unless the admin token is yours alone. - Viewer: no terminal; the snapshot view only.
How the socket is authenticated: a browser cannot send the Authorization header on a WebSocket, so the dashboard first calls POST /api/v1/sessions/{id}/terminal/ticket with its token. The daemon checks the scope (and the opt-in for write) and returns a ticket that is valid for 30 seconds, for one connection, to that session, in that mode. The socket (GET /api/v1/sessions/{id}/terminal?ticket=…) spends the ticket on its first use and checks again that the token which minted it still exists, has not expired and still holds the scope — a ticket presented together with another token’s Authorization header is refused. Only the ticket’s hash is kept, in memory. The socket’s Origin must be the daemon’s own, an origin in server.allowed_origins, or a same-origin browser request (Sec-Fetch-Site: same-origin); any other origin is refused. Each attach and detach is logged and recorded in the event feed (terminal_attached / terminal_detached); terminal contents never are.
The hub does not proxy the live terminal: it refuses the ticket route, the socket and any WebSocket upgrade (403 terminal_not_proxied). On Windows the routes answer 501 terminal_unsupported.
Agent grants are separate
Section titled “Agent grants are separate”Agents call the daemon through /api/v1/agent-actions/… (comments, PR
merges, input requests, guardrail approvals) with a short-lived per-run
grant that only that run holds. Those routes never accept dashboard tokens
and dashboard tokens never reach agents; scopes do not change them.
Agent processes
Section titled “Agent processes”Tokens control who may call the daemon. What an agent process may touch on
the machine is a separate question: by default it has the daemon user’s full
filesystem access. A profile with isolation: process runs its agent inside
an operating-system sandbox that hides ~/.ssh, ~/.aws, ~/.config/gh,
the project’s .itervox/.env and token files, the hub and dashboard token
files and every other workspace, and lets it write only to its own workspace
(plus its git directories, the temp directory and the CLI’s own state). A run
whose sandbox is unavailable does not start. Hooks are not sandboxed. See
Process isolation.
The desktop app’s terminal
Section titled “The desktop app’s terminal”Open in Terminal in the desktop app’s Sessions window starts a terminal on your machine that runs tmux attach — locally, or over ssh -t (or gcloud compute ssh --tunnel-through-iap) to the remote’s host — as you, with your own SSH credentials. The terminal can therefore reach whatever your SSH login on that host can, which is more than the dashboard token allows: the attached tmux client types into the session, and nothing stops you opening a shell there. It is you at your keyboard, not a new capability of the app or the daemon. It adds no write path into the daemon or into other processes: the app does not run tmux itself, the daemon is unchanged (internal/tmuxctl is still its only tmux caller), and the app offers the action only for sessions it may attach to — those itervox started, and hand-started ones under sessions.tmux_control. The command is built as separate arguments from a checked session name ([A-Za-z0-9_-]) and the connection’s checked destination, never as a shell line from the daemon’s text. See Open in Terminal.
API scope table
Section titled “API scope table”Every route declares its scope in internal/server/route_scopes.go, the one
table the server enforces; a route that is not in it is refused, and CI
fails when a new route has no declaration.
| Method | Route | Scope |
|---|---|---|
GET | /api/v1/deps/analyze/{jobId} | viewer |
GET | /api/v1/events | viewer |
GET | /api/v1/feed | viewer |
GET | /api/v1/history | viewer |
GET | /api/v1/history/prompt-versions | viewer |
GET | /api/v1/issues | viewer |
GET | /api/v1/issues/{identifier} | viewer |
GET | /api/v1/issues/{identifier}/context | viewer |
GET | /api/v1/issues/{identifier}/decisions | viewer (redacted, bounded decision logs, #218) |
GET | /api/v1/issues/{identifier}/diff | viewer (?file= hunks: operator) |
GET | /api/v1/issues/{identifier}/log-stream | viewer |
GET | /api/v1/issues/{identifier}/logs | viewer |
GET | /api/v1/issues/{identifier}/sublog-stream | viewer |
GET | /api/v1/issues/{identifier}/sublogs | viewer |
GET | /api/v1/logs | viewer |
GET | /api/v1/logs/identifiers | viewer |
GET | /api/v1/memory | viewer |
GET | /api/v1/memory/recall | viewer |
GET | /api/v1/model-servers | viewer (URL credentials redacted below admin) |
GET | /api/v1/playbooks | viewer (#218) |
GET | /api/v1/projects | viewer |
GET | /api/v1/projects/filter | viewer |
GET | /api/v1/repo/evals | viewer |
GET | /api/v1/repo/hotspots | viewer |
GET | /api/v1/repo/readiness | viewer |
GET | /api/v1/rules | viewer |
GET | /api/v1/rules/preview | viewer |
GET | /api/v1/sessions | viewer |
GET | /api/v1/sessions/{id}/transcript | viewer |
GET | /api/v1/settings/layers | viewer (raw files and secrets redacted below admin) |
GET | /api/v1/settings/models | viewer |
GET | /api/v1/settings/profiles | viewer (commands redacted below admin) |
GET | /api/v1/settings/reviewer | viewer |
GET | /api/v1/settings/schema | viewer |
GET | /api/v1/skills/analytics | viewer |
GET | /api/v1/skills/analytics/recommendations | viewer |
GET | /api/v1/skills/inventory | viewer |
GET | /api/v1/skills/issues | viewer |
GET | /api/v1/skills/profile-backends | viewer (Operator: run the fleet.) |
GET | /api/v1/state | viewer |
GET | /api/v1/steering/phrases | viewer (#218) |
GET | /api/v1/summary | viewer |
GET | /api/v1/task-templates | viewer (saved task templates, #251) |
GET | /api/v1/tracker/labels | viewer |
GET | /api/v1/tracker/scope | viewer |
GET | /api/v1/tracker/teams | viewer |
GET | /api/v1/tracker/users | viewer |
GET | /api/v1/whoami | viewer |
GET | /metrics | viewer |
POST | /api/v1/backend-health/clear | operator |
POST | /api/v1/client-errors | operator |
POST | /api/v1/deps/analyze | operator |
DELETE | /api/v1/deps/analyze/{jobId} | operator |
POST | /api/v1/dispatch/pause | operator |
POST | /api/v1/dispatch/resume | operator |
DELETE | /api/v1/issues/{identifier} | operator |
POST | /api/v1/issues/{identifier}/ai-review | operator |
POST | /api/v1/issues/{identifier}/backend | operator |
POST | /api/v1/issues/{identifier}/cancel | operator |
POST | /api/v1/issues/{identifier}/comment | operator |
DELETE | /api/v1/issues/{identifier}/deps-override | operator |
POST | /api/v1/issues/{identifier}/deps-override | operator |
POST | /api/v1/issues/{identifier}/dismiss-input | operator |
POST | /api/v1/issues/{identifier}/failures/ack | operator |
DELETE | /api/v1/issues/{identifier}/logs | operator |
POST | /api/v1/issues/{identifier}/pr-review | operator (one GitHub review, never merges, #238) |
POST | /api/v1/issues/{identifier}/playbook | operator (per-issue playbook override, #218) |
POST | /api/v1/issues/{identifier}/review-comments | operator (to the running agent or the PR, #238) |
POST | /api/v1/issues/{identifier}/review-continue | operator (the whole draft review to the agent: steer the live run, or queue it for a new run) |
POST | /api/v1/issues/{identifier}/profile | operator |
POST | /api/v1/issues/{identifier}/provide-input | operator |
POST | /api/v1/issues/{identifier}/reanalyze | operator |
POST | /api/v1/issues/{identifier}/resume | operator |
PATCH | /api/v1/issues/{identifier}/state | operator |
DELETE | /api/v1/issues/{identifier}/sublogs | operator |
DELETE | /api/v1/issues/{identifier}/sublogs/{sessionId} | operator |
POST | /api/v1/issues/{identifier}/terminate | operator |
DELETE | /api/v1/logs | operator |
POST | /api/v1/memory | operator |
DELETE | /api/v1/memory/{id} | operator |
PUT | /api/v1/memory/{id} | operator |
POST | /api/v1/memory/{id}/approve | operator |
POST | /api/v1/memory/{id}/pin | operator |
POST | /api/v1/memory/{id}/promote | operator |
POST | /api/v1/memory/{id}/reject | operator |
DELETE | /api/v1/outbox/{id} | operator |
POST | /api/v1/outbox/{id}/retry | operator |
POST | /api/v1/refresh | operator |
POST | /api/v1/repo/readiness/verify-skill-issue | operator (creates a tracker issue, #218) |
POST | /api/v1/sessions/{id}/message | operator (steering) |
GET | /api/v1/sessions/{id}/screen | operator (a live terminal pane) |
POST | /api/v1/sessions/{id}/terminal/ticket | operator (a read-only live terminal; write also needs admin and sessions.terminal_write) |
POST | /api/v1/skills/check-refs | operator (read-only, but a POST) |
POST | /api/v1/skills/scan | operator |
POST | /api/v1/tracker/filter/preview | operator (read-only, but a POST) |
POST | /api/v1/tasks | operator (New task: creates an issue, may dispatch, #251) |
PUT | /api/v1/tasks/{identifier}/instructions | operator (until the task starts, #251) |
POST | /api/v1/automations/{id}/test | admin |
PUT | /api/v1/projects/filter | admin |
PUT | /api/v1/rules/{layer} | admin |
POST | /api/v1/sessions | admin (starts a tmux session) |
DELETE | /api/v1/sessions/{id} | admin |
POST | /api/v1/sessions/{id}/stop | admin (graceful / force stop) |
POST | /api/v1/sessions/{id}/keys | admin |
PUT | /api/v1/settings/agent/max-retries | admin |
PUT | /api/v1/settings/agent/max-switches-per-issue-per-window | admin |
PUT | /api/v1/settings/agent/switch-window-hours | admin |
PUT | /api/v1/settings/automations | admin |
POST | /api/v1/settings/deps-analysis-mode | admin |
PUT | /api/v1/settings/dispatch-strategy | admin |
POST | /api/v1/settings/inline-input | admin |
PUT | /api/v1/settings/layers/{layer} | admin |
POST | /api/v1/settings/models/refresh | admin |
DELETE | /api/v1/settings/profiles/{name} | admin |
PUT | /api/v1/settings/profiles/{name} | admin |
PUT | /api/v1/settings/reviewer | admin |
POST | /api/v1/settings/ssh-hosts | admin |
DELETE | /api/v1/settings/ssh-hosts/{host} | admin |
PUT | /api/v1/settings/tracker/failed-state | admin |
PUT | /api/v1/settings/tracker/states | admin |
POST | /api/v1/settings/workers | admin |
POST | /api/v1/settings/workspace/auto-clear | admin |
POST | /api/v1/skills/fix | admin (writes skill files) |
POST | /api/v1/task-templates/{name} | admin (writes .itervox/tasks/<name>.md, #251) |
PUT | /api/v1/task-templates/{name} | admin (#251) |
DELETE | /api/v1/task-templates/{name} | admin (#251) |
GET | /api/v1/tokens | admin |
POST | /api/v1/tokens | admin |
DELETE | /api/v1/tokens/{id} | admin |
POST | /api/v1/tokens/{id}/rotate | admin |
PUT | /api/v1/tracker/scope | admin |
DELETE | /api/v1/workspaces | admin |
* | /* | none (public) (the embedded SPA shell and its assets) |
GET | /api/v1/health | none (public) |
GET | /api/v1/ready | none (public) |
POST | /api/v1/webhooks/{tracker} | none (public) |
GET | /api/v1/sessions/{id}/terminal | single-use terminal ticket (the live terminal’s WebSocket; the ticket needs operator, or admin for write) |
POST | /api/v1/agent-actions/{identifier}/comment | per-run agent grant |
POST | /api/v1/agent-actions/{identifier}/comment_pr | per-run agent grant |
POST | /api/v1/agent-actions/{identifier}/create-issue | per-run agent grant |
POST | /api/v1/agent-actions/{identifier}/guardrail/approvals | per-run agent grant |
GET | /api/v1/agent-actions/{identifier}/guardrail/approvals/{id} | per-run agent grant (Viewer: reads and streams.) |
POST | /api/v1/agent-actions/{identifier}/guardrail/events | per-run agent grant |
POST | /api/v1/agent-actions/{identifier}/guardrail/lanes | per-run agent grant |
POST | /api/v1/agent-actions/{identifier}/merge_pr | per-run agent grant |
POST | /api/v1/agent-actions/{identifier}/move-state | per-run agent grant |
POST | /api/v1/agent-actions/{identifier}/provide-input | per-run agent grant |
See also the API reference and Remote Access & Mobile.