Runeward

Rune Box: an environment where your agent can roam freely but with receipts.

The open-source governance harness for AI agents, by Runeward.

Put enforceable policy, human approvals, isolated execution, budgets, and signed evidence around any AI agent. Rune Box works with an existing agent or multi-agent framework rather than requiring a new model or orchestration stack.

Prove it in one command

Prerequisites: a running Docker, OrbStack, or Podman engine and the runebox binary.

runebox quickstart

The command creates .runebox/quickstart.toml, checks the policy, runtime, image, and state path, runs an allowed command, proves a destructive command is denied before execution, and verifies the signed audit trail. It never overwrites an existing policy unless --force is passed.

doctor and dashboard readiness also resolve required secret sources. A Charter that references an unset env:// value is not presented as launch-ready.

runebox doctor quickstart                     # explain setup problems safely

runebox --config-dir .runebox serve # dashboard + governed REST API runebox evidence export quickstart -o run.json runebox evidence verify run.json # independent policy/audit verification

What Rune Box adds

Every governed action follows one path:

agent request → policy → human approval when required → limits → sandbox → signed audit event

Naming

Documentation and UI use familiar terms first. Existing API paths and file fields retain the original themed names for compatibility.

See the full naming and writing convention.

Install

Choose the package that matches how you use Rune Box:

For normal local use, install the CLI with Homebrew. For an agent integration, install the SDK for its language as well. The pip and npm packages connect to a running Rune Box API; they do not replace the CLI/runtime.

Homebrew — CLI

Local sandboxes require a running Docker, OrbStack, or Podman engine.

brew install Runeeward/tap/runebox

runebox version runebox quickstart

pip — Python SDK

Requires Python 3.9 or newer. The base client has no third-party runtime dependencies.

python -m pip install runee-box

python -c "import runebox; print(runebox.version)"

npm — TypeScript SDK

Requires Node.js 18 or newer.

npm install @runebox/sdk

npm ls @runebox/sdk

See Adapters for LangChain, CrewAI, LlamaIndex, OpenAI Agents, Strands, Vercel AI SDK, and LangChain.js installation options.

Other CLI installation options

The signed macOS/Linux installer requires cosign so it can fail closed while verifying the checksum manifest. Windows binaries are available from Releases.

curl -fsSL https://raw.githubusercontent.com/Runeeward/RuneBox/main/install.sh | sh

To build the current main branch, use Rust 1.95 or newer (the workspace MSRV):

git clone https://github.com/Runeeward/RuneBox

cd RuneBox cargo build --release --locked -p runebox-cli --bin runebox ./target/release/runebox version

cargo install --locked --path crates/runebox-cli installs it into ~/.cargo/bin instead.

Use it with an agent

Expose governed tools to an MCP-capable IDE or agent:

{

"mcpServers": { "runebox": { "command": "runebox", "args": ["mcp", "--config-dir", ".runebox"] } } }

Or place an agent CLI inside a sandbox and run one or many governed workers:

runebox cohort --agent claude --model sonnet build "Build a tested API"

Adapters are included for LangChain, CrewAI, LlamaIndex, OpenAI Agents, Strands, Vercel AI SDK, and LangChain.js. See Adapters and agent groups.

The dashboard also has a read-only Live chat TTY for each Citadel. Agent harnesses publish user, assistant, tool, and system turns with runebox_publish_conversation (or the REST, Python, and TypeScript equivalents), and authorized teammates can follow the redacted conversation without terminal input access. Rune Box cannot infer private UI chat text that the agent client does not publish; wire the publish call into the harness turn callback. The publisher must connect to the same runebox serve control plane as the dashboard (through /mcp, REST, or an SDK).

Harness agents and subagents

Rune Box is the enforcement boundary around an agent, not the component that decides how the agent reasons. Route the tool calls of a parent agent and each delegated subagent through Rune Box to give them explicit policy, approval, isolation, budget, and evidence boundaries.

Existing concepts keep their meaning: a Cohort is a group of peer workers sharing a task board; it is not being renamed to “subagents.” The orchestrator still decides when to delegate, while Rune Box records the parent/run/provider lineage and prevents a child Citadel from widening its parent's tenant or Charter. Every participating agent can receive its own Citadel and Chronicle. See Agent harnessing.

Policy workflow

Policies support built-in glob rules, CEL, OPA/Rego, and signed OCI bundles. Test them in CI, start from a reviewed scaffold, or derive exact proposals from verified production evidence:

runebox policy scaffold package-approval

runebox policy test quickstart --case 'tool=shell,action=rm -rf /,expect=deny' runebox policy learn run.json > proposed-policy.toml

policy learn never edits a policy automatically. It verifies the evidence first, skips redacted actions, produces exact matches, and requires a human to review and broaden them.

Security posture

• The server binds to loopback by default and requires authentication before a non-loopback bind.
• Non-loopback HTTP also requires TLS unless --allow-insecure-http explicitly acknowledges that a trusted reverse proxy terminates TLS.
• Multi-principal RBAC scopes sandboxes, agent groups, recovery snapshots, and dashboard views to their tenant while attributing every operation to its actor. Static tokens and OIDC JWTs use the same authorization model, and embedded HTTP MCP shares the REST ownership checks.
• Browser automation is experimental and disabled by default. Enable it only in a trusted deployment with RUNEBOX_ENABLE_EXPERIMENTAL_BROWSER=1 after reviewing the security model. Browser-capable Charters declare capabilities = ["browser"]; the dashboard then exposes governed rendered-text and screenshot actions and their policy/egress results.
• An optional browser IDE (code-server inside the environment + ticketed reverse proxy) is similarly experimental: RUNEBOX_ENABLE_EXPERIMENTAL_IDE=1, Charter [ide], Dockerfile.ide targets ide / ide-agents, examples ide-demo / ide-claude / ide-codex / ide-cursor. Limits: not per-keystroke policy; no Cursor/Claude Desktop/Codex GUIs inside the environment; no first-class GitHub Copilot on code-server. See Browser IDE and the security model.
• Per-action policy applies to tool calls routed through the control plane (REST, MCP, dashboard file/shell/code actions, and SDKs). An interactive terminal or a process already running inside a sandbox is a direct sandbox session: it receives isolation/network/resource controls and terminal recording, but its individual commands are not intercepted for approval. Use governed tool calls when command-level policy and signed verdicts are required.
• Report vulnerabilities privately using SECURITY.md. Rune Box remains pre-1.0; residual limitations are tracked in ROADMAP.md.

What's inside the environment

Beyond per-action policy, a Charter can confine the agent process itself and keep its work:

• In-sandbox confinement. runebox-supervisor runs as PID 1 in the sandbox image and launches the agent under Landlock filesystem rules, a seccomp filter and a dropped identity, from the Charter's [filesystem] and [process] sections. See Isolation and the security model.
• Credential brokering. [[endpoint]] and [[credential]] entries let the egress proxy inject real secrets into approved requests while the agent only ever sees a placeholder, and an endpoint's binaries restrict it to the listed executables (attributed per connection by the in-sandbox supervisor, strict egress only). See the security model.
• Persistent workspaces and forks. [workspace] persist = true keeps a workspace across sleep, wake and control-plane restarts; forks start from a copy. Agent turns, Cohort memory, handoffs and [schedule] runs build on it. See [Workspaces and context](docs/workspaces-and-context