CLI reference · Rune Box docs

Run runeward <command> --help for full flags. A bare policy name is shorthand for enter <charter>. A policy is a Charter and a sandbox is a Citadel; commands and flags use those names.

Global flags

Flag	Description
`-c`, `--config-dir`	Directory to resolve Charters from (or `$RUNEWARD_CONFIG_DIR`).
`--help`	Help for any command.
`--version`	Print the version.

Commands

Setup and checks

Command	Description
`runeward auth login\|status\|logout`	Save or remove a client credential (OIDC device flow or `--token-stdin`).
`runeward init [project-dir]`	Create `.runeward/quickstart.toml`; never overwrites an existing policy.
`runeward quickstart [project-dir]`	Prove an allow, a pre-execution denial and a signed audit.
`runeward doctor [charter] [--json]`	Check policy, runtime, required secret sources, image and state readiness.
`runeward runtime check\|guide\|install <gvisor\|kata>`	Inspect, explain or install a hardened runtime. `install` is a dry run unless you add `--apply`.
`runeward version`	Print version information.

Sandboxes and the control plane

Command	Description
`runeward enter <charter> [-- cmd...]`	Create a sandbox and open a shell, or run one command.
`runeward serve [--bind ADDR] [--port N] [--token ... --tls-cert ... --tls-key ...] [--allow-insecure-http] [--no-ui] [--hardened]`	Start the REST API and web dashboard (default `--bind 127.0.0.1 --port 8080`). A non-loopback `--bind` needs auth (a token of at least 32 characters, or `RUNEWARD_AUTHZ_FILE`) and TLS, unless `--allow-insecure-http` is passed behind a trusted TLS proxy. `--no-ui` serves only the REST API. `--hardened` (or `RUNEWARD_HARDENED=1`) refuses to start unless every hardened-mode check passes.
`runeward mcp [--http --tls-cert ... --tls-key ...]`	Serve governed tools over stdio or streamable-HTTP MCP.
`runeward export <citadel-id> <dest-dir>`	Copy a sandbox workspace back to the host (Docker and k8s).
`runeward replay <cast>`	Replay a recorded terminal session (asciinema v2 cast).

Policy

Command	Description
`runeward list`	List reachable Charters.
`runeward print <charter>`	Print the resolved policy with secrets redacted.
`runeward validate [charter...] [--strict]`	Lint Charters (every resolvable one if none named): missing images, unresolved secrets, unreachable rules, duplicate env. `--strict` also fails on warnings.
`runeward policy test <charter> [--cases <file>] [--case <spec>]...`	Simulate the policy against actions from a TOML file and/or inline `--case tool=...,action=...,expect=...`; exits non-zero on mismatch.
`runeward policy scaffold [template] [--list]`	Print a ready-made policy template.
`runeward policy learn <evidence-or-chronicle.json>`	Print reviewable policy proposals from a verified audit trail.
`runeward charter sign\|verify <file>`	Create or check a detached ed25519 signature over a Charter.
`runeward archive keygen\|push\|pull`	Manage signed OCI policy Archives.

Audit and evidence

Command	Description
`runeward evidence export <charter> [-o file]`	Package the resolved policy and signed audit events.
`runeward evidence verify <file>`	Verify the policy digest, event chain and every signature.
`runeward chronicle verify <bundle.json>`	Verify an exported signed audit transcript offline.

Kubernetes

Command	Description
`runeward controller`	Run the controller (watches CRDs).
`runeward webhook`	Run the admission webhook.
`runeward up`	Install the in-cluster control plane in one command.

Sandboxes, sessions and schedules

