ironcurtain MCP工具

Prerequisites

• Node.js 22+ (required by isolated-vm; maximum Node 25)
• Docker — not required but strongly recommended for Docker Agent Mode, which provides the strongest isolation
• An API key for at least one LLM provider (Anthropic, Google, or OpenAI)

Install

As a global CLI tool (end users):

npm install -g @provos/ironcurtain

From source (development):

git clone https://github.com/provos/ironcurtain.git
cd ironcurtain
npm install

One-time setup

1. Set your API key:

export ANTHROPIC_API_KEY=sk-ant-...

You can also place keys in a .env file in the project root (loaded automatically via dotenv), or add them to ~/.ironcurtain/config.json via ironcurtain config. Environment variables take precedence over config file values. Supported: ANTHROPIC_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY, OPENAI_API_KEY.

2. Run the first-start wizard (runs automatically on first ironcurtain start, or explicitly):

ironcurtain setup

Walks you through GitHub token setup, web search provider, model selection, and other settings. Creates ~/.ironcurtain/config.json with your choices.

Builtin agent (no Docker required)

For quick tasks or environments without Docker, IronCurtain's builtin agent runs entirely locally in a V8 sandbox:

ironcurtain start                                    # Interactive multi-turn session
ironcurtain start "Summarize the files in ./src"     # Single-shot mode
ironcurtain start -w ./my-project "Fix the tests"    # Workspace mode
ironcurtain start --persona my-assistant "Check my email"  # Use a persona

What compiled rules look like

A constitution clause like:

- 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.

compiles to:

[
  { "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" }
]

Any call that doesn't match an explicit allow or escalate rule is denied by default.

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

Review the generated ~/.ironcurtain/generated/compiled-policy.json — these are the exact rules enforced at runtime.

Network Passthrough (Docker Agent Mode)

In Docker Agent Mode, the container has no network access — all traffic goes through IronCurtain's MITM proxy. By default, only LLM provider domains are reachable. The agent can request access to additional domains at runtime via the proxy virtual MCP server (add_proxy_domain). Each request requires human approval via the escalation flow.

Approved domains get a raw passthrough tunnel — HTTP, HTTPS, and WebSocket connections are forwarded without content inspection or credential injection. This gives the agent greater utility (calling third-party APIs, streaming data from external services) but means traffic to those domains is unmediated. See SECURITY_CONCERNS.md Section 2b-i for the threat model and DEVELOPER_GUIDE.md for usage details.

Quick Start

Demo

<p align="center"> <img src="demo.gif" alt="IronCurtain mux demo: trusted input from command mode enables auto-approval of git clone and git push" width="800"> </p>

The agent is asked to clone a repository and push changes. Both git_clone and git_push are escalated by the policy engine, but the auto-approver approves them automatically — the user's trusted input from command mode (Ctrl-A) provided clear intent, so no manual /approve was needed.

Configuration

IronCurtain stores configuration and session data in ~/.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
├── 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)

Single-session runs (ironcurtain start, mux tabs, cron jobs) write under sessions/. Shared-container workflow runs write under workflow-runs/ instead — see the next section.

Multi-agent workflows

IronCurtain orchestrates multiple AI agents through structured workflows. The bundled vulnerability discovery workflow hunts memory-safety and logic bugs in native code through a tiered harness pipeline (Tier 1 isolated function → Tier 2 multi-component → Tier 3 full build) with libFuzzer/AFL++ coverage gating, hypothesis-driven discover/triage states, and a final human report-review gate. The design-and-code workflow runs plan / design / implement / review cycles, also with human gates. Each agent runs in its own Docker container with role-specific policy boundaries; the engine manages state transitions, artifact passing, and crash-resume checkpointing automatically. Open source, runs entirely on your machine, enforces per-agent security policies via the constitution-based policy engine, and works with any Docker-containerized agent — comparable in scope to Amazon Kiro and Google Jules for coding tasks, but with first-class security and an extensible workflow definition format.

The web UI is the intended interface for workflow runs. Start the daemon, open the printed URL, and drive runs from the Workflows page — the state-machine graph above is live, the agent-message timeline streams with markdown rendering, gate reviews include a workspace + artifact browser, and past runs stay listed.

ironcurtain daemon --web-ui

CLI access is available for scripting, automation, and debugging:

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"

See WORKFLOWS.md for the full documentation.

Workflow run layout

A workflow definition can opt in to a shared Docker container by setting settings.sharedContainer: true in its YAML. In that mode every agent state runs inside the same long-lived container and shares one policy engine instance; between states the orchestrator hot-swaps the active policy so each persona sees its own rules. All artifacts for the run land in a single tree:

~/.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

No per-session entries are created under ~/.ironcurtain/sessions/ for a shared-container workflow run. User-visible commands (ironcurtain workflow start|resume|inspect|list) are unchanged. See WORKFLOWS.md for authoring workflow definitions and the full lifecycle.

Edit configuration interactively:

ironcurtain config

Key configuration areas: models and API keys, resource budgets (token/step/time/cost limits), auto-approve escalations, web search provider, audit redaction, and memory server LLM settings. See CONFIG.md for the full reference.

To route LLM traffic through a gateway like LiteLLM or OpenRouter (in both Code Mode and Docker Agent Mode), see MODEL_ROUTING.md.

Troubleshooting