runeward

Rune Box：让 Agent 自由探索，同时留下记录的环境。
Runeward 推出的 AI Agent 开源治理框架。

为任意 AI Agent 配备可强制执行的策略、人工审批、隔离执行、预算和签名证据。Rune Box 可与现有 Agent 或多 Agent 框架配合使用，无需更换模型或编排技术栈。

一条命令验证

前提条件：已运行 Docker、OrbStack 或 Podman 引擎，并安装 runeward 二进制文件。

runeward quickstart

该命令会创建 .runeward/quickstart.toml，检查策略、运行时、镜像和状态路径，运行一条允许执行的命令，证明破坏性命令会在执行前被拒绝，并验证签名审计记录。除非传入 --force，否则不会覆盖已有策略。

doctor 和仪表板就绪状态检查也会解析必需的密钥来源。引用了未设置的 env:// 值的 Charter 不会被标记为可启动。

runeward doctor quickstart                     # explain setup problems safely
runeward --config-dir .runeward serve          # dashboard + governed REST API
runeward evidence export quickstart -o run.json
runeward evidence verify run.json              # independent policy/audit verification

Rune Box 的新增能力

关注点	仅使用容器	Rune Box
工具调用	执行进程请求的操作	先检查每一项 Shell、代码、文件、网络和浏览器操作
高风险操作	因应用而异	使用 allow、deny 或 require-approval，并记录决策归属
网络	通常默认开放，除非另行配置	主机名策略默认拒绝；在 Kubernetes 上严格执行 L3 规则
限制	CPU／内存	墙钟时间、执行次数、出口流量、Token、成本和重试循环预算
审计	运行时日志	仅追加、哈希链式、由 Ed25519 签名的事件
交接	临时日志和文件夹	工作区 tar、恢复快照和可移植的签名证据 JSON
Agent 身份	单个不透明进程	租户、操作者、父级运行、提供方、模型和持久运行沿袭记录
接口	因运行时而异	CLI、REST、MCP、Web 仪表板、Kubernetes CRD 和本地 SDK 适配器

每项受治理的操作都遵循同一条路径：

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

命名

文档和 UI 优先使用通俗易懂的术语。为保持兼容性，现有 API 路径和文件字段仍保留原有主题名称。

通俗术语	Rune Box 名称	现有接口
沙箱	Citadel	/v1/citadels、Kubernetes Citadel
策略文件／配置档案	Charter	/v1/charters、*.toml 配置档案
审批	Conclave	/v1/conclave
签名审计记录	Chronicle	/v1/chronicle、[chronicle]
网络控制	Perimeter	/perimeter、[network]
预算和限制	Rationing	[rationing]
Agent 组／集群	Cohort	/v1/cohorts、[cohort]
签名策略包	Archive	runeward archive、[policy_bundle]

请参阅完整的命名和写作规范。

安装

根据 Rune Box 的使用方式选择合适的安装包：

安装方式	安装内容	命令
Homebrew	适用于 macOS 或 Linux 的 Rune Box CLI	brew install Runeeward/tap/runeward
PyPI	Python 客户端和 Agent 框架适配器	python -m pip install runeward
npm	TypeScript 客户端和 Agent 框架工具	npm install @runeward/sdk

对于常规本地使用，请通过 Homebrew 安装 CLI。对于 Agent 集成，还要安装对应语言的 SDK。pip 和 npm 包连接到正在运行的 Rune Box API；它们不能替代 CLI/运行时。

Homebrew — CLI

本地沙箱需要正在运行的 Docker、OrbStack 或 Podman 引擎。

brew install Runeeward/tap/runeward
runeward version
runeward quickstart

pip — Python SDK

需要 Python 3.9 或更高版本。基础客户端没有第三方运行时依赖。

python -m pip install runeward
python -c "import runeward; print(runeward.__version__)"

npm — TypeScript SDK

需要 Node.js 18 或更高版本。

npm install @runeward/sdk
npm ls @runeward/sdk

请参阅适配器，了解 LangChain、CrewAI、LlamaIndex、OpenAI Agents、Strands、Vercel AI SDK 和 LangChain.js 的安装选项。

