REST API

Paths use the Rune Box names: citadels (sandboxes), charters (policies), cohorts (agent groups), chronicle (signed audit trail), conclave (approvals), perimeter (network controls), rationing (budgets).

Authentication

• serve refuses a non-loopback --bind unless auth is configured.
• Single token: --token or RUNEWARD_API_TOKEN. Multi-principal RBAC: RUNEWARD_AUTHZ_FILE, a JSON store of principals, each with a token, launch scope, optional approval-profile scope and admin flag.
• OIDC: RUNEWARD_OIDC_ISSUER and RUNEWARD_OIDC_AUDIENCE. Signed Rune Box claims map to the same model as local tokens.
• Send Authorization: Bearer <token> or X-Runeward-Token on every request except /healthz and the static dashboard shell.
• Under RBAC, non-admins see only their tenant's resources; admins see all. Agents can share a tenant and stay separately attributable.
• The terminal WebSocket uses a short-lived, single-use scoped ticket, so long-lived credentials never appear in URLs. POST /v1/tickets mints one: body {"kind":"ide","sandbox_id":"<id>"}, where kind may also be terminal or conversation (both need sandbox_id) or download.
• Non-loopback listeners need TLS (--tls-cert/--tls-key) unless --allow-insecure-http acknowledges a trusted TLS-terminating proxy.
• Request bodies are capped at 16 MiB.

See Security.

Errors

Non-governance failures carry a stable code: authentication_required, authz_denied, not_found, conflict, rate_limited, invalid_request or internal_error. Policy denials return {"verdict":"deny",...}. Approval pauses return {"verdict":"require-approval","approval_id":"..."}. SDKs raise different exception types for authorization and policy denials.

Health and identity

Sandboxes

Governed actions

Paths are under /v1/citadels/{id}.

Agent sessions

Runs

Durable lineage records that outlive the sandbox: tenant, actor, policy, agent/provider/model, optional parent run, timestamps and terminal status.

Agent groups

Paths after the first two rows are under /v1/cohorts/{id}.

Schedules

A schedule body has exactly one of cron (5 fields, UTC) or every (a duration such as 15m or 1h30m, at least 1m), plus command and optional prompt, precheck, agent, model. See Workspaces.

Signed audit trail

Approvals

Experimental surfaces

Warning: Both are off by default. Enable the browser only in a trusted deployment after reading Security.

Browser

Needs RUNEWARD_ENABLE_EXPERIMENTAL_BROWSER=1 and a browser-capable policy.

Browser IDE

code-server against /workspace. Needs RUNEWARD_ENABLE_EXPERIMENTAL_IDE=1, policy [ide] enabled = true, and an ide or ide-agents image from deploy/Dockerfile.ide.

The ticket is single-use; a session cookie covers later asset loads. Sandbox list/get may include ide / ide_agents. Limits: no per-keystroke policy, no Cursor, Claude Desktop or Codex GUIs inside the sandbox, and no first-class GitHub Copilot (Open VSX). Details: Browser IDE.

Example

AUTH=(-H "Authorization: Bearer $RUNEWARD_API_TOKEN")   # omit when serving without a token: AUTH=()
SB=$(curl -s "${AUTH[@]}" -X POST localhost:8080/v1/citadels -d '{"profile":"ns-auto"}' | jq -r .id)
curl -s "${AUTH[@]}" -X POST "localhost:8080/v1/citadels/$SB/shell/exec" -d '{"command":["echo","hi"]}'
curl -s "${AUTH[@]}" "localhost:8080/v1/chronicle/verify"
curl -s "${AUTH[@]}" -X DELETE "localhost:8080/v1/citadels/$SB"