IronCurtain

자율 AI 에이전트를 위한 안전한* 런타임으로, 보안 정책이 사람이 읽을 수 있는 헌법에서 도출됩니다.

*누군가 "안전하다"고 말할 때, 즉시 의심해야 합니다. 우리가 말하는 안전이란 무엇인가?

[!WARNING] 연구 프로토타입. IronCurtain은 AI 에이전트를 진정으로 유용할 만큼 안전하게 만드는 방법을 탐구하는 초기 단계 연구 프로젝트입니다. API, 구성 형식, 아키텍처는 변경될 수 있습니다. 기여와 피드백을 환영합니다.

데모

에이전트에게 저장소를 복제하고 변경 사항을 푸시하도록 요청합니다. git_clone과 git_push 모두 정책 엔진에 의해 에스컬레이션되지만, 자동 승인기가 자동으로 승인합니다 — 명령 모드(Ctrl-A)에서의 사용자 신뢰 입력이 명확한 의도를 제공했기 때문에 수동 /approve가 필요하지 않았습니다.

문제

자율 AI 에이전트는 파일을 관리하고, git 명령을 실행하고, 메시지를 보내고, 사용자를 대신하여 API와 상호작용할 수 있습니다. 그러나 오늘날의 에이전트 프레임워크는 에이전트에게 파일 시스템, 자격 증명, 네트워크에 대한 전체 접근 권한과 같이 사용자와 동일한 권한을 부여합니다. 보안 연구자들은 이를 주변 권한(ambient authority) 이라고 부르며, 이는 단일 프롬프트 인젝션 또는 다중 턴 드리프트로 인해 에이전트가 파일을 삭제하거나, 데이터를 유출하거나, 악성 코드를 푸시할 수 있음을 의미합니다.

일반적인 대응은 에이전트를 좁은 샌드박스로 제한하거나(유용성 제한), 사용자에게 모든 작업을 승인하도록 요청하는 것(자율성 제한)입니다. 어느 쪽도 만족스럽지 않습니다.

접근 방식

IronCurtain은 다른 길을 택합니다: 보안 의도를 평범한 영어로 표현하면, 시스템이 시행 방법을 알아냅니다.

에이전트가 무엇을 할 수 있고 무엇을 할 수 없는지 설명하는 짧은 문서인 헌법(constitution) 을 작성합니다. IronCurtain은 LLM 파이프라인을 사용하여 이를 결정론적 보안 정책으로 컴파일하고, 생성된 테스트 시나리오에 대해 컴파일된 규칙을 검증한 다음, 런타임에 모든 도구 호출에 대해 정책을 시행합니다. 그 결과는 자연어로 정의한 경계 내에서 자율적으로 작업할 수 있는 에이전트입니다.

핵심 아이디어:

• 에이전트는 신뢰할 수 없습니다. IronCurtain은 LLM이 프롬프트 인젝션 또는 드리프트에 의해 손상될 수 있다고 가정합니다. 보안은 모델이 "착하게 행동하는 것"에 의존하지 않습니다.
• 영어로 입력, 시행으로 출력. 의도를 작성하면("승인 없이 파괴적인 git 작업 금지"), 시스템이 이를 결정론적 규칙으로 컴파일하여 런타임에 추가 LLM 개입 없이 시행합니다.
• 의미론적 개입(Semantic interposition). 에이전트에게 원시 시스템 접근 권한을 부여하는 대신, 모든 상호작용은 MCP 서버(파일 시스템, git 등)를 통해 이루어집니다. 모든 도구 호출은 허용, 거부, 또는 사용자 승인으로 에스컬레이션할 수 있는 정책 엔진을 통과합니다.
• 심층 방어. 에이전트 코드는 호스트에 대한 직접 접근 권한이 없는 V8 아이솔레이트에서 실행됩니다. 나가는 유일한 방법은 의미론적으로 의미 있는 MCP 도구 호출을 통하는 것이며, 모든 호출은 정책에 대해 검사됩니다.

아키텍처

IronCurtain은 서로 다른 신뢰 모델을 가진 두 가지 세션 모드를 지원합니다:

• 내장 에이전트(코드 모드) — IronCurtain 자체 LLM 에이전트가 V8 샌드박스에서 실행되는 TypeScript 스니펫을 작성합니다. IronCurtain은 에이전트, 샌드박스, 정책 엔진을 제어합니다. 모든 도구 호출은 구조화된 MCP 요청으로 샌드박스를 나가고, 정책 엔진(허용/거부/에스컬레이션)을 통과한 다음에야 실제 MCP 서버에 도달합니다.

• Docker 에이전트 모드 — 외부 에이전트(Claude Code, Goose, Codex)가 공용 네트워크에 직접 접근하지 않고 컨테이너 내부에서 실행됩니다. IronCurtain은 외부 효과를 중재합니다: LLM API 호출은 TLS 종료 MITM 프록시(호스트 허용 목록, 가짜 키에서 실제 키로 교체)를 통과하고, MCP 도구 호출은 동일한 정책 엔진을 통과하며, 지원되는 패키지 설치는 검증 패키지 프록시를 통과합니다.

선택적 중첩 Docker는 개발자 세션에 호스트 Docker 소켓을 노출하지 않고 비공개 임시 데몬을 제공합니다. 구현된 프로필은 macOS의 Apple Container 및 Docker Desktop, 그리고 amd64의 WSL2와 Docker Desktop을 지원합니다. offline, images, packages 모드는 로컬 이미지 사용, 중재된 공용 이미지 풀, 지원되는 패키지 빌드를 구분합니다. 네이티브 Linux Engine은 중첩에 허용되지 않습니다. 전제 조건과 제한 사항은 구성 참조를 확인하세요.