其他 CLI 安装选项

签名的 macOS/Linux 安装程序需要 cosign，这样才能在校验和清单验证失败时安全终止。 Windows 二进制文件可从发布页面获取。

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

要构建当前的 main 分支，请使用 Rust 1.95 或更高版本（工作区 MSRV）：

git clone https://github.com/Runeeward/runeward
cd runeward
cargo build --release --locked -p runeward-cli --bin runeward
./target/release/runeward version

cargo install --locked --path crates/runeward-cli 会将其安装到 ~/.cargo/bin。

与 Agent 搭配使用

向支持 MCP 的 IDE 或 Agent 暴露受治理的工具：

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

或者，将 Agent CLI 放入沙箱，并运行一个或多个受治理的工作进程：

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

已包含适用于 LangChain、CrewAI、LlamaIndex、OpenAI Agents、Strands、Vercel AI SDK 和 LangChain.js 的适配器。请参阅适配器和Agent 组。

仪表板还为每个 Citadel 提供只读的 Live chat TTY。Agent 框架通过 runeward_publish_conversation（或相应的 REST、Python 和 TypeScript 接口）发布 user、assistant、tool 和 system 对话轮次；获授权的团队成员可以查看脱敏后的对话，而无需终端输入权限。Rune Box 无法推断 Agent 客户端未发布的私有 UI 聊天文本；请将发布调用接入框架的轮次回调。发布器必须连接到与仪表板相同的 runeward serve 控制平面（通过 /mcp、REST 或 SDK）。

框架 Agent 和子 Agent

Rune Box 是 Agent 周围的执行边界，而不是决定 Agent 如何推理的组件。将父 Agent 及其每个委派子 Agent 的工具调用路由到 Rune Box，为它们设定明确的策略、审批、隔离、预算和证据边界。

现有概念保持原意：Cohort 是共享任务看板的一组同级工作进程；它不会被重命名为“子 Agent”。编排器仍决定何时委派，而 Rune Box 会记录父级/运行/提供方的沿袭关系，并阻止子级 Citadel 扩大其父级的租户或 Charter 范围。每个参与的 Agent 都可以拥有自己的 Citadel 和 Chronicle。请参阅 Agent 框架集成。

策略工作流

策略支持内置 glob 规则、CEL、OPA/Rego 和签名 OCI 捆绑包。可在 CI 中测试策略、从经审核的模板开始，或根据已验证的生产证据生成精确提案：

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

policy learn 不会自动编辑策略。它会先验证证据，跳过已脱敏的操作，生成精确匹配项，并要求人工审核和扩展这些匹配项。

安全态势

• 服务默认绑定到回环地址；若要绑定到非回环地址，则必须先进行身份验证。
• 非回环 HTTP 还必须使用 TLS，除非通过 --allow-insecure-http 明确确认由可信反向代理终止 TLS。
• 多主体 RBAC 会将沙箱、Agent 组、恢复快照和仪表板视图限定在各自租户范围内，并将每项操作归因于其执行者。静态令牌和 OIDC JWT 使用相同的授权模型，嵌入式 HTTP MCP 也遵循相同的 REST 所有权检查。
• 浏览器自动化尚处于实验阶段，默认禁用。仅在可信部署中启用，并在审阅安全模型后设置 RUNEWARD_ENABLE_EXPERIMENTAL_BROWSER=1。支持浏览器功能的 Charter 会声明 capabilities = ["browser"]；随后，仪表板将显示受管控的渲染文本和屏幕截图操作，以及相应的策略／出口结果。
• 可选的浏览器 IDE（环境内的 code-server + 带票据的反向代理）同样处于实验阶段：RUNEWARD_ENABLE_EXPERIMENTAL_IDE=1、Charter [ide]、Dockerfile.ide 的 ide / ide-agents 目标，以及 ide-demo / ide-claude / ide-codex / ide-cursor 示例。限制：不提供逐击键策略；环境内没有 Cursor/Claude Desktop/Codex 图形界面；code-server 不原生支持 GitHub Copilot。请参阅浏览器 IDE和安全模型。
• 逐操作策略适用于通过控制平面（REST、MCP、仪表板文件／Shell／代码操作及 SDK）路由的工具调用。交互式终端或已在沙箱内运行的进程属于直接沙箱会话：它们会受到隔离／网络／资源控制，并记录终端活动，但不会拦截其中的单条命令以供审批。需要命令级策略和签名判定时，请使用受管控的工具调用。
• 请通过 SECURITY.md 私下报告漏洞。Rune Box 仍处于 1.0 之前；剩余限制记录在 ROADMAP.md 中。

