IronCurtain

Безопасная* среда выполнения для автономных ИИ-агентов, в которой политика безопасности выводится из читаемого человеком устава (constitution).

*Когда кто-то пишет «secure», вы должны сразу же отнестись с подозрением. Что мы имеем в виду под secure?

[!WARNING] Исследовательский прототип. IronCurtain — это ранний исследовательский проект, изучающий, как сделать ИИ-агентов достаточно безопасными, чтобы они были по-настоящему полезными. API, форматы конфигурации и архитектура могут меняться. Приветствуются вклад и обратная связь.

Demo

Агента просят клонировать репозиторий и отправить изменения. Оба действия — git_clone и git_push — эскалируются политическим движком, но авто-одобритель одобряет их автоматически: доверенный ввод пользователя из командного режима (Ctrl-A) выражал явное намерение, так что ручной /approve не понадобился.

The Problem

Автономные ИИ-агенты могут управлять файлами, выполнять команды git, отправлять сообщения и взаимодействовать с API от вашего имени. Но современные агентные фреймворки дают агенту те же привилегии, что и пользователю, — например, полный доступ к файловой системе, учётным данным и сети. Исследователи безопасности называют это ambient authority, и это означает, что одиночная prompt-инъекция или дрейф в многоходовом диалоге могут заставить агента удалять файлы, похищать данные или публиковать вредоносный код.

Обычный ответ — либо ограничить агентов узкой песочницей (что ограничивает их полезность), либо просить пользователя одобрять каждое действие (что ограничивает их автономию). Ни то, ни другое не является удовлетворительным.

The Approach

IronCurtain идёт другим путём: сформулируйте ваши требования безопасности на простом английском, а система сама разберётся с их соблюдением.

Вы пишете конституцию — короткий документ, описывающий, что агенту разрешено и запрещено делать. IronCurtain компилирует её в детерминированную политику безопасности с помощью LLM-конвейера, проверяет скомпилированные правила на сгенерированных тестовых сценариях, а затем применяет политику во время выполнения при каждом вызове инструмента. В результате получается агент, который может работать автономно в границах, заданных вами на естественном языке.

Ключевые идеи:

• Агент не заслуживает доверия. IronCurtain исходит из того, что LLM может быть скомпрометирована из-за prompt-инъекции или дрейфа. Безопасность не зависит от того, что модель «ведёт себя хорошо».
• Английский на входе, исполнение на выходе. Вы описываете намерение («никаких разрушительных операций git без одобрения»); система компилирует его в детерминированные правила, которые применяются во время выполнения без дальнейшего участия LLM.
• Семантическая интерпозиция. Вместо предоставления агенту прямого доступа к системе все взаимодействия проходят через MCP серверы (файловая система, git и т.д.). Каждый вызов инструмента проходит через политический движок, который может разрешить, запретить или эскалировать решение пользователю для одобрения.
• Эшелонированная защита. Код агента выполняется в изоляте V8 без прямого доступа к хосту. Единственный способ выйти наружу — семантически осмысленные вызовы MCP-инструментов, и каждый из них проверяется на соответствие политике.

Architecture

IronCurtain поддерживает два режима сеансов с разными моделями доверия:

• Builtin Agent (Code Mode) — собственный LLM-агент IronCurtain пишет TypeScript-фрагменты, которые выполняются в песочнице V8. IronCurtain контролирует агента, песочницу и политический движок. Каждый вызов инструмента покидает песочницу как структурированный MCP-запрос, проходит через политический движок (разрешить / запретить / эскалировать) и только затем достигает реального MCP-сервера.

• Docker Agent Mode — внешний агент (Claude Code, Goose и т.п.) работает внутри Docker-контейнера без доступа к сети. IronCurtain опосредует внешние эффекты: вызовы LLM API проходят через TLS-терминирующий MITM-прокси (разрешённый список хостов, подмена ключей fake-to-real), вызовы MCP-инструментов проходят через тот же политический движок, а установка пакетов (npm/PyPI) идёт через проверяющий прокси-реестр.

В обоих режимах агент не заслуживает доверия. Безопасность не зависит от того, следует ли модель инструкциям, — она обеспечивается на границе.