두 모드 모두에서 에이전트는 신뢰할 수 없습니다. 보안은 모델이 지시를 따르는 것에 의존하지 않으며 — 경계에서 시행됩니다.

다이어그램, 계층별 신뢰 분석, macOS 플랫폼 참고 사항이 포함된 전체 아키텍처는 SANDBOXING.md를 참조하세요.

빠른 시작

전제 조건

• Node.js 24 또는 26 — IronCurtain이 테스트하는 짝수 메이저 버전입니다. 둘 다 사전 빌드된 isolated-vm 바이너리를 설치합니다. Node 25는 지원되지 않으며 테스트되지 않습니다.
• Docker — 필수는 아니지만 가장 강력한 격리를 제공하는 Docker 에이전트 모드에 강력히 권장됩니다. macOS 26+ (Apple silicon)에서는 Apple container가 대체 백엔드로 작동합니다(컨테이너당 VM; 해당 서비스가 실행 중일 때 자동으로 사용됨 — ironcurtain config의 containerRuntime 참조)
• 최소 하나의 LLM 제공자(Anthropic, Google, 또는 OpenAI)에 대한 API 키

설치

글로벌 CLI 도구로 (최종 사용자):

npm install -g @provos/ironcurtain

소스에서 (개발):

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

최초 설정

1. API 키 설정:

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 시에도 자동으로 실행됩니다):

ironcurtain setup

GitHub 토큰 설정, 웹 검색 제공자, 모델 선택 및 기타 설정을 안내합니다. 선택한 내용으로 ~/.ironcurtain/config.json을 생성합니다.

IronCurtain 실행하기

IronCurtain은 개발자 경험에 맞춘 기본 정책과 함께 제공됩니다 — 읽기 전용 작업은 허용되고, 변경 작업(쓰기, 푸시, PR 생성)은 사람의 승인을 위해 에스컬레이션됩니다. 설정 후 즉시 사용을 시작할 수 있습니다.

터미널 멀티플렉서 (권장)

IronCurtain을 사용하는 권장 방법입니다. 에이전트의 대화형 TUI(Claude Code 또는 Goose)의 모든 기능을 활용하면서 IronCurtain이 정책 엔진을 통해 모든 도구 호출을 중재합니다 — 모두 단일 터미널에서 이루어집니다.

ironcurtain mux

주요 기능:

• 완전한 에이전트 TUI — 에이전트는 네트워크 접근이 없는 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를 참조하세요: 입력 모드, 신뢰할 수 있는 입력 보안 모델, 에스컬레이션 워크플로, 키보드 참조.

비-mux 세션

빠른 일회성 작업, 스크립트, 또는 로컬 내장 에이전트를 명시적으로 원할 때는 ironcurtain start를 사용하세요. 일반적인 대화형 Docker 에이전트 작업에는 ironcurtain mux를 사용하세요.

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 작업을 위한 데몬 모드도 지원합니다. 데몬에는 브라우저 기반 모니터링 및 에스컬레이션 처리를 위한 선택적 웹 UI(--web-ui)가 있습니다. 자세한 내용은 RUNNING_MODES.md를 참조하세요.

멀티 에이전트 워크플로

IronCurtain은 구조화된 워크플로를 통해 여러 AI 에이전트를 오케스트레이션합니다. 번들로 제공되는 취약점 발견 워크플로는 libFuzzer/AFL++ 커버리지 게이팅, 가설 기반 discover/triage 상태, 그리고 최종 인간 보고서 검토 게이트를 갖춘 계층형 하네스 파이프라인(Tier 1 격리 함수 → Tier 2 다중 컴포넌트 → Tier 3 전체 빌드)을 통해 네이티브 코드의 메모리 안전성 및 로직 버그를 추적합니다. 설계-및-코드 워크플로는 계획 / 설계 / 구현 / 검토 주기를 실행하며, 역시 인간 게이트를 포함합니다. 각 에이전트는 역할별 정책 경계를 가진 자체 Docker 컨테이너에서 실행되며, 엔진은 상태 전환, 아티팩트 전달, 크래시-재개 체크포인팅을 자동으로 관리합니다. 오픈 소스이며, 전적으로 사용자의 머신에서 실행되고, 헌법 기반 정책 엔진을 통해 에이전트별 보안 정책을 시행하며, 모든 Docker 컨테이너화된 에이전트와 함께 작동합니다 — 코딩 작업에 있어 Amazon Kiro 및 Google Jules와 범위가 유사하지만, 일급 보안과 확장 가능한 워크플로 정의 형식을 갖추고 있습니다.

웹 UI는 워크플로 실행을 위한 의도된 인터페이스입니다. 데몬을 시작하고, 출력된 URL을 열고, Workflows 페이지에서 실행을 구동하세요 — 위의 상태 머신 그래프는 실시간이며, 에이전트 메시지 타임라인은 마크다운 렌더링과 함께 스트리밍되고, 게이트 검토에는 워크스페이스 + 아티팩트 브라우저가 포함되며, 과거 실행은 계속 목록에 남아 있습니다.

ironcurtain daemon --web-ui

스크립팅, 자동화, 디버깅을 위한 CLI 접근이 제공됩니다:

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"