环境内包含的内容

除逐操作策略外，Charter 还可以限制 Agent 进程本身，并保留其工作成果：

• 沙箱内限制。 runeward-supervisor 在沙箱映像中以 PID 1 运行，并根据 Charter 的 [filesystem] 和 [process] 部分，使用 Landlock 文件系统规则、seccomp 过滤器和已降权的身份启动 Agent。请参阅隔离和安全模型。
• 凭据代理。 [[endpoint]] 和 [[credential]] 条目允许出口代理向经批准的请求注入真实密钥，而 Agent 只能看到占位符；端点的 binaries 则将其限制为列出的可执行文件（仅限严格出口，由沙箱内的监督程序按连接归因）。请参阅安全模型。
• 持久化工作区和分叉。 [workspace] persist = true 可在休眠、唤醒和控制平面重启期间保留工作区；分叉从副本开始。Agent 轮次、Cohort 记忆、交接和 [schedule] 运行都基于该工作区。请参阅工作区与上下文。
• 强化模式。 --hardened（或 RUNEWARD_HARDENED=1）要求所有强化检查均通过，否则拒绝启动；从未运行的调用会返回标准拒绝对象。请参阅 CLI 参考。

架构

Rune Box 是一个 Rust Cargo 工作区（crates/），可构建四个二进制文件：

二进制文件	运行内容	Crate
runeward	CLI、控制平面（serve）、MCP 服务、Kubernetes 控制器和 Webhook	runeward-cli
runeward-egress	策略执行型出口代理和凭据代理（Linux sidecar）	runeward-egress
runeward-supervisor	沙箱内的 PID 1：Landlock、seccomp、已降权的身份（Linux）	runeward-supervisor
runeward-browser	沙箱内的无头浏览器驱动（Linux）	runeward-browser

各库 Crate 按控制循环拆分：

• runeward-charter：Charter 架构、加载器、检查器和签名。
• runeward-policy：glob/argv、CEL 和 Rego 引擎、护栏和用量核算； runeward-policybundle 用于分发已签名的 OCI 策略包。
• runeward-controlplane：受治理的执行（策略、审批、限制、后端执行、账本）、 工作区、分叉、Agent 回合、Cohort 记忆和计划任务。
• runeward-backend：Docker、Podman 和 Kubernetes 沙箱后端。
• runeward-server（REST、WebSockets、仪表板）和 runeward-mcp（stdio 和可流式传输的 HTTP）。
• runeward-k8s：runeward.dev CRD、Citadel/Cohort 控制器和准入 Webhook。
• runeward-ledger、runeward-keys、runeward-auditsink、runeward-termrec：已签名的、 哈希链式审计轨迹及其密钥、接收器和终端录制。
• runeward-authz、runeward-secrets、runeward-credentials、runeward-fleet、runeward-obs： RBAC/OIDC、密钥来源、CLI 登录、Cohort 任务板以及日志/指标。

发布二进制文件支持 Linux（静态 musl、amd64/arm64）、macOS（amd64/arm64）和 Windows （amd64，仅 CLI）；容器镜像支持多种架构，并由 cosign 签名。

文档

• 快速入门
• 安装
• 隔离
• 工作区和上下文
• 策略 / Charters
• REST API
• 浏览器 IDE（实验性的 code-server 代理）
• 安全模型
• 端到端测试
• 已发布的网站：runeeward.github.io/runeward

欢迎贡献；请参阅 CONTRIBUTING.md。基于 Apache 2.0 许可。