Skip to content

Security & access tokens

Itervox serves its dashboard and REST/SSE API from one daemon. This page covers who can do what on it.

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_TOKEN from the environment or .itervox/.env (pin one with itervox secret set ITERVOX_API_TOKEN), or
  • ITERVOX_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.

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.

ScopeCan
viewerWatch: 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.
operatorRun 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.
adminEverything: 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.

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.

Terminal window
# 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, expiry
itervox token rotate tok_1a2b3c4d5e6f # new secret, same id/name/scope
itervox token rotate # no id: the one stored admin token
itervox token revoke tok_1a2b3c4d5e6f

The 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.

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.

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 token in 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.

  • .itervox/tokens.json, mode 0600, ignored by the .itervox/.gitignore that itervox init writes (and the daemon self-heals). Never commit it.
  • It holds id, name, scope, hash, created, lastUsed and expires per token — never a secret. lastUsed is 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 mcp creates its own stored token named mcp (viewer unless started with --token-scope operator) and remembers its secret in .itervox/mcp-token.json (mode 0600, gitignored). Revoke it like any other token; the next itervox mcp start creates a new one.

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.

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 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_control on.
  • 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.

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.

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.

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.

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.

MethodRouteScope
GET/api/v1/deps/analyze/{jobId}viewer
GET/api/v1/eventsviewer
GET/api/v1/feedviewer
GET/api/v1/historyviewer
GET/api/v1/history/prompt-versionsviewer
GET/api/v1/issuesviewer
GET/api/v1/issues/{identifier}viewer
GET/api/v1/issues/{identifier}/contextviewer
GET/api/v1/issues/{identifier}/decisionsviewer (redacted, bounded decision logs, #218)
GET/api/v1/issues/{identifier}/diffviewer (?file= hunks: operator)
GET/api/v1/issues/{identifier}/log-streamviewer
GET/api/v1/issues/{identifier}/logsviewer
GET/api/v1/issues/{identifier}/sublog-streamviewer
GET/api/v1/issues/{identifier}/sublogsviewer
GET/api/v1/logsviewer
GET/api/v1/logs/identifiersviewer
GET/api/v1/memoryviewer
GET/api/v1/memory/recallviewer
GET/api/v1/model-serversviewer (URL credentials redacted below admin)
GET/api/v1/playbooksviewer (#218)
GET/api/v1/projectsviewer
GET/api/v1/projects/filterviewer
GET/api/v1/repo/evalsviewer
GET/api/v1/repo/hotspotsviewer
GET/api/v1/repo/readinessviewer
GET/api/v1/rulesviewer
GET/api/v1/rules/previewviewer
GET/api/v1/sessionsviewer
GET/api/v1/sessions/{id}/transcriptviewer
GET/api/v1/settings/layersviewer (raw files and secrets redacted below admin)
GET/api/v1/settings/modelsviewer
GET/api/v1/settings/profilesviewer (commands redacted below admin)
GET/api/v1/settings/reviewerviewer
GET/api/v1/settings/schemaviewer
GET/api/v1/skills/analyticsviewer
GET/api/v1/skills/analytics/recommendationsviewer
GET/api/v1/skills/inventoryviewer
GET/api/v1/skills/issuesviewer
GET/api/v1/skills/profile-backendsviewer (Operator: run the fleet.)
GET/api/v1/stateviewer
GET/api/v1/steering/phrasesviewer (#218)
GET/api/v1/summaryviewer
GET/api/v1/task-templatesviewer (saved task templates, #251)
GET/api/v1/tracker/labelsviewer
GET/api/v1/tracker/scopeviewer
GET/api/v1/tracker/teamsviewer
GET/api/v1/tracker/usersviewer
GET/api/v1/whoamiviewer
GET/metricsviewer
POST/api/v1/backend-health/clearoperator
POST/api/v1/client-errorsoperator
POST/api/v1/deps/analyzeoperator
DELETE/api/v1/deps/analyze/{jobId}operator
POST/api/v1/dispatch/pauseoperator
POST/api/v1/dispatch/resumeoperator
DELETE/api/v1/issues/{identifier}operator
POST/api/v1/issues/{identifier}/ai-reviewoperator
POST/api/v1/issues/{identifier}/backendoperator
POST/api/v1/issues/{identifier}/canceloperator
POST/api/v1/issues/{identifier}/commentoperator
DELETE/api/v1/issues/{identifier}/deps-overrideoperator
POST/api/v1/issues/{identifier}/deps-overrideoperator
POST/api/v1/issues/{identifier}/dismiss-inputoperator
POST/api/v1/issues/{identifier}/failures/ackoperator
DELETE/api/v1/issues/{identifier}/logsoperator
POST/api/v1/issues/{identifier}/pr-reviewoperator (one GitHub review, never merges, #238)
POST/api/v1/issues/{identifier}/playbookoperator (per-issue playbook override, #218)
POST/api/v1/issues/{identifier}/review-commentsoperator (to the running agent or the PR, #238)
POST/api/v1/issues/{identifier}/review-continueoperator (the whole draft review to the agent: steer the live run, or queue it for a new run)
POST/api/v1/issues/{identifier}/profileoperator
POST/api/v1/issues/{identifier}/provide-inputoperator
POST/api/v1/issues/{identifier}/reanalyzeoperator
POST/api/v1/issues/{identifier}/resumeoperator
PATCH/api/v1/issues/{identifier}/stateoperator
DELETE/api/v1/issues/{identifier}/sublogsoperator
DELETE/api/v1/issues/{identifier}/sublogs/{sessionId}operator
POST/api/v1/issues/{identifier}/terminateoperator
DELETE/api/v1/logsoperator
POST/api/v1/memoryoperator
DELETE/api/v1/memory/{id}operator
PUT/api/v1/memory/{id}operator
POST/api/v1/memory/{id}/approveoperator
POST/api/v1/memory/{id}/pinoperator
POST/api/v1/memory/{id}/promoteoperator
POST/api/v1/memory/{id}/rejectoperator
DELETE/api/v1/outbox/{id}operator
POST/api/v1/outbox/{id}/retryoperator
POST/api/v1/refreshoperator
POST/api/v1/repo/readiness/verify-skill-issueoperator (creates a tracker issue, #218)
POST/api/v1/sessions/{id}/messageoperator (steering)
GET/api/v1/sessions/{id}/screenoperator (a live terminal pane)
POST/api/v1/sessions/{id}/terminal/ticketoperator (a read-only live terminal; write also needs admin and sessions.terminal_write)
POST/api/v1/skills/check-refsoperator (read-only, but a POST)
POST/api/v1/skills/scanoperator
POST/api/v1/tracker/filter/previewoperator (read-only, but a POST)
POST/api/v1/tasksoperator (New task: creates an issue, may dispatch, #251)
PUT/api/v1/tasks/{identifier}/instructionsoperator (until the task starts, #251)
POST/api/v1/automations/{id}/testadmin
PUT/api/v1/projects/filteradmin
PUT/api/v1/rules/{layer}admin
POST/api/v1/sessionsadmin (starts a tmux session)
DELETE/api/v1/sessions/{id}admin
POST/api/v1/sessions/{id}/stopadmin (graceful / force stop)
POST/api/v1/sessions/{id}/keysadmin
PUT/api/v1/settings/agent/max-retriesadmin
PUT/api/v1/settings/agent/max-switches-per-issue-per-windowadmin
PUT/api/v1/settings/agent/switch-window-hoursadmin
PUT/api/v1/settings/automationsadmin
POST/api/v1/settings/deps-analysis-modeadmin
PUT/api/v1/settings/dispatch-strategyadmin
POST/api/v1/settings/inline-inputadmin
PUT/api/v1/settings/layers/{layer}admin
POST/api/v1/settings/models/refreshadmin
DELETE/api/v1/settings/profiles/{name}admin
PUT/api/v1/settings/profiles/{name}admin
PUT/api/v1/settings/revieweradmin
POST/api/v1/settings/ssh-hostsadmin
DELETE/api/v1/settings/ssh-hosts/{host}admin
PUT/api/v1/settings/tracker/failed-stateadmin
PUT/api/v1/settings/tracker/statesadmin
POST/api/v1/settings/workersadmin
POST/api/v1/settings/workspace/auto-clearadmin
POST/api/v1/skills/fixadmin (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/tokensadmin
POST/api/v1/tokensadmin
DELETE/api/v1/tokens/{id}admin
POST/api/v1/tokens/{id}/rotateadmin
PUT/api/v1/tracker/scopeadmin
DELETE/api/v1/workspacesadmin
*/*none (public) (the embedded SPA shell and its assets)
GET/api/v1/healthnone (public)
GET/api/v1/readynone (public)
POST/api/v1/webhooks/{tracker}none (public)
GET/api/v1/sessions/{id}/terminalsingle-use terminal ticket (the live terminal’s WebSocket; the ticket needs operator, or admin for write)
POST/api/v1/agent-actions/{identifier}/commentper-run agent grant
POST/api/v1/agent-actions/{identifier}/comment_prper-run agent grant
POST/api/v1/agent-actions/{identifier}/create-issueper-run agent grant
POST/api/v1/agent-actions/{identifier}/guardrail/approvalsper-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/eventsper-run agent grant
POST/api/v1/agent-actions/{identifier}/guardrail/lanesper-run agent grant
POST/api/v1/agent-actions/{identifier}/merge_prper-run agent grant
POST/api/v1/agent-actions/{identifier}/move-stateper-run agent grant
POST/api/v1/agent-actions/{identifier}/provide-inputper-run agent grant

See also the API reference and Remote Access & Mobile.