Skip to content
Back to search

ironcurtain

A secure* runtime for autonomous AI agents. Policy from plain-English constitutions. (*https://ironcurtain.dev)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/provos/ironcurtain with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/provos/ironcurtain'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/provos--ironcurtain/badge.svg)](/listings/provos--ironcurtain)

HTML

<a href="/listings/provos--ironcurtain"><img src="/api/listings/provos--ironcurtain/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- Node.js 24 or 26 — the even-numbered major lines IronCurtain tests. Both install prebuilt `isolated-vm` binaries. Node 25 is unsupported and untested. - Docker — not required but **strongly recommended** for Docker Agent Mode, which provides the strongest isolation. On macOS 26+ (Apple silicon), [Apple `container`](https://github.com/apple/container) works as an alternative backend (VM per container; used automatically when its services are running — see `containerRuntime` in `ironcurtain config`) - 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** (run this explicitly before using the recommended mux path; it also runs automatically on first non-mux `ironcurtain start`):

ironcurtain setup

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 421 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # IronCurtain
  2. [![CI](https://github.com/provos/ironcurtain/actions/workflows/ci.yml/badge.svg)](https://github.com/provos/ironcurtain/actions/workflows/ci.yml)
  3. [![npm](https://img.shields.io/npm/v/@provos/ironcurtain)](https://www.npmjs.com/package/@provos/ironcurtain)
  4. [![License](https://img.shields.io/github/license/provos/ironcurtain)](LICENSE)
  5. [![Website](https://img.shields.io/badge/web-ironcurtain.dev-blue)](https://ironcurtain.dev)
  6. **A secure\* runtime for autonomous AI agents, where security policy is derived from a human-readable constitution.**
  7. _\*When someone writes "secure," you should immediately be skeptical. [What do we mean by secure?](https://ironcurtain.dev)_
  8. > [!WARNING]
  9. > **Research Prototype.** IronCurtain is an early-stage research project exploring how to make AI agents safe enough to be genuinely useful. APIs, configuration formats, and architecture may change. Contributions and feedback are welcome.
  10. ## Demo
  11. <p align="center">
  12. <img src="demo.gif" alt="IronCurtain mux demo: trusted input from command mode enables auto-approval of git clone and git push" width="800">
  13. </p>
  14. 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.
  15. ## The Problem
  16. Autonomous AI agents can manage files, run git commands, send messages, and interact with APIs on your behalf. But today's agent frameworks give the agent the same privileges as the user such as full access to the filesystem, credentials, and network. Security researchers call this **ambient authority**, and it means a single prompt injection or multi-turn drift can cause an agent to delete files, exfiltrate data, or push malicious code.
  17. The common response is to either restrict agents to a narrow sandbox (limiting their usefulness) or to ask the user to approve every action (limiting their autonomy). Neither is satisfactory.
  18. ## The Approach
  19. IronCurtain takes a different path: **express your security intent in plain English, then let the system figure out enforcement.**
  20. You write a **constitution** which is a short document describing what your agent is and isn't allowed to do. IronCurtain compiles this into a deterministic security policy using an LLM pipeline, validates the compiled rules against generated test scenarios, and then enforces the policy at runtime on every tool call. The result is an agent that can work autonomously within boundaries you define in natural language.
  21. The key ideas:
  22. - **The agent is untrusted.** IronCurtain assumes the LLM may be compromised by prompt injection or drift. Security does not depend on the model "being good."
  23. - **English in, enforcement out.** You write intent ("no destructive git operations without approval"); the system compiles it into deterministic rules that are enforced without further LLM involvement at runtime.
  24. - **Semantic interposition.** Instead of giving the agent raw system access, all interactions go through [MCP](https://modelcontextprotocol.io/) servers (filesystem, git, etc.). Every tool call passes through a policy engine that can **allow**, **deny**, or **escalate** to the user for approval.
  25. - **Defense in depth.** Agent code runs in a V8 isolate with no direct access to the host. The only way out is through semantically meaningful MCP tool calls and every one is checked against policy.
  26. ## Architecture
  27. IronCurtain supports two session modes with different trust models:
  28. - **Builtin Agent (Code Mode)** — IronCurtain's own LLM agent writes TypeScript snippets that execute in a V8 sandbox. IronCurtain controls the agent, the sandbox, and the policy engine. Every tool call exits the sandbox as a structured MCP request, passes through the policy engine (allow / deny / escalate), and only then reaches the real MCP server.
  29. - **Docker Agent Mode** — An external agent (Claude Code, Goose, Codex) runs inside a container without direct public-network access. IronCurtain mediates the external effects: LLM API calls pass through a TLS-terminating MITM proxy (host allowlist, fake-to-real key swap), MCP tool calls pass through the same policy engine, and supported package installations go through validating package proxies.
  30. Opt-in [nested Docker](CONFIG.md#nested-docker-workloads) gives developer sessions a private, ephemeral
  31. daemon without exposing the host Docker socket. Implemented profiles cover Apple Container and Docker
  32. Desktop on macOS, and WSL2 with Docker Desktop on amd64. Its `offline`, `images`, and `packages` modes
  33. separate local image use, mediated public image pulls, and supported package builds. Native Linux Engine
  34. is not admitted for nesting; see the configuration reference for prerequisites and limitations.
  35. In both modes, the agent is **untrusted**. Security does not depend on the model following instructions — it is enforced at the boundary.
  36. See [SANDBOXING.md](SANDBOXING.md) for the full architecture with diagrams, layer-by-layer trust analysis, and macOS platform notes.
  37. ## Quick Start
  38. ### Prerequisites
  39. - Node.js 24 or 26 — the even-numbered major lines IronCurtain tests. Both install prebuilt `isolated-vm` binaries. Node 25 is unsupported and untested.
  40. - Docker — not required but **strongly recommended** for Docker Agent Mode, which provides the strongest isolation. On macOS 26+ (Apple silicon), [Apple `container`](https://github.com/apple/container) works as an alternative backend (VM per container; used automatically when its services are running — see `containerRuntime` in `ironcurtain config`)
  41. - An API key for at least one LLM provider (Anthropic, Google, or OpenAI)
  42. ### Install
  43. **As a global CLI tool (end users):**
  44. ```bash
  45. npm install -g @provos/ironcurtain
  46. ```
  47. **From source (development):**
  48. ```bash
  49. git clone https://github.com/provos/ironcurtain.git
  50. cd ironcurtain
  51. npm install
  52. ```
  53. ### One-time setup
  54. **1. Set your API key:**
  55. ```bash
  56. export ANTHROPIC_API_KEY=sk-ant-...
  57. ```
  58. 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`.
  59. **2. Run the first-start wizard** (run this explicitly before using the recommended mux path; it also runs automatically on first non-mux `ironcurtain start`):
  60. ```bash
  61. ironcurtain setup
  62. ```
  63. Walks you through GitHub token setup, web search provider, model selection, and other settings. Creates `~/.ironcurtain/config.json` with your choices.
  64. ## Running IronCurtain
  65. IronCurtain ships with a default policy geared towards the developer experience — read-only operations are allowed, mutations (writes, pushes, PR creation) escalate for human approval. You can start using it immediately after setup.
  66. ### Terminal multiplexer (recommended)
  67. The recommended way to use IronCurtain. It gives you the full power of your agent's interactive TUI (Claude Code or Goose) while IronCurtain mediates every tool call through its policy engine — all in a single terminal.
  68. ```bash
  69. ironcurtain mux
  70. ```
  71. **Key capabilities:**
  72. - **Full agent TUI** — The agent runs in a PTY inside a Docker container with no network access. You interact with it exactly as if it were running locally.
  73. - **Inline escalation handling** — When a tool call needs approval, an escalation picker overlays the viewport with single-key actions (a/d/w for approve/deny/whitelist). Use `/approve+ N` to whitelist a domain or path for the rest of the session.
  74. - **Trusted user input** — Text typed in command mode (Ctrl-A) is captured on the host side before entering the container. This creates a verified intent signal that the auto-approver can use — e.g., typing "push my changes to origin" will auto-approve a subsequent `git_push` escalation.
  75. - **Tab management** — Spawn multiple concurrent sessions (`/new`), switch between them (`/tab N`, Alt-1..9), close them (`/close`). Multiple mux instances can run in parallel.
  76. See [DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md) for the full walkthrough: input modes, trusted input security model, escalation workflow, and keyboard reference.
  77. ### Non-mux sessions
  78. Use `ironcurtain start` for quick one-shot tasks, scripts, or when you explicitly want the local builtin agent. For normal interactive Docker-agent work, use `ironcurtain mux`.
  79. ```bash
  80. ironcurtain start "Summarize the files in ./src" # Single-shot mode
  81. ironcurtain start -w ./my-project "Fix the tests" # Single-shot workspace mode
  82. ironcurtain start --agent builtin # Local builtin REPL, no Docker
  83. ironcurtain start --persona my-assistant "Check my email" # Use a persona
  84. ```
  85. ### Other running modes
  86. IronCurtain also supports session resume (`--resume <session-id>`), a legacy raw PTY/debug mode, a Signal messaging transport for mobile approval, and a daemon mode for scheduled cron jobs. The daemon has an optional [web UI](DAEMON.md#web-ui) (`--web-ui`) for browser-based monitoring and escalation handling. See [RUNNING_MODES.md](RUNNING_MODES.md) for details.
  87. ### Multi-agent workflows
  88. 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.
  89. ![Vuln-discovery state machine in the IronCurtain web UI](packages/web-ui/docs/workflow-state-machine.png)
  90. **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.
  91. ```bash
  92. ironcurtain daemon --web-ui
  93. ```
  94. CLI access is available for scripting, automation, and debugging:
  95. ```bash
  96. ironcurtain workflow start vuln-discovery \
  97. "Find memory-safety bugs in libical" --workspace ~/src/libical
  98. ironcurtain workflow start design-and-code \
  99. "Build a REST API with authentication"
  100. ```
  101. See [WORKFLOWS.md](WORKFLOWS.md) for the full documentation.
  102. ## Customizing Your Policy
  103. The default policy works well for general development, but you can tailor it to your workflow:
  104. **1. Customize your constitution** (optional but recommended):
  105. ```bash
  106. ironcurtain customize-policy
  107. ```
  108. An LLM-assisted conversation that generates a constitution tailored to your workflow, saved to `~/.ironcurtain/constitution-user.md`. You can also edit this file directly.
  109. **2. Compile the policy:**
  110. ```bash
  111. ironcurtain compile-policy
  112. ```
  113. Translates your constitution into deterministic rules, generates test scenarios, and verifies them. Compiled artifacts go to `~/.ironcurtain/generated/`.
  114. ### Personas
  115. Personas are named policy profiles — each bundles a constitution, compiled policy, persistent workspace, and semantic memory. Use them to run agents with different roles or access levels.
  116. ```bash
  117. ironcurtain persona create my-assistant # Create a persona
  118. ironcurtain persona compile my-assistant # Compile its policy
  119. ironcurtain start --persona my-assistant "Check my calendar"
  120. ```
  121. In mux mode, `/new my-assistant` spawns a tab using that persona. Personas can also be assigned to cron jobs. See [DAEMON.md](DAEMON.md) for scheduled job configuration.
  122. Personas can also be managed from the [web UI](DAEMON.md#persona-policy-management) — browse, create, edit constitutions, and compile policies with live progress. Because a policy is a security boundary, the web UI's mutation controls are read-only unless the daemon is started with `--allow-policy-mutation` (off by default).
  123. ### Skills
  124. Drop SKILL.md packages under `~/.ironcurtain/skills/<name>/` to make purpose-specific guidance (helper scripts, deterministic checks, domain knowledge) available to every Docker agent session. The merged set is staged into a per-bundle host directory and bind-mounted **read-only** into the container at the path the active agent's native discovery walks — Claude Code is pointed at the staging dir via `--add-dir`, Goose scans `~/.config/goose/skills/<name>/SKILL.md`. The agent discovers them automatically and decides when to read them based on each skill's frontmatter description. The SKILL.md _format_ is the open standard adopted by Claude Code, Goose, and Codex; only the _discovery path_ differs per agent. Workflows can ship per-state skills inside the workflow package — see [WORKFLOWS.md](WORKFLOWS.md#skills).
  125. ## Policy: Constitution → Enforcement
  126. You write intent in plain English; IronCurtain compiles it into deterministic rules:
  127. ```
  128. constitution.md → [Annotate] → [Compile] → [Resolve Lists] → [Generate Scenarios] → [Verify & Repair]
  129. │ │ │ │ │
  130. ▼ ▼ ▼ ▼ ▼
  131. tool-annotations compiled-policy dynamic-lists test-scenarios verified policy
  132. .json .json .json .json (or build failure)
  133. ```
  134. 1. **Annotate** — Classify each MCP tool's arguments by role (read-path, write-path, delete-path, none).
  135. 2. **Compile** — Translate the English constitution into deterministic if/then rules. Categorical references ("major news sites", "my contacts") are emitted as `@list-name` symbolic references.
  136. 3. **Resolve Lists** — Resolve symbolic lists to concrete values via LLM knowledge or MCP tool-use (e.g., querying a contacts database). Written to `dynamic-lists.json`, user-editable. Skipped when no lists are present.
  137. 4. **Generate Scenarios** — Create test scenarios from the constitution plus mandatory handwritten invariant tests.
  138. 5. **Verify & Repair** — Run scenarios against the real policy engine. An LLM judge analyzes failures and generates targeted repairs (up to 2 rounds). Build fails if the policy cannot be verified.
  139. All artifacts are content-hash cached — only changed inputs trigger recompilation.
  140. ### What compiled rules look like
  141. A constitution clause like:
  142. ```markdown
  143. - The agent may perform read-only git operations (status, diff, log) within the sandbox without approval.
  144. - The agent must receive human approval before git push, pull, fetch, or any remote-contacting operation.
  145. ```
  146. compiles to:
  147. ```json
  148. [
  149. { "tool": "git_status", "decision": "allow", "condition": { "directory": { "within": "$SANDBOX" } } },
  150. { "tool": "git_diff", "decision": "allow", "condition": { "directory": { "within": "$SANDBOX" } } },
  151. { "tool": "git_push", "decision": "escalate", "reason": "Remote-contacting git operations require human approval" }
  152. ]
  153. ```
  154. Any call that doesn't match an explicit `allow` or `escalate` rule is **denied by default**.
  155. ```bash
  156. ironcurtain annotate-tools --server filesystem # Annotate one server (merge with existing)
  157. ironcurtain annotate-tools --all # Re-annotate all servers
  158. ironcurtain compile-policy # Compile constitution into rules and verify
  159. ironcurtain refresh-lists # Re-resolve dynamic lists without full recompilation
  160. ironcurtain refresh-lists --list major-news # Refresh a single list
  161. ```
  162. Review the generated `~/.ironcurtain/generated/compiled-policy.json` — these are the exact rules enforced at runtime.
  163. ## Configuration
  164. IronCurtain stores configuration and session data in `~/.ironcurtain/`:
  165. ```
  166. ~/.ironcurtain/
  167. ├── config.json # User configuration
  168. ├── constitution.md # User-local base constitution (overrides package default)
  169. ├── constitution-user.md # Your policy customizations (generated by customize-policy)
  170. ├── generated/ # User-compiled policy artifacts (overrides package defaults)
  171. ├── personas/ # Persona directories (constitution, policy, workspace, memory)
  172. ├── skills/ # User-global SKILL.md packages, mounted into every Docker session
  173. ├── jobs/ # Cron job definitions, workspaces, and run records
  174. ├── statistics/ # Content-free local LLM usage database + pseudonymization key
  175. ├── sessions/
  176. │ └── {sessionId}/
  177. │ ├── sandbox/ # Per-session filesystem sandbox
  178. │ ├── escalations/ # File-based IPC for human approval
  179. │ ├── audit.jsonl # Per-session audit log
  180. │ └── session.log # Diagnostics
  181. └── workflow-runs/ # Shared-container workflow runs (see below)
  182. ```
  183. 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.
  184. ### Workflow run layout
  185. 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:
  186. ```
  187. ~/.ironcurtain/workflow-runs/<workflowId>/
  188. ├── audit.jsonl # Persona-tagged append-only audit
  189. ├── messages.jsonl # Orchestrator message log
  190. ├── workspace/ # Agent workspace (filesystem MCP root)
  191. ├── bundle/ # Shared container support (claude-state, orientation, sockets, escalations, system-prompt.txt)
  192. ├── states/
  193. │ └── <stateId>.<visitCount>/ # session.log + session-metadata.json per invocation
  194. └── proxy-control.sock # Coordinator UDS for policy hot-swap
  195. ```
  196. 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](WORKFLOWS.md) for authoring workflow definitions and the full lifecycle.
  197. Edit configuration interactively:
  198. ```bash
  199. ironcurtain config
  200. ```
  201. 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](CONFIG.md) for the full reference.
  202. ### Local LLM statistics
  203. Content-free LLM usage collection is enabled by default. It records token counts (input, thinking, output, and
  204. totals), timing, protocol/provider/model routing, outcomes, refusals, and cost metadata when providers expose it. It
  205. does not store prompts, completions, thinking text, tool payloads, request/response bodies, credentials, or arbitrary
  206. headers. User/config-derived labels and non-public routes are pseudonymized with a local HMAC key; bounded model and
  207. provider identifiers remain readable for analysis.
  208. Data lives in `~/.ironcurtain/statistics/llm-usage.sqlite3`; the pseudonymization key is
  209. `~/.ironcurtain/statistics/identity.key`. The default retention period is 90 days. Use `ironcurtain config` →
  210. **LLM Statistics**, the web UI Settings view, or set `"statistics": { "enabled": false }` to opt out. Set
  211. `retentionDays` to `null` to disable automatic pruning. Restart a long-running daemon after changing these settings.
  212. Manual deletion is available with `ironcurtain statistics delete --before <ISO-date-or-epoch-ms>` or `--all`.
  213. This is logical SQLite row deletion, not secure erasure: deleted bytes may remain in free pages, WAL files, filesystem
  214. snapshots, or backups. The identity key is not rotated or deleted by these commands.
  215. To route LLM traffic through a gateway like LiteLLM or OpenRouter (in both Code Mode and Docker Agent Mode), see [MODEL_ROUTING.md](MODEL_ROUTING.md).
  216. Route Docker agents through model-provider profiles (e.g. GLM-5.3 / GLM-5.3-Flash via OpenRouter, no sidecar) with `ironcurtain config` → Model Providers, then pick a profile at `/new` or with `--provider-profile` — see [MODEL_ROUTING.md](MODEL_ROUTING.md#first-class-openrouter).
  217. ## Built-in Capabilities
  218. IronCurtain ships with six pre-configured MCP servers. All tool calls (except memory) are governed by your compiled policy.
  219. | Server | Tools | Key capabilities |
  220. | -------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
  221. | **Filesystem** | 14 | Read, write, edit, search files; directory tree; move; diff calculation |
  222. | **Git** | 28 | Full git workflow: status, diff, log, commit, branch, push/pull/fetch, clone, stash, blame |
  223. | **Fetch** | 2 | HTTP GET with HTML-to-markdown conversion; web search (Brave, Tavily, SerpAPI, Parallel Search) |
  224. | **GitHub** | 41 | Issues, PRs, code search, reviews via `ghcr.io/github/github-mcp-server`; requires a GitHub personal access token |
  225. | **Google Workspace** | 128 | Gmail, Calendar, Drive, Docs, Sheets — requires OAuth setup via `ironcurtain auth` |
  226. | **Memory** | 5 | Persistent semantic memory with hybrid vector+keyword search, LLM summarization, and automatic compaction. Enabled for persona and cron sessions. |
  227. Read-only operations are allowed by default policy; mutations (writes, pushes, PR creation) escalate for human approval. Tools use `server.tool` naming (e.g., `filesystem.read_file`, `memory.recall`). See [ADDING_MCP_SERVERS.md](ADDING_MCP_SERVERS.md) to add your own.
  228. ### Network Passthrough (Docker Agent Mode)
  229. 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.
  230. 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](docs/SECURITY_CONCERNS.md) Section 2b-i for the threat model and [DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md) for usage details.
  231. ## Security Model
  232. IronCurtain is designed around a specific threat model: **the LLM goes rogue.** This can happen through prompt injection (a malicious email or web page hijacks the agent) or through multi-turn drift (the agent gradually deviates from the user's intent over a long session).
  233. ### What IronCurtain enforces
  234. - **Filesystem containment** — Symlink-aware path resolution prevents path traversal and symlink-escape attacks.
  235. - **Per-tool policy** — Each MCP tool call is evaluated against compiled rules. The policy engine classifies tool arguments by role (read-path, write-path, delete-path) to make fine-grained decisions.
  236. - **Structural invariants** — Certain protections are hardcoded and cannot be overridden by the constitution: the agent can never modify its own policy files, audit logs, or configuration.
  237. - **Human escalation** — When policy says "escalate," the agent pauses and the user must explicitly approve or deny. Optionally, an LLM-based auto-approver handles unambiguous cases (see [CONFIG.md](CONFIG.md)).
  238. - **Audit trail** — Every tool call and policy decision is logged to an append-only JSONL audit log.
  239. - **Resource limits** — Token, step, time, and cost budgets prevent runaway sessions.
  240. ### Known limitations
  241. This is a research prototype. Known gaps include:
  242. - **Policy compilation fidelity** — The LLM-based compiler can misinterpret constitution intent. The verification pipeline catches many errors but is not exhaustive. Always review the compiled `compiled-policy.json`.
  243. - **V8 isolate boundaries** — Code Mode uses V8 isolates, not OS-level virtualization. A V8 zero-day could allow escape.
  244. - **No outbound content inspection** — An agent allowed to write files could encode sensitive data to bypass content-level controls. Planned: LLM-based intelligibility checks on outbound content.
  245. - **Escalation fatigue** — Too many false-positive escalations can lead to habitual approval. Tune your constitution to minimize unnecessary prompts.
  246. See [docs/SECURITY_CONCERNS.md](docs/SECURITY_CONCERNS.md) for a detailed threat analysis.
  247. ## Troubleshooting
  248. | Issue | Guidance |
  249. | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  250. | **Missing API key** | Set the environment variable (`ANTHROPIC_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY`, or `OPENAI_API_KEY`) or add the corresponding key to `~/.ironcurtain/config.json`. |
  251. | **Sandbox unavailable** | OS-level sandboxing requires `bubblewrap` and `socat`. Install both, or set `"sandboxPolicy": "warn"` in your MCP server config for development. |
  252. | **Budget exhausted** | Adjust limits in `~/.ironcurtain/config.json` under `resourceBudget`. Set any individual limit to `null` to disable it. |
  253. | **Node version errors** | Supported Node.js lines are 24 and 26. Both install prebuilt `isolated-vm` binaries. Other major versions are rejected by `ironcurtain doctor`. |
  254. | **Policy doesn't match intent** | Review `compiled-policy.json` to see the generated rules. Run `ironcurtain customize-policy` to refine your constitution, then `ironcurtain compile-policy` to recompile. Specific wording produces better rules — vague phrasing leads to vague policy. |
  255. | **Auto-approve not triggering** | The auto-approver only approves when the user's message explicitly authorizes the action (e.g., "push to origin" for `git_push`). Vague messages always escalate to human review. Verify `autoApprove.enabled` is `true` in `config.json`. |
  256. | **PTY/mux terminal garbled after exit** | Run `reset` in that terminal to restore normal mode. This is needed when the process is killed ungracefully and raw mode is not restored. |
  257. | **Mux/listener: "already running"** | Only one mux or escalation-listener can run at a time. The lock at `~/.ironcurtain/escalation-listener.lock` is auto-cleared if the previous process is dead. If it persists, check the PID in the lock file. |
  258. | **Signal bot not responding** | Verify the signal-cli container is running (`docker ps \| grep ironcurtain-signal`). Check that Signal is configured (`ironcurtain setup-signal`). See [TRANSPORT.md](TRANSPORT.md) for detailed troubleshooting. |
  259. ## Development
  260. ```bash
  261. npm test # Run all tests
  262. npm test -- test/policy-engine.test.ts # Run a single test file
  263. npm test -- -t "denies delete_file" # Run a single test by name
  264. npm run lint # Lint
  265. npm run build # TypeScript compilation + asset copy
  266. ```
  267. See [TESTING.md](TESTING.md) for the full testing guide, including integration test flags and conventions.
  268. ### Project Structure
  269. ```
  270. src/
  271. ├── index.ts # Entry point
  272. ├── cli.ts # CLI command dispatcher
  273. ├── config/ # Configuration loading, constitution, MCP server definitions
  274. ├── session/ # Multi-turn session management, budgets, loop detection
  275. ├── sandbox/ # V8 isolated execution environment
  276. ├── trusted-process/ # Policy engine, MCP proxy, audit log, escalation handler
  277. ├── pipeline/ # Constitution → policy compilation pipeline
  278. ├── escalation/ # Escalation listener: session registry, TUI dashboard, state
  279. ├── mux/ # Terminal multiplexer: PTY bridge, renderer, trusted input
  280. ├── persona/ # Persona management (create, compile, resolve)
  281. ├── memory/ # Memory server integration (config, annotations, path resolution)
  282. ├── signal/ # Signal messaging transport (bot daemon, setup, formatting)
  283. ├── daemon/ # Unified daemon (Signal + cron scheduler, control socket)
  284. ├── cron/ # Cron job management (scheduler, job store, git sync, policy)
  285. ├── docker/ # Docker agent mode, PTY session, MITM proxy, registry proxy
  286. ├── workflow/ # Multi-agent workflow engine (orchestrator, state machine, gates)
  287. ├── web-ui/ # Web UI backend (JSON-RPC dispatch, event bus, workflow manager)
  288. ├── servers/ # Built-in MCP servers (fetch, web search providers)
  289. └── types/ # Shared type definitions
  290. packages/
  291. └── memory-mcp-server/ # Standalone memory MCP server (publishable npm package)
  292. ```
  293. ## License
  294. [Apache-2.0](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.