# IronCurtain
[](https://github.com/provos/ironcurtain/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@provos/ironcurtain)
[](LICENSE)
[](https://ironcurtain.dev)
**一个面向自主 AI 代理的安全\*运行时,其安全策略源自一份人类可读的宪法。**
_\*当有人写下“安全”二字时,你应当立刻保持怀疑。[我们所说的安全究竟指什么?](https://ironcurtain.dev)_
> [!WARNING]
> **研究原型。** IronCurtain 是一个早期研究项目,探索如何让 AI 代理足够安全,从而真正有用。API、配置格式和架构都可能发生变化。欢迎贡献和反馈。
## 演示
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/42102/cf5f5cc847e63acad65eccf1c7fb33bacd782a5d592249cfea60e5f32830ac07.gif" alt="IronCurtain mux 演示:来自命令模式的受信输入使 git clone 和 git push 获得自动批准" width="800">
</p>
代理被要求克隆一个仓库并推送更改。`git_clone` 和 `git_push` 都被策略引擎升级处理,但自动批准器会自动批准它们——用户在命令模式(Ctrl-A)下提供的受信输入表达了明确的意图,因此无需手动执行 `/approve`。
## 问题
自主 AI 代理可以代表你管理文件、运行 git 命令、发送消息并与 API 交互。但如今的代理框架赋予代理与用户相同的权限,例如对文件系统、凭据和网络的完全访问权。安全研究人员称之为**环境权限**,这意味着一次提示注入或多轮对话中的意图漂移,就可能导致代理删除文件、窃取数据或推送恶意代码。
常见的应对方式要么是将代理限制在狭窄的沙箱中(限制了其实用性),要么是要求用户批准每一个操作(限制了其自主性)。两者都不尽如人意。
## 方法
IronCurtain 走了一条不同的路:**用通俗英语表达你的安全意图,然后让系统自行确定如何执行。**
你编写一份**宪法**,这是一份简短文档,描述你的代理可以做什么、不可以做什么。IronCurtain 使用 LLM 流水线将其编译为确定性的安全策略,用生成的测试场景验证编译后的规则,然后在运行时对每一次工具调用执行该策略。最终得到的代理可以在你用自然语言定义的边界内自主工作。
核心思想:
- **代理是不可信的。** IronCurtain 假设 LLM 可能因提示注入或意图漂移而被攻破。安全性不依赖于模型“表现良好”。
- **输入英语,输出执行。** 你编写意图(“未经批准不得执行破坏性 git 操作”);系统将其编译为确定性规则,并在运行时无需 LLM 进一步参与即可执行。
- **语义中介。** 系统不赋予代理原始的系统访问权限,而是让所有交互都通过 [MCP](https://modelcontextprotocol.io/) 服务器(文件系统、git 等)进行。每一次工具调用都会经过策略引擎,该引擎可以**允许**、**拒绝**或**升级**给用户审批。
- **纵深防御。** 代理代码运行在 V8 隔离环境中,无法直接访问宿主机。唯一的出口是语义上有意义的 MCP 工具调用,而每一次调用都会对照策略进行检查。
## 架构
IronCurtain 支持两种具有不同信任模型的会话模式:
- **内置代理(代码模式)** — IronCurtain 自有的 LLM 代理编写在 V8 沙箱中执行的 TypeScript 代码片段。IronCurtain 控制代理、沙箱和策略引擎。每一次工具调用都以结构化 MCP 请求的形式离开沙箱,经过策略引擎(允许 / 拒绝 / 升级),然后才到达真正的 MCP 服务器。
- **Docker Agent 模式** — 外部代理(Claude Code、Goose、Codex)在容器内运行,无法直接访问公共网络。IronCurtain 负责中介外部效应:LLM API 调用经过一个终止 TLS 的 MITM 代理(主机允许列表、假密钥到真密钥的替换),MCP 工具调用经过同一策略引擎,受支持的软件包安装则经过验证型软件包代理。
可选的[嵌套 Docker](https://github.com/provos/ironcurtain/blob/master/CONFIG.md#nested-docker-workloads) 为开发者会话提供一个私有、临时的守护进程,而不会暴露宿主机的 Docker socket。已实现的配置文件涵盖 macOS 上的 Apple Container 和 Docker Desktop,以及 amd64 上的 WSL2 配合 Docker Desktop。其 `offline`、`images` 和 `packages` 模式分别对应本地镜像使用、经中介的公共镜像拉取,以及受支持的软件包构建。原生 Linux Engine 不允许用于嵌套;有关前提条件和限制,请参阅配置参考。
在两种模式下,代理都是**不受信任的**。安全性不依赖于模型遵循指令——它是在边界处强制执行的。
有关完整架构(含图表)、逐层信任分析以及 macOS 平台说明,请参阅 [SANDBOXING.md](https://github.com/provos/ironcurtain/blob/master/SANDBOXING.md)。
## 快速开始
### 前提条件
- Node.js 24 或 26 —— IronCurtain 测试的偶数主版本线。两者都会安装预构建的 `isolated-vm` 二进制文件。Node 25 不受支持且未经测试。
- Docker —— 并非必需,但**强烈推荐**用于 Docker Agent 模式,因为它提供最强的隔离。在 macOS 26+(Apple 芯片)上,[Apple `container`](https://github.com/apple/container) 可作为替代后端(每个容器一个 VM;当其服务运行时自动使用——参见 `ironcurtain config` 中的 `containerRuntime`)
- 至少一个 LLM 提供商的 API 密钥(Anthropic、Google 或 OpenAI)
### 安装
**作为全局 CLI 工具(最终用户):**
```bash
npm install -g @provos/ironcurtain
```
**来自源码(开发):**
```bash
git clone https://github.com/provos/ironcurtain.git
cd ironcurtain
npm install
```
### 一次性设置
**1. 设置你的 API 密钥:**
```bash
export ANTHROPIC_API_KEY=sk-ant-...
```
你也可以将密钥放在项目根目录的 `.env` 文件中(通过 `dotenv` 自动加载),或通过 `ironcurtain config` 将其添加到 `~/.ironcurtain/config.json`。环境变量优先于配置文件中的值。支持:`ANTHROPIC_API_KEY`、`GOOGLE_GENERATIVE_AI_API_KEY`、`OPENAI_API_KEY`。
**2. 运行首次启动向导**(在使用推荐的 mux 路径之前显式运行此命令;它也会在首次执行非 mux 的 `ironcurtain start` 时自动运行):
```bash
ironcurtain setup
```
引导你完成 GitHub token 设置、Web 搜索提供程序、模型选择及其他设置。根据你的选择创建 `~/.ironcurtain/config.json`。
## 运行 IronCurtain
IronCurtain 附带一套面向开发者体验的默认策略——允许只读操作,变更操作(写入、推送、创建 PR)会升级以请求人工批准。你可以在设置完成后立即开始使用它。
### 终端复用器(推荐)
使用 IronCurtain 的推荐方式。它让你能够充分利用智能体的交互式 TUI(Claude Code 或 Goose),同时 IronCurtain 通过其策略引擎对每一次工具调用进行中介——全部在一个终端中完成。
```bash
ironcurtain mux
```
**核心能力:**
- **完整的 agent TUI** — agent 在 Docker 容器内的 PTY 中运行,且无网络访问权限。你可以像它在本地运行一样与之交互。
- **内联升级处理** — 当工具调用需要审批时,升级选择器会以单键操作(a/d/w 分别对应批准/拒绝/加入白名单)覆盖视口。使用 `/approve+ N` 可在本次会话剩余时间内将某个域名或路径加入白名单。
- **可信用户输入** — 在命令模式(Ctrl-A)下输入的文本会在进入容器之前于宿主机侧被捕获。这会产生一个经过验证的意图信号,供自动批准器使用——例如,输入“push my changes to origin”将自动批准随后的 `git_push` 升级请求。
- **标签页管理** — 生成多个并发会话(`/new`),在它们之间切换(`/tab N`、Alt-1..9),关闭它们(`/close`)。多个 mux 实例可以并行运行。
完整演练请参见 [DEVELOPER_GUIDE.md](https://github.com/provos/ironcurtain/blob/master/DEVELOPER_GUIDE.md):输入模式、可信输入安全模型、升级工作流以及键盘参考。
### 非 mux 会话
对于快速的一次性任务、脚本,或当你明确想要使用本地内置 agent 时,请使用 `ironcurtain start`。对于常规的交互式 Docker-agent 工作,请使用 `ironcurtain mux`。
```bash
ironcurtain start "Summarize the files in ./src" # Single-shot mode
ironcurtain start -w ./my-project "Fix the tests" # Single-shot workspace mode
ironcurtain start --agent builtin # Local builtin REPL, no Docker
ironcurtain start --persona my-assistant "Check my email" # Use a persona
```
### 其他运行模式
IronCurtain 还支持会话恢复(`--resume <session-id>`)、传统的原始 PTY/调试模式、用于移动端审批的 Signal 消息传输,以及用于定时 cron 任务的守护进程模式。守护进程有一个可选的 [Web UI](https://github.com/provos/ironcurtain/blob/master/DAEMON.md#web-ui)(`--web-ui`),用于基于浏览器的监控和升级处理。详情请参阅 [RUNNING_MODES.md](https://github.com/provos/ironcurtain/blob/master/RUNNING_MODES.md)。
### 多智能体工作流
IronCurtain 通过结构化工作流编排多个 AI 智能体。内置的**漏洞发现**工作流通过分层测试框架流水线(第 1 层隔离函数 → 第 2 层多组件 → 第 3 层完整构建)在原生代码中搜寻内存安全和逻辑缺陷,并配有 libFuzzer/AFL++ 覆盖率门控、假设驱动的 `discover`/`triage` 状态,以及最终的人工报告审查门。**设计与编码**工作流运行计划 / 设计 / 实现 / 审查循环,同样设有人工门。每个智能体都在自己的 Docker 容器中运行,具有角色特定的策略边界;引擎自动管理状态转换、产物传递和崩溃恢复检查点。开源、完全在你的机器上运行、通过基于宪法的策略引擎强制执行每个智能体的安全策略,并可与任何 Docker 容器化的智能体配合使用——在编码任务的范围上与 Amazon Kiro 和 Google Jules 相当,但具备一流的安全性和可扩展的工作流定义格式。

**Web UI 是工作流运行的预期界面。** 启动守护进程,打开打印出的 URL,然后从 Workflows 页面驱动运行——上方的状态机图是实时的,智能体消息时间线以 markdown 渲染流式显示,门审查包含工作区 + 产物浏览器,过去的运行会保持列出。
```bash
ironcurtain daemon --web-ui
```
CLI 访问可用于脚本编写、自动化和调试:
```bash
ironcurtain workflow start vuln-discovery \
"Find memory-safety bugs in libical" --workspace ~/src/libical
ironcurtain workflow start design-and-code \
"Build a REST API with authentication"
```
完整文档请参阅 [WORKFLOWS.md](https://github.com/provos/ironcurtain/blob/master/WORKFLOWS.md)。
## 自定义你的策略
默认策略适用于一般开发场景,但你可以根据自身工作流进行调整:
**1. 自定义你的 constitution**(可选但推荐):
```bash
ironcurtain customize-policy
```
一个由 LLM 辅助的对话,用于生成针对你工作流定制的 constitution,并保存到 `~/.ironcurtain/constitution-user.md`。你也可以直接编辑此文件。
**2. 编译策略:**
```bash
ironcurtain compile-policy
```
将你的 constitution 转换为确定性规则,生成测试场景并对其进行验证。编译产物输出到 `~/.ironcurtain/generated/`。
### Personas
Personas 是具名的策略配置文件——每个都捆绑了 constitution、编译后的策略、持久化工作区和语义记忆。使用它们可以以不同的角色或访问级别运行 agent。
```bash
ironcurtain persona create my-assistant # Create a persona
ironcurtain persona compile my-assistant # Compile its policy
ironcurtain start --persona my-assistant "Check my calendar"
```
在 mux 模式下,`/new my-assistant` 会使用该 persona 启动一个标签页。Persona 也可以分配给 cron 任务。有关定时任务的配置,请参见 [DAEMON.md](https://github.com/provos/ironcurtain/blob/master/DAEMON.md)。
Persona 也可以通过 [Web UI](https://github.com/provos/ironcurtain/blob/master/DAEMON.md#persona-policy-management) 进行管理——浏览、创建、编辑 constitution,并实时查看策略编译进度。由于策略是安全边界,除非守护进程以 `--allow-policy-mutation` 启动(默认关闭),否则 Web UI 的变更控件为只读。
### Skills
将 SKILL.md 包放入 `~/.ironcurtain/skills/<name>/`,即可让每个 Docker agent 会话都能使用特定用途的指导(辅助脚本、确定性检查、领域知识)。合并后的集合会被暂存到每个 bundle 的主机目录中,并以**只读**方式绑定挂载到容器内当前活动 agent 的原生发现路径——Claude Code 通过 `--add-dir` 指向暂存目录,Goose 扫描 `~/.config/goose/skills/<name>/SKILL.md`。agent 会自动发现它们,并根据每个 skill 的 frontmatter 描述决定何时读取。SKILL.md 的_格式_是 Claude Code、Goose 和 Codex 采用的开放标准;只有_发现路径_因 agent 而异。工作流可以在工作流包内附带按状态划分的 skill——请参见 [WORKFLOWS.md](https://github.com/provos/ironcurtain/blob/master/WORKFLOWS.md#skills)。
## 策略:Constitution → 强制执行
你用通俗英语编写意图;IronCurtain 将其编译为确定性规则:
```
constitution.md → [Annotate] → [Compile] → [Resolve Lists] → [Generate Scenarios] → [Verify & Repair]
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
tool-annotations compiled-policy dynamic-lists test-scenarios verified policy
.json .json .json .json (or build failure)
```
1. **标注** — 按角色(读取路径、写入路径、删除路径、无)对每个 MCP 工具的实参进行分类。
2. **编译** — 将英文宪法翻译为确定性的 if/then 规则。类别性引用(“主要新闻网站”、“我的联系人”)以 `@list-name` 符号引用的形式输出。
3. **解析列表** — 通过 LLM 知识或 MCP 工具调用(例如查询联系人数据库)将符号列表解析为具体值。写入 `dynamic-lists.json`,用户可编辑。当不存在列表时跳过。
4. **生成场景** — 根据宪法以及强制的手写不变量测试创建测试场景。
5. **验证与修复** — 针对真实策略引擎运行场景。由 LLM 评判器分析失败并生成针对性修复(最多 2 轮)。如果策略无法通过验证,则构建失败。
所有产物均按内容哈希缓存——只有发生变化的输入才会触发重新编译。
### 编译后的规则示例
一条宪法条款如下:
```markdown
- The agent may perform read-only git operations (status, diff, log) within the sandbox without approval.
- The agent must receive human approval before git push, pull, fetch, or any remote-contacting operation.
```
编译为:
```json
[
{ "tool": "git_status", "decision": "allow", "condition": { "directory": { "within": "$SANDBOX" } } },
{ "tool": "git_diff", "decision": "allow", "condition": { "directory": { "within": "$SANDBOX" } } },
{ "tool": "git_push", "decision": "escalate", "reason": "Remote-contacting git operations require human approval" }
]
```
任何不匹配显式 `allow` 或 `escalate` 规则的调用都会**默认被拒绝**。
```bash
ironcurtain annotate-tools --server filesystem # Annotate one server (merge with existing)
ironcurtain annotate-tools --all # Re-annotate all servers
ironcurtain compile-policy # Compile constitution into rules and verify
ironcurtain refresh-lists # Re-resolve dynamic lists without full recompilation
ironcurtain refresh-lists --list major-news # Refresh a single list
```
查看生成的 `~/.ironcurtain/generated/compiled-policy.json` —— 这些是运行时强制执行的确切规则。
## 配置
IronCurtain 将配置和会话数据存储在 `~/.ironcurtain/` 中:
```
~/.ironcurtain/
├── config.json # User configuration
├── constitution.md # User-local base constitution (overrides package default)
├── constitution-user.md # Your policy customizations (generated by customize-policy)
├── generated/ # User-compiled policy artifacts (overrides package defaults)
├── personas/ # Persona directories (constitution, policy, workspace, memory)
├── skills/ # User-global SKILL.md packages, mounted into every Docker session
├── jobs/ # Cron job definitions, workspaces, and run records
├── statistics/ # Content-free local LLM usage database + pseudonymization key
├── sessions/
│ └── {sessionId}/
│ ├── sandbox/ # Per-session filesystem sandbox
│ ├── escalations/ # File-based IPC for human approval
│ ├── audit.jsonl # Per-session audit log
│ └── session.log # Diagnostics
└── workflow-runs/ # Shared-container workflow runs (see below)
```
单会话运行(`ironcurtain start`、mux 标签页、cron 作业)写入 `sessions/` 下。共享容器工作流运行则写入 `workflow-runs/` 下——参见下一节。
### 工作流运行布局
工作流定义可以通过在其 YAML 中设置 `settings.sharedContainer: true` 来选择启用共享 Docker 容器。在该模式下,每个 agent 状态都在同一个长期运行的容器内运行,并共享同一个策略引擎实例;在状态之间,编排器会热切换活动策略,使每个角色只能看到自己的规则。该运行的所有产物都落在同一个目录树中:
```
~/.ironcurtain/workflow-runs/<workflowId>/
├── audit.jsonl # Persona-tagged append-only audit
├── messages.jsonl # Orchestrator message log
├── workspace/ # Agent workspace (filesystem MCP root)
├── bundle/ # Shared container support (claude-state, orientation, sockets, escalations, system-prompt.txt)
├── states/
│ └── <stateId>.<visitCount>/ # session.log + session-metadata.json per invocation
└── proxy-control.sock # Coordinator UDS for policy hot-swap
```
在共享容器工作流运行中,不会在 `~/.ironcurtain/sessions/` 下创建按会话划分的条目。用户可见的命令(`ironcurtain workflow start|resume|inspect|list`)保持不变。有关编写工作流定义和完整生命周期的信息,请参阅 [WORKFLOWS.md](https://github.com/provos/ironcurtain/blob/master/WORKFLOWS.md)。
以交互方式编辑配置:
```bash
ironcurtain config
```
关键配置区域:模型与 API 密钥、资源预算(token/步骤/时间/成本限制)、自动批准升级、Web 搜索提供商、审计脱敏以及记忆服务器 LLM 设置。完整参考请见 [CONFIG.md](https://github.com/provos/ironcurtain/blob/master/CONFIG.md)。
### 本地 LLM 统计
无内容 LLM 使用情况收集默认启用。它记录 token 计数(输入、思考、输出及总计)、计时、协议/提供商/模型路由、结果、拒绝情况,以及提供商公开时的成本元数据。它不存储提示词、补全内容、思考文本、工具载荷、请求/响应正文、凭据或任意标头。用户/配置派生的标签和非公开路由会使用本地 HMAC 密钥进行假名化;有界的模型和提供商标识符保持可读以便分析。
数据位于 `~/.ironcurtain/statistics/llm-usage.sqlite3`;假名化密钥为 `~/.ironcurtain/statistics/identity.key`。默认保留期为 90 天。使用 `ironcurtain config` → **LLM Statistics**、Web UI 设置视图,或设置 `"statistics": { "enabled": false }` 以退出。将 `retentionDays` 设为 `null` 可禁用自动清理。更改这些设置后,请重启长时间运行的守护进程。
可使用 `ironcurtain statistics delete --before <ISO-date-or-epoch-ms>` 或 `--all` 进行手动删除。这是逻辑上的 SQLite 行删除,而非安全擦除:已删除的字节可能残留在空闲页、WAL 文件、文件系统快照或备份中。这些命令不会轮换或删除身份密钥。
要将 LLM 流量路由到 LiteLLM 或 OpenRouter 之类的网关(在 Code Mode 和 Docker Agent Mode 中均适用),请参见 [MODEL_ROUTING.md](https://github.com/provos/ironcurtain/blob/master/MODEL_ROUTING.md)。
通过模型提供商配置文件(例如通过 OpenRouter 使用 GLM-5.3 / GLM-5.3-Flash,无需 sidecar)路由 Docker 代理:使用 `ironcurtain config` → Model Providers,然后在 `/new` 处或使用 `--provider-profile` 选择配置文件——参见 [MODEL_ROUTING.md](https://github.com/provos/ironcurtain/blob/master/MODEL_ROUTING.md#first-class-openrouter)。
## 内置能力
IronCurtain 附带六个预配置的 MCP 服务器。所有工具调用(记忆除外)均受你编译的策略管控。
| 服务器 | 工具数 | 关键能力 |
| -------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Filesystem** | 14 | 读取、写入、编辑、搜索文件;目录树;移动;差异计算 |
| **Git** | 28 | 完整 git 工作流:status、diff、log、commit、branch、push/pull/fetch、clone、stash、blame |
| **Fetch** | 2 | 带 HTML 转 Markdown 转换的 HTTP GET;Web 搜索(Brave、Tavily、SerpAPI、Parallel Search) |
| **GitHub** | 41 | 通过 `ghcr.io/github/github-mcp-server` 处理 Issues、PR、代码搜索、审查;需要 GitHub 个人访问令牌 |
| **Google Workspace** | 128 | Gmail、Calendar、Drive、Docs、Sheets——需要通过 `ironcurtain auth` 进行 OAuth 设置 |
| **Memory** | 5 | 持久语义记忆,支持混合向量+关键词搜索、LLM 摘要和自动压缩。为 persona 和 cron 会话启用。 |
只读操作默认策略允许;变更操作(写入、推送、创建 PR)会升级以请求人工批准。工具使用 `server.tool` 命名(例如 `filesystem.read_file`、`memory.recall`)。要添加自己的服务器,请参见 [ADDING_MCP_SERVERS.md](https://github.com/provos/ironcurtain/blob/master/ADDING_MCP_SERVERS.md)。
### 网络直通(Docker Agent Mode)
在 Docker Agent 模式下,容器没有网络访问权限——所有流量都经过 IronCurtain 的 MITM 代理。默认情况下,只有 LLM 提供商的域名可以访问。代理可以在运行时通过 `proxy` 虚拟 MCP 服务器(`add_proxy_domain`)请求访问其他域名。每个请求都需要通过升级流程获得人工批准。
已批准的域名会获得**原始直通隧道**——HTTP、HTTPS 和 WebSocket 连接会被转发,而不进行内容检查或凭据注入。这为代理提供了更大的实用性(调用第三方 API、从外部服务流式传输数据),但也意味着发往这些域名的流量是**未经中介的**。威胁模型参见 [SECURITY_CONCERNS.md](https://github.com/provos/ironcurtain/blob/master/docs/SECURITY_CONCERNS.md) 第 2b-i 节,使用详情参见 [DEVELOPER_GUIDE.md](https://github.com/provos/ironcurtain/blob/master/DEVELOPER_GUIDE.md)。
## 安全模型
IronCurtain 围绕一个特定的威胁模型设计:**LLM 失控。** 这可能通过提示注入(恶意电子邮件或网页劫持代理)或多轮漂移(代理在长时间会话中逐渐偏离用户意图)发生。
### IronCurtain 强制执行的内容
- **文件系统隔离**——符号链接感知的路径解析可防止路径遍历和符号链接逃逸攻击。
- **按工具策略**——每次 MCP 工具调用都会根据编译后的规则进行评估。策略引擎按角色(读取路径、写入路径、删除路径)对工具参数进行分类,以做出细粒度决策。
- **结构不变量**——某些保护是硬编码的,无法被宪法覆盖:代理永远不能修改自己的策略文件、审计日志或配置。
- **人工升级**——当策略要求“升级”时,代理会暂停,用户必须明确批准或拒绝。可选地,基于 LLM 的自动批准器可处理明确无歧义的情况(参见 [CONFIG.md](https://github.com/provos/ironcurtain/blob/master/CONFIG.md))。
- **审计追踪**——每次工具调用和策略决策都会记录到仅追加的 JSONL 审计日志中。
- **资源限制**——Token、步骤、时间和成本预算可防止会话失控。
### 已知限制
这是一个研究原型。已知的不足包括:
- **策略编译保真度**——基于 LLM 的编译器可能会误解宪法意图。验证流水线能捕获许多错误,但并非详尽无遗。请始终审查编译后的 `compiled-policy.json`。
- **V8 隔离边界**——Code Mode 使用 V8 隔离,而非操作系统级虚拟化。V8 零日漏洞可能导致逃逸。
- **无出站内容检查**——被允许写入文件的代理可以编码敏感数据以绕过内容级控制。计划中:对出站内容进行基于 LLM 的可理解性检查。
- **升级疲劳**——过多的误报升级可能导致习惯性批准。调整你的宪法以尽量减少不必要的提示。
详细威胁分析参见 [docs/SECURITY_CONCERNS.md](https://github.com/provos/ironcurtain/blob/master/docs/SECURITY_CONCERNS.md)。
## 故障排除
| 问题 | 处理建议 |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **缺少 API 密钥** | 设置环境变量(`ANTHROPIC_API_KEY`、`GOOGLE_GENERATIVE_AI_API_KEY` 或 `OPENAI_API_KEY`),或将对应的密钥添加到 `~/.ironcurtain/config.json`。 |
| **沙箱不可用** | 操作系统级沙箱需要 `bubblewrap` 和 `socat`。请安装这两者,或在开发时于 MCP 服务器配置中设置 `"sandboxPolicy": "warn"`。 |
| **预算耗尽** | 在 `~/.ironcurtain/config.json` 的 `resourceBudget` 下调整限制。将任意单项限制设为 `null` 即可禁用它。 |
| **Node 版本错误** | 支持的 Node.js 版本线为 24 和 26。两者都会安装预构建的 `isolated-vm` 二进制文件。其他主版本会被 `ironcurtain doctor` 拒绝。 |
| **策略与意图不匹配** | 查看 `compiled-policy.json` 以了解生成的规则。运行 `ironcurtain customize-policy` 来完善你的 constitution,然后运行 `ironcurtain compile-policy` 重新编译。具体的措辞会产生更好的规则——含糊的表述会导致含糊的策略。 |
| **自动批准未触发** | 自动批准器仅在用户消息明确授权该操作时才会批准(例如,对 `git_push` 使用 "push to origin")。含糊的消息始终会升级为人工审核。请确认 `config.json` 中的 `autoApprove.enabled` 为 `true`。 |
| **PTY/mux 终端退出后乱码** | 在该终端中运行 `reset` 以恢复正常模式。当进程被非正常终止且原始模式未恢复时,需要执行此操作。 |
| **Mux/listener:"已在运行"** | 同一时间只能运行一个 mux 或 escalation-listener。如果前一个进程已终止,`~/.ironcurtain/escalation-listener.lock` 处的锁会自动清除。如果锁仍然存在,请检查锁文件中的 PID。 |
| **Signal 机器人无响应** | 确认 signal-cli 容器正在运行(`docker ps \| grep ironcurtain-signal`)。检查 Signal 是否已配置(`ironcurtain setup-signal`)。详细故障排除请参见 [TRANSPORT.md](https://github.com/provos/ironcurtain/blob/master/TRANSPORT.md)。 |
## 开发
```bash
npm test # Run all tests
npm test -- test/policy-engine.test.ts # Run a single test file
npm test -- -t "denies delete_file" # Run a single test by name
npm run lint # Lint
npm run build # TypeScript compilation + asset copy
```
完整的测试指南(包括集成测试标志和约定)请参见 [TESTING.md](https://github.com/provos/ironcurtain/blob/master/TESTING.md)。
### 项目结构
```
src/
├── index.ts # Entry point
├── cli.ts # CLI command dispatcher
├── config/ # Configuration loading, constitution, MCP server definitions
├── session/ # Multi-turn session management, budgets, loop detection
├── sandbox/ # V8 isolated execution environment
├── trusted-process/ # Policy engine, MCP proxy, audit log, escalation handler
├── pipeline/ # Constitution → policy compilation pipeline
├── escalation/ # Escalation listener: session registry, TUI dashboard, state
├── mux/ # Terminal multiplexer: PTY bridge, renderer, trusted input
├── persona/ # Persona management (create, compile, resolve)
├── memory/ # Memory server integration (config, annotations, path resolution)
├── signal/ # Signal messaging transport (bot daemon, setup, formatting)
├── daemon/ # Unified daemon (Signal + cron scheduler, control socket)
├── cron/ # Cron job management (scheduler, job store, git sync, policy)
├── docker/ # Docker agent mode, PTY session, MITM proxy, registry proxy
├── workflow/ # Multi-agent workflow engine (orchestrator, state machine, gates)
├── web-ui/ # Web UI backend (JSON-RPC dispatch, event bus, workflow manager)
├── servers/ # Built-in MCP servers (fetch, web search providers)
└── types/ # Shared type definitions
packages/
└── memory-mcp-server/ # Standalone memory MCP server (publishable npm package)
```
## 许可证
[Apache-2.0](https://github.com/provos/ironcurtain/blob/master/LICENSE)