These are REST clients of a running runeward serve. They take --base (or $RUNEWARD_BASE, default http://127.0.0.1:8080), --token (or $RUNEWARD_API_TOKEN, else the auth login credential) and --json. See Workspaces.

Command	Description
`citadel fork <id> [--charter X]`	Copy the workspace into a new, independent sandbox. A policy not provably within the source's (Charter subsumption) needs an administrator.
`citadel sleep <id>`	Sleep a persistent sandbox (`[workspace] persist = true`); the disk is kept.
`citadel wake <id>`	Wake it under the same id.
`citadel status <id>`	Delivered isolation tier, usage, capabilities and workspace state.
`citadel perimeter <id>`	Network-control decisions: time, verdict, target, tool, reason.
`session turn <session-id> <prompt> [--agent A] [--model M]`	Start the next agent turn and stream its output.
`session attach <session-id> [--after N]`	Replay after sequence `N`, then follow live. Safe to re-run after a dropped connection.
`session cancel <session-id>`	Cancel the active turn. It does not rewind changes already made.
`schedule create (--citadel ID \| --cohort ID) (--cron "0 6 * * *" \| --every 30m) [--agent A] [--model M] [--prompt P] [--precheck "cmd args"] [-- cmd...]`	Schedule recurring runs. Without `-- cmd`, the agent CLI runs with the prompt as its last argument.
`schedule list [--citadel ID \| --cohort ID]`	List visible schedules.
`schedule get\|delete\|run <id>`	Show, delete or fire now. Policy, precheck and budgets still apply.

With --json, session turn and session attach print one JSON event per line (seq, stream, data). Otherwise status events go to stderr as runeward: [status #N] ....

Agent groups

runeward cohort ... drives agent groups (Cohorts); see Agent groups. The memory and task-context subcommands below use the active group (cohort up) or --cohort <id>, and accept --json.

Command	Description
`cohort memory put <key> <text> [--tag T]... [--expected-version N]`	Write shared memory. `--expected-version 0` requires a new key.
`cohort memory get <key>`	Read one entry.
`cohort memory search [query] [--tag T]... [--limit N] [--max-bytes N]`	Ranked, byte-capped search.
`cohort memory list`	List every entry.
`cohort memory delete <key> [--version N]`	Delete, conditionally with `--version`.
`cohort note <task> <text>`	Leave a handoff note.
`cohort brief <task> <brief> [--for AGENT]`	Set the brief an agent gets on claim (`*`, the default, means every agent; empty clears).
`cohort handoff <task> --lease-token T --note N [--result R] [--requeue] [--owner W]`	Complete a claimed task, or give it back with `--requeue`, with a note.
`cohort task context <task> [--for AGENT] [--memory-bytes N]`	Show what an agent gets on claim.
`cohort task child <task> <payload>`	Add a linked child task.

cohort run and cohort build claim tasks with their context; when a task has a brief, notes, a parent or matching memory, it is wrapped in the prompt between --- Rune Box task context (...) --- and --- end of Rune Box task context ---. On finish, the task completes with a handoff note holding the last 2 KiB of output. A failed attempt also leaves a note; non-retryable refusals are not requeued. cohort exec does the same when no older tasks are pending, otherwise it runs the prompt without a task.

Exit codes

Code	Meaning
`0`	Success.
`1`	Any other error, including bad requests and usage errors.
`3`	Refused by policy, an approval gate, missing permission or an unmet isolation floor. Nothing ran.
`4`	Refused for a spent budget, rate limit or load shedding. Nothing ran; retrying later may succeed.

A refusal prints one line to stderr. Quote its request_id; it matches the server's X-Request-Id and logs.

refused (policy, retryable=false, request_id=5f0c9a7e21b4d3c8): denied by policy: no deletes

Environment

Variable	Purpose
`RUNEWARD_CONFIG_DIR`	Default Charter directory.
`RUNEWARD_STATE_DIR`	Ledger, keys, recordings and agent-group state. Use a distinct value per running instance.
`RUNEWARD_API_TOKEN`	Bearer token required on every control-plane request.
`RUNEWARD_BASE`	Control-plane URL for the REST-client commands (`cohort`, `citadel`, `session`, `schedule`); same as `--base`, default `http://127.0.0.1:8080`.
`RUNEWARD_AUTHZ_FILE`	JSON file of named RBAC principals; enables multi-principal auth.
`RUNEWARD_OIDC_ISSUER` / `RUNEWARD_OIDC_AUDIENCE`	Verify OIDC bearer JWTs and map signed tenant/role claims.
`RUNEWARD_OIDC_JWKS_URL`	Explicit JWKS endpoint; normally discovered. HTTPS required except on loopback.
`RUNEWARD_CREDENTIALS_FILE`	Path for the credential written by `auth login`.
`RUNEWARD_RATE_LIMIT`	Requests/sec per client IP; default `50`. `0`/`off` only for trusted benchmarks.
`RUNEWARD_RECORD_TERMINALS`	`1` records terminal sessions as asciinema casts.
`RUNEWARD_AUDIT_WEBHOOK_URL` / `RUNEWARD_AUDIT_FILE`	Stream audit events to a webhook and/or file.
`RUNEWARD_COPY_FROM_ROOTS`	Colon-separated allowlist for `copy_from`/seed sources.
`RUNEWARD_MCP_DEFAULT_TOKEN`	Principal for a stdio MCP process; falls back to `auth login`.
`RUNEWARD_K8S_NAMESPACE`	Namespace for k8s sandbox pods (default `runeward`).
`RUNEWARD_K8S_PSA_ENFORCE`	Pod Security Admission level: `privileged`\|`baseline`\|`restricted` (default `privileged`).
`RUNEWARD_K8S_DIRECT_VOLUME_CLASS`	StorageClass for direct-assigned block volumes, so `kata-fc` workspaces are a real disk and can persist. See Isolation.
`RUNEWARD_K8S_NETWORK_POLICY`	Truthy creates a default-deny (DNS-only egress) NetworkPolicy.
`RUNEWARD_MICROVM_DIR`	State and image-disk cache of the native microVM backend (default `~/.runeward/microvm`). Keep it short: socket paths must fit about 100 bytes. See Isolation.
`RUNEWARD_MICROVM_VMM`	Monitor for a `microvm` Charter without `host.runtime`: `firecracker` or `libkrun` (default: Firecracker when configured).
`RUNEWARD_MICROVM_AGENT`	The static `runeward-vmagent` guest PID 1 (default: next to `runeward`, then `PATH`).
`RUNEWARD_MICROVM_KERNEL`	The uncompressed guest kernel Firecracker boots.
`RUNEWARD_FIRECRACKER_BIN`	The `firecracker` binary (default: `PATH`).
`RUNEWARD_KRUN_HELPER` / `RUNEWARD_LIBKRUN`	The `runeward-krun` helper (default: `PATH`) and the libkrun library (default `libkrun.so.1`, `libkrun.1.dylib` on macOS), built with block-device support.
`RUNEWARD_MICROVM_DISK_SIZE`	Size of a new persistent workspace disk (sparse; default `8g`).
`RUNEWARD_MICROVM_MKFS`	`mkfs.ext4` for image and workspace disks (`debugfs` from the same directory).
`RUNEWARD_DNS_RESOLVERS`	Comma-separated resolver IPs for DNS under strict egress.
`RUNEWARD_ENABLE_EXPERIMENTAL_BROWSER`	`1` enables the experimental browser surface. Off by default; trusted deployments only.
`RUNEWARD_ENABLE_EXPERIMENTAL_IDE`	`1` enables the experimental in-sandbox browser IDE. Off by default. See Browser IDE.
`RUNEWARD_OP_BIN` / `OP_SERVICE_ACCOUNT_TOKEN`	Locate and authenticate the 1Password `op` CLI for `op://` references; the desktop app integration needs no token. See Policies.
`GITHUB_TOKEN`	Injected only when a Charter references `op = "env://GITHUB_TOKEN"`. Use a least-privilege token; never put it in an MCP config or committed file. Host `gh` auth is not passed in.
`OPENAI_BASE_URL`	OpenAI-compatible endpoint, used only when a Charter injects it. From Docker use e.g. `http://host.docker.internal:11434/v1` and allow the host in network policy.

Note: Provider and source-control variables stay on the host. They reach a sandbox only through an explicit env:// secret source, which applies readiness checks, redaction and the policy's egress rules.

Examples

runeward quickstart
runeward --config-dir examples enter ns-auto -- python --version

# Authenticated control plane on a non-loopback bind
RUNEWARD_API_TOKEN=$(openssl rand -hex 32) \
  runeward --config-dir examples serve --bind 0.0.0.0 --port 8443 \
  --tls-cert ./tls/server.crt --tls-key ./tls/server.key

Written from docs/cli.md at commit 1ee29ff4ab36. Rune Box is open source under Apache-2.0.