См. SANDBOXING.md с полной архитектурой, диаграммами, послойным анализом доверия и примечаниями по macOS.

Quick Start

Prerequisites

• Node.js 22, 24 или 26 — чётные мажорные ветки, на которых тестируется IronCurtain (требование isolated-vm; для 24 и 26 устанавливаются готовые бинарники, Node 22 компилируется из исходников при установке и требует тулчейн C/C++). Нечётные ветки (23, 25) работают, но не тестируются — ironcurtain doctor выдаст предупреждение.
• Docker — не обязателен, но настоятельно рекомендуется для Docker Agent Mode, который обеспечивает самую сильную изоляцию. На macOS 26+ (Apple silicon) Apple container работает как альтернативный бэкенд (виртуальная машина на каждый контейнер; используется автоматически, когда его службы запущены — см. containerRuntime в ironcurtain config)
• API-ключ хотя бы для одного LLM-провайдера (Anthropic, Google или OpenAI)

Install

Как глобальный 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.json` с помощью `ironcurtain config`. Переменные окружения имеют приоритет над значениями из файла конфигурации. Поддерживаются: `ANTHROPIC_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY`, `OPENAI_API_KEY`.

**2. Запустите мастер первичной настройки** (запустите его явно перед использованием рекомендуемого пути mux; он также запускается автоматически при первом запуске `ironcurtain start` без mux):```bash
ironcurtain setup

Проводит вас через настройку GitHub-токена, провайдера веб-поиска, выбора модели и других параметров. Создаёт ~/.ironcurtain/config.json с вашими выборами.

Запуск IronCurtain

IronCurtain поставляется с политикой по умолчанию, ориентированной на опыт разработчика: операции чтения разрешены, а изменения (записи, push, создание PR) требуют одобрения человека. Вы можете начать использовать его сразу после настройки.

Терминальный мультиплексор (рекомендуется)

Рекомендуемый способ использования IronCurtain. Он даёт вам всю мощь интерактивного TUI вашего агента (Claude Code или Goose), пока IronCurtain пропускает каждый вызов инструмента через свой движок политик — всё в одном терминале.```bash ironcurtain mux

**Ключевые возможности:**

- **Полноценный TUI агента** — Агент работает в PTY внутри Docker-контейнера без доступа к сети. Вы взаимодействуете с ним точно так же, как если бы он работал локально.
- **Встроенная обработка эскалации** — Когда вызов инструмента требует одобрения, поверх области просмотра появляется панель эскалации с действиями по одной клавише (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/HEAD/DEVELOPER_GUIDE.md): режимы ввода, модель безопасности доверенного ввода, процесс эскалации и справочник по клавиатуре.

### Сеансы без mux

Используйте `ironcurtain start` для быстрых разовых задач, скриптов или когда вам явно нужен локальный встроенный агент. Для обычной интерактивной работы с Docker-агентом используйте `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>), устаревший режим raw PTY/отладки, транспорт обмена сообщениями Signal для мобильного подтверждения и режим демона для запланированных cron-задач. Демон имеет опциональный веб-интерфейс (--web-ui) для мониторинга через браузер и обработки эскалаций. Подробнее см. RUNNING_MODES.md.

Мультиагентные рабочие процессы

IronCurtain координирует несколько ИИ-агентов через структурированные рабочие процессы. Встроенный рабочий процесс обнаружения уязвимостей ищет ошибки безопасности памяти и логические ошибки в нативном коде через многоуровневый конвейер харнессов (уровень 1: изолированная функция → уровень 2: многокомпонентный → уровень 3: полная сборка) с контролем покрытия libFuzzer/AFL++, управляемыми гипотезами состояниями discover/triage и финальным этапом проверки отчёта человеком. Рабочий процесс design-and-code выполняет циклы «план / дизайн / реализация / ревью», также с участием человека на контрольных точках. Каждый агент работает в собственном Docker-контейнере с ролевыми границами политик; движок автоматически управляет переходами состояний, передачей артефактов и контрольными точками для возобновления после сбоя. Open source, полностью работает на вашей машине, обеспечивает соблюдение политик безопасности каждого агента через конституционный движок политик и работает с любым Docker-контейнеризированным агентом — по охвату сопоставим с Amazon Kiro и Google Jules для задач кодирования, но с первоклассной безопасностью и расширяемым форматом определения рабочих процессов.

Веб-интерфейс — это основной интерфейс для запуска рабочих процессов. Запустите демон, откройте выведенный 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.

Настройка вашей политики

Политика по умолчанию хорошо подходит для общей разработки, но вы можете адаптировать её под свой рабочий процесс:

1. Настройте свою конституцию (необязательно, но рекомендуется):```bash ironcurtain customize-policy

Разговор с LLM-ассистентом, который генерирует конституцию, адаптированную под ваш рабочий процесс, сохраняемую в `~/.ironcurtain/constitution-user.md`. Вы также можете редактировать этот файл напрямую.

**2. Составьте политику:**```bash
ironcurtain compile-policy

Преобразует вашу конституцию в детерминированные правила, генерирует тестовые сценарии и проверяет их. Скомпилированные артефакты сохраняются в ~/.ironcurtain/generated/.

Персоны

Персоны — это именованные политические профили: каждая объединяет конституцию, скомпилированную политику, постоянное рабочее пространство и семантическую память. Используйте их для запуска агентов с разными ролями или уровнями доступа.```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` открывает вкладку с использованием этой персоны. Персоны также можно назначать заданиям cron. См. [DAEMON.md](https://github.com/provos/ironcurtain/blob/HEAD/DAEMON.md) о настройке запланированных заданий.

Персонами также можно управлять через [веб-интерфейс](https://github.com/provos/ironcurtain/blob/HEAD/DAEMON.md#persona-policy-management) — просматривать, создавать, редактировать конституции и компилировать политики с отображением прогресса в реальном времени. Поскольку политика является границей безопасности, элементы изменения в веб-интерфейсе доступны только для чтения, если демон не запущен с `--allow-policy-mutation` (по умолчанию выключено).

### Skills

Размещайте пакеты SKILL.md в `~/.ironcurtain/skills/<name>/`, чтобы предоставить целевые инструкции (вспомогательные скрипты, детерминированные проверки, предметные знания) каждой сессии Docker-агента. Объединённый набор помещается в отдельный каталог на хосте для каждого бандла и монтируется в контейнер **только для чтения** по тому пути, который сканирует встроенный механизм обнаружения активного агента: Claude Code указывается на промежуточный каталог через `--add-dir`, Goose сканирует `~/.config/goose/skills/<name>/SKILL.md`. Агент обнаруживает их автоматически и сам решает, когда их читать, на основе описания во frontmatter каждого навыка. _Формат_ SKILL.md — это открытый стандарт, принятый в Claude Code, Goose и Codex; различается только _путь обнаружения_ у каждого агента. Воркфлоу могут включать навыки для отдельных состояний внутри своего пакета — см. [WORKFLOWS.md](https://github.com/provos/ironcurtain/blob/HEAD/WORKFLOWS.md#skills).

## Политика: Конституция → Исполнение

Вы описываете намерение простым английским языком; 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-инструмента по роли (read-path, write-path, delete-path, none).
2. Компиляция — Переведите английскую конституцию в детерминированные правила «если/то». Категориальные ссылки («крупные новостные сайты», «мои контакты») выводятся как символические ссылки @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
├── 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/ — см. следующий раздел.

Структура запуска рабочего процесса

Определение рабочего процесса может включить использование общего Docker-контейнера, задав settings.sharedContainer: true в своём YAML. В этом режиме каждое состояние агента выполняется внутри одного долгоживущего контейнера и использует один экземпляр политики; между состояниями оркестратор в горячем режиме подменяет активную политику, чтобы каждая персона видела свои правила. Все артефакты запуска сохраняются в едином дереве:``` ~/.ironcurtain/workflow-runs// ├── 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/ │ └── ./ # 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/HEAD/WORKFLOWS.md) о создании определений рабочих процессов и полном жизненном цикле.

Редактирование конфигурации в интерактивном режиме:```bash
ironcurtain config

Ключевые области конфигурации: модели и ключи API, бюджеты ресурсов (лимиты токенов/шагов/времени/стоимости), эскалации с автоматическим одобрением, провайдер веб-поиска, редактирование аудита и настройки LLM сервера памяти. Полную справку см. в CONFIG.md.

Чтобы направить трафик LLM через шлюз вроде LiteLLM или OpenRouter (в режимах Code Mode и Docker Agent Mode), см. MODEL_ROUTING.md.

Маршрутизируйте агентов Docker через профили поставщиков моделей (например, GLM-5.2 через OpenRouter, без sidecar) с помощью ironcurtain config → Model Providers, затем выберите профиль в /new или с помощью --provider-profile — см. MODEL_ROUTING.md.

Встроенные возможности

IronCurtain поставляется с шестью предварительно настроенными MCP-серверами. Все вызовы инструментов (кроме memory) регулируются скомпилированной политикой.

Операции только для чтения разрешены политикой по умолчанию; изменения (запись, push, создание PR) эскалируются на утверждение человеком. Инструменты используют именование server.tool (например, filesystem.read_file, memory.recall). Чтобы добавить свои собственные, см. ADDING_MCP_SERVERS.md.

Сквозной сетевой доступ (Docker Agent Mode)

В режиме Docker Agent Mode контейнер не имеет доступа к сети — весь трафик проходит через MITM-прокси IronCurtain. По умолчанию доступны только домены LLM-провайдеров. Агент может запросить доступ к дополнительным доменам во время выполнения через виртуальный MCP-сервер proxy (add_proxy_domain). Каждый запрос требует одобрения человека через процедуру эскалации.

Одобренные домены получают сквозной туннель без обработки — соединения HTTP, HTTPS и WebSocket пересылаются без проверки содержимого и внедрения учётных данных. Это даёт агенту больше возможностей (вызов сторонних API, стриминг данных из внешних сервисов), но означает, что трафик на эти домены без посредничества. Модель угроз см. в SECURITY_CONCERNS.md, раздел 2b-i, а подробности использования — в DEVELOPER_GUIDE.md.

Модель безопасности

IronCurtain спроектирован вокруг конкретной модели угроз: LLM выходит из-под контроля. Это может произойти через prompt injection (вредоносное письмо или веб-страница перехватывает агента) или через многоходовой дрейф (агент постепенно отклоняется от намерений пользователя в течение длительной сессии).

Что обеспечивает IronCurtain

• Изоляция файловой системы — Учёт симлинков при разрешении путей предотвращает path traversal и symlink-escape атаки.
• Политика для каждого инструмента — Каждый вызов MCP-инструмента оценивается по скомпилированным правилам. Движок политик классифицирует аргументы инструментов по роли (read-path, write-path, delete-path) для принятия детальных решений.
• Структурные инварианты — Некоторые защитные механизмы зашиты на уровне кода и не могут быть переопределены конституцией: агент никогда не может изменять свои собственные файлы политик, журналы аудита или конфигурацию.
• Эскалация на человека — Когда политика требует «эскалировать», агент останавливается, и пользователь должен явно одобрить или отклонить. Опционально автоматический одобритель на основе LLM обрабатывает однозначные случаи (см. CONFIG.md).
• Журнал аудита — Каждый вызов инструмента и решение политики записываются в журнал аудита JSONL в режиме append-only.
• Лимиты ресурсов — Бюджеты токенов, шагов, времени и стоимости предотвращают неконтролируемые сессии.

Известные ограничения

Это исследовательский прототип. Известные пробелы включают:

• Точность компиляции политики — Компилятор на основе LLM может неверно истолковать намерения конституции. Конвейер верификации выявляет многие ошибки, но не является исчерпывающим. Всегда проверяйте скомпилированный compiled-policy.json.
• Границы изолятов V8 — Code Mode использует изоляты V8, а не виртуализацию на уровне ОС. Zero-day в V8 может позволить побег.
• Отсутствие проверки исходящего содержимого — Агент, которому разрешено записывать файлы, может закодировать чувствительные данные, чтобы обойти контроль на уровне содержимого. Запланировано: проверки понятности исходящего содержимого на основе LLM.
• Усталость от эскалаций — Слишком большое количество ложноположительных эскалаций может привести к привычному одобрению. Настройте конституцию, чтобы минимизировать ненужные запросы.

Подробный анализ угроз см. в docs/SECURITY_CONCERNS.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/HEAD/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