프로젝트 .ai-jail
ai-jail은 이 파일을 신뢰하지 않습니다. 감옥을 더 조일 수만 있고 열 수는 없습니다. allow_hosts나 forward_ports 목록을 줄일 수는 있어도 더할 수는 없습니다. 심볼릭 링크로 걸려 있으면 따라가지 않고, 에이전트에는 그 자리에 빈 파일이 보입니다.
설정이 들어오는 세 곳
설정은 프로젝트 안의 파일, 홈 디렉터리의 파일, 직접 입력한 플래그에서 옵니다. 권한이 낮은 것부터 높은 순으로 적었습니다.
↔ 옆으로 밀어 전체 다이어그램을 확인하세요
프로젝트
전역 ~/.ai-jail
내 파일이므로 ai-jail이 신뢰합니다. 모든 실행에 적용되는 기본 테이블이 있고, 명령의 첫 단어로 선택되는 [commands.<name>] 테이블을 둘 수 있습니다.
명령줄 플래그
플래그의 권한이 가장 높습니다. 스위치는 대부분 --network와 --no-network처럼 쌍으로 있어서, 파일이 연 것을 플래그로 닫을 수도 있습니다.
명령 테이블에서 단일 값은 기본 테이블의 값을 대체하고, 매핑이나 마스크 같은 목록은 기본 테이블의 목록에 더해집니다.
# 기본 테이블: 모든 명령에 적용hide_dotdirs = [".my_secrets"]mask = [".env", ".env.*"] # 명령이 "claude"로 시작할 때만[commands.claude]network = trueenv_pass = ["ANTHROPIC_BASE_URL"]mask = ["*.pem"]스위치 목록
모든 행은 요청하기 전까지 꺼져 있습니다. 예외는 청록색 행 두 개로, 기본으로 켜져 있습니다. 기능 플래그마다 다시 닫는 --no- 짝이 있습니다. 빨간 배지는 감옥을 약하게 만드는 스위치를 뜻합니다. 전체 목록과 이유는 보안 페이지에 있습니다.
네트워크와 서비스
| 플래그 | 설정 키 | 하는 일 | 위험 |
|---|---|---|---|
--network | network = true | 네트워크 전체. 에이전트가 읽을 수 있는 것은 무엇이든 밖으로 보낼 수 있습니다. 호스트 몇 개만 필요하다면 --allow-host가 더 조이는 선택입니다. 둘 다 주지 않으면 샌드박스는 알려진 에이전트 자신의 API 호스트와, Linux에서는 툴체인이 프록시를 통해 여는 패키지 레지스트리에만 닿고, --no-network는 둘 다 닫습니다. | 감옥을 약하게 함 |
--allow-host <HOST> | allow_hosts = [...] | 샌드박스가 나열한 호스트와 그 서브도메인에만, ai-jail 내장 프록시를 거쳐 TCP로 닿습니다. 플래그는 여러 번 쓸 수 있습니다. 2.8.1부터 목록이 기본값에 더해지므로, 알려진 에이전트는 자기 API 호스트를 그대로 유지합니다. --network나 --browser와는 함께 쓸 수 없고, 프로젝트 파일은 목록을 줄일 수만 있습니다. | 한 가지를 엶 |
--forward-port <PORT> | forward_ports = [...] | 호스트 루프백의 포트 하나를 샌드박스 자신의 루프백으로 중계합니다. 호스트 127.0.0.1에 떠 있는 로컬 MCP 서버, 에디터 소켓, 개발용 데이터베이스가 안에서도 같은 포트로 응답하고, 그 밖의 호스트 포트는 모두 닫힌 채입니다. 포트를 더 열려면 플래그를 반복하세요. Linux 전용이고, --network와 함께 쓰거나 1024 미만 포트를 주면 거부됩니다. --allow-host와 함께, 그리고 --lockdown 아래에서도 동작합니다. 그 포트 뒤의 서비스는 통째로 신뢰되며, 허용 목록도 감사 기록도 없습니다. 프로젝트 파일은 목록을 줄일 수만 있습니다. 설정 파일에서 forward_ports를 두는 위치. | 감옥을 약하게 함 |
--ssh | ssh = true | ~/.ssh를 읽기 전용으로 열고 SSH 에이전트 소켓을 연결해서 git push가 되게 합니다. | 한 가지를 엶 |
--docker | no_docker = false | Docker 소켓. 데몬이 호스트를 마운트한 컨테이너를 띄울 수 있으므로 사실상 내 컴퓨터의 root 권한입니다. | 감옥을 약하게 함 |
--tailscale | tailscale = true | Tailscale 소켓. | 한 가지를 엶 |
--systemd-user | systemd_user = true | systemd 사용자 버스. 에이전트가 내 사용자 매니저에게 호스트에서 서비스를 실행해 달라고 요청할 수 있습니다. Linux 전용. | 감옥을 약하게 함 |
에이전트와 환경
| 플래그 | 설정 키 | 하는 일 | 위험 |
|---|---|---|---|
--agent-state | agent_state = true | 에이전트 자신의 로그인. 실행한 하네스의 상태(~/.claude, ~/.codex, Devin이라면 ~/.local/share/devin과 ~/.config/devin 등)를 읽기·쓰기로 마운트하고, 셸에 설정된 API 키를 복사합니다: ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY 또는 GOOGLE_API_KEY, XAI_API_KEY, MOONSHOT_API_KEY. 에이전트는 로그인된 상태로 시작하고, 감옥 안의 모든 것이 그 로그인을 쓸 수 있습니다. --no-agent-state를 주면 로그아웃 상태로 실행됩니다. 락다운에서는 꺼지고, 프로젝트 파일은 끌 수만 있습니다. | 기본 활성 |
--claude-dir <PATH> | claude_dir = "..." | 지정한 디렉터리를 Claude의 상태 디렉터리로 쓰고 CLAUDE_CONFIG_DIR을 설정합니다. | 한 가지를 엶 |
--env <NAME[=VALUE]> | 없음 | 셸에 있는 변수 하나를 전달하거나 NAME=VALUE로 변수 하나를 설정합니다. 여러 번 쓸 수 있고 디스크에 저장되지 않습니다. Linux에서는 값이 메모리 파일을 통해 샌드박스로 전달되어 런처의 명령줄에 나타나지 않지만, 직접 쓴 NAME=VALUE는 ai-jail 자신의 명령줄에는 여전히 보이니, 시크릿에는 --env NAME이나 --env-from-file을 쓰세요. | 한 가지를 엶 |
--env-from-file <PATH> | env_from_file = [...] | 파일에서 엄격한 KEY=VALUE 줄을 읽어 --env처럼 전달합니다. 충돌하면 플래그 쪽이 이깁니다. 파일은 내 소유의 일반 파일이어야 하고, 권한이 0600 이하이며 프로젝트 바깥에 있어야 합니다. 아니면 실행이 실패합니다. ai-jail은 값을 디스크에 저장하지 않고, 설정 키는 전역 파일에서만 동작합니다. | 한 가지를 엶 |
--secret <KEY=host> | secret_hosts = { ... } | KEY의 실제 값을 샌드박스 밖에 둡니다. 에이전트에는 플레이스홀더가 보이고, 프록시가 그 호스트 하나로 가는 요청에만 실제 값을 넣습니다. --allow-host가 필요하고, 키는 --env나 --env-from-file로 먼저 들어와 있어야 합니다. 전역 파일 전용이고 저장되지 않습니다. 그 호스트에 대해 프록시로 평문 HTTP를 보낼 수 있는 클라이언트만 해당하고, HTTPS 터널은 건드리지 않습니다. | 한 가지를 엶 |
--inherit-env | inherit_env = true | 셸 환경 전체를 그 안의 시크릿까지 모두 전달합니다. 쓰지 마세요. | 감옥을 약하게 함 |
| 없음 | env_pass = ["NAME"] | --env와 같지만 전역 파일에서만 동작합니다. 프로젝트 파일에 설정하면 무시됩니다. | 한 가지를 엶 |
툴체인과 도구 자격 증명
| 플래그 | 설정 키 | 하는 일 | 위험 |
|---|---|---|---|
--toolchains | no_toolchains = false | 내 컴파일러와 패키지 관리자는 읽기 전용으로, 의존성 캐시는 감옥 전용 저장소에, 패키지 레지스트리는 필터링 프록시를 통해 닿을 수 있게 합니다. Linux 전용이고 거기서는 기본으로 켜져 있습니다. macOS에서는 아무것도 매핑하지 않고 어떤 레지스트리에도 닿지 않습니다. 락다운에서는 꺼지고, 프로젝트 파일은 끌 수만 있습니다. 아래에 자세히. | 기본 활성 |
--github | github = true | 내 gh 설정 디렉터리를 읽기 전용으로 열고, 활성 github.com 토큰을 그 실행에 한해 GH_TOKEN으로 전달해서, 토큰이 시스템 키링에 있어도 gh가 로그인된 상태가 됩니다. ai-jail은 호스트에서 gh auth token을 실행하고 그 결과를 메모리 파일로 넘기며, 명령줄이나 디스크에는 두지 않습니다. --dry-run은 토큰을 가져오지 않고, --env로 GH_TOKEN을 직접 주면 조회를 건너뜁니다. github.com만, 활성 계정만 해당합니다. 감옥 안의 모든 것이 여전히 GitHub에서 나처럼 행동할 수 있습니다. | 한 가지를 엶 |
--aws | aws = true | 내 ~/.aws, 읽기 전용. 자격 증명이 유효한 동안 감옥 안의 모든 것이 AWS에서 나처럼 행동할 수 있습니다. | 한 가지를 엶 |
--kube | kube = true | 내 ~/.kube, 읽기 전용. 감옥 안의 모든 것이 내 클러스터에 나로서 접근할 수 있습니다. | 한 가지를 엶 |
--gcloud | gcloud = true | 내 ~/.config/gcloud, 읽기 전용. 감옥 안의 모든 것이 Google Cloud에서 나처럼 행동할 수 있습니다. | 한 가지를 엶 |
--docker-config | docker_config = true | 내 ~/.docker/config.json, 읽기 전용. 레지스트리 로그인이 들어 있어서 감옥 안의 모든 것이 그 로그인을 쓸 수 있습니다. | 한 가지를 엶 |
데스크톱과 하드웨어
| 플래그 | 설정 키 | 하는 일 | 위험 |
|---|---|---|---|
--gpu | no_gpu = false | GPU 장치. 드라이버의 공격 표면도 함께 열립니다. Linux 전용. | 한 가지를 엶 |
--kvm | kvm = true | /dev/kvm. QEMU나 Android 에뮬레이터 같은 하드웨어 가속 가상 머신용입니다. 호스트 커널의 KVM 인터페이스가 노출됩니다. 게스트는 샌드박스의 네트워크만 쓰고, tun이나 vhost 장치는 없습니다. Linux 전용. | 한 가지를 엶 |
--display | no_display = false | Wayland 소켓만 열고 세션의 다른 것은 열지 않습니다. Linux 전용. | 한 가지를 엶 |
--x11 | x11 = true | X11 소켓. X11에서는 프로그램이 키 입력을 기록하고 스크린샷을 찍을 수 있습니다. | 감옥을 약하게 함 |
--audio | audio = true | PipeWire와 PulseAudio 소켓, 그리고 /dev/snd. 감옥 안의 모든 것이 오디오를 녹음하고 재생할 수 있습니다. Linux 전용. | 한 가지를 엶 |
--host-shm | host_shm = true | 호스트의 /dev/shm. 감옥 바깥 프로세스와 공유하는 메모리가 열립니다. | 한 가지를 엶 |
--pictures | pictures = true | ~/Pictures, 읽기 전용. | 한 가지를 엶 |
--browser[=hard|soft] | browser_profile = "hard" | 별도의 브라우저 프로필. hard(기본값)는 실행 사이에 아무것도 남기지 않고, soft는 ~/.local/share/ai-jail/browsers 아래에 프로필을 보관합니다. | 한 가지를 엶 |
파일
| 플래그 | 설정 키 | 하는 일 | 위험 |
|---|---|---|---|
--map <PATH|SOURCE:DEST> | ro_maps = [...] | 경로 하나를 읽기 전용으로 추가 마운트합니다. 다른 위치에 마운트하려면 SOURCE:DEST로 씁니다. 여러 번 쓸 수 있습니다. | 한 가지를 엶 |
--rw-map <PATH|SOURCE:DEST> | rw_maps = [...] | 경로 하나를 읽기·쓰기로 추가 마운트합니다. 여러 번 쓸 수 있습니다. | 한 가지를 엶 |
--overlay-map <PATH> | overlay_maps = [...] | 경로를 copy-on-write로 마운트합니다. 에이전트가 쓴 내용은 별도 레이어로 가고 원본은 그대로 남습니다. Linux 전용이며 macOS에서는 읽기 전용 마운트가 됩니다. | 한 가지를 엶 |
--hide-dotdir <NAME> | hide_dotdirs = [...] | .my_secrets처럼 이름을 지정한 점(.) 디렉터리를 절대 마운트하지 않습니다. 여러 번 쓸 수 있습니다. |
끌 수는 있지만 끄면 안 되는 계층
| 플래그 | 설정 키 | 하는 일 | 위험 |
|---|---|---|---|
--no-landlock | no_landlock = true | 파일 규칙을 커널 안에서 한 번 더 적용하는 Landlock을 끕니다. --lockdown에서는 거부됩니다. | 감옥을 약하게 함 |
--no-seccomp | no_seccomp = true | 위험한 시스템 콜을 막는 필터를 끕니다. | 감옥을 약하게 함 |
--no-rlimits | no_rlimits = true | 폭주하는 프로세스를 멈추는 제한을 끕니다. | 감옥을 약하게 함 |
--no-private-home | private_home = false | 새 홈 디렉터리를 포기합니다. 실제 홈이 폭넓게 열립니다. 필요한 경로 하나만 --map으로 여는 편이 낫습니다. | 감옥을 약하게 함 |
각 계층이 하는 일은 작동 방식에서 설명합니다.
가시성
| 플래그 | 설정 키 | 하는 일 | 위험 |
|---|---|---|---|
--audit-log | audit_log = true | 실행할 때마다 ~/.local/share/ai-jail/history.jsonl(디렉터리 0700, 파일 0600)에 레코드 하나를 추가합니다. 시각, 명령, 실제 적용된 기능, 설정 출처, 종료 코드, 소요 시간이 들어갑니다. --allow-host를 쓰면 허용되거나 거부된 연결도 모두 기록하고, --secret을 쓰면 주입도 모두 기록합니다. 각 줄에는 바로 앞 줄의 해시가 들어갑니다. 기본으로 꺼져 있고, 프로젝트 파일은 끌 수만 있고 켤 수는 없습니다. | 한 가지를 엶 |
--audit-show | 없음 | 로그를 읽기 쉬운 요약으로 출력하고 종료합니다. 실행, 필터링된 네트워크 결정, 시크릿 치환이 나옵니다. 체인은 검사하지 않습니다. 출력하면 0, 레코드가 손상되었거나 읽기 오류면 1, 로그가 없으면 2를 반환합니다. 실행 기록에는 명령 인자가 들어갈 수 있으니 인자에 시크릿을 넣지 마세요. | |
--audit-verify | 없음 | 감사 로그의 해시 체인을 따라 검사한 뒤 종료합니다. 온전하면 0, 처음 끊긴 고리에서 1, 로그가 없으면 2를 반환합니다. 2.2 이전에 쓰인 레코드는 legacy로 보고되며 오류가 아닙니다. |
유틸리티
| 플래그 | 하는 일 |
|---|---|
--dry-run | 샌드박스 명령을 출력하고 아무것도 실행하지 않습니다. 설정 파일도 쓰지 않습니다. |
--init | 프로젝트 .ai-jail을 쓰거나 업데이트하고 종료합니다. |
--clean | 이번 실행에서 프로젝트 .ai-jail을 무시합니다. |
--bootstrap | AI 도구 자체의 권한 설정을 생성합니다. |
status | 현재 .ai-jail 설정을 보여 줍니다. |
-v, --verbose | 감옥을 구성하는 동안 마운트를 하나하나 보여 줍니다. |
나머지는 ai-jail --help로 확인하세요. 상태 표시줄, worktree, mise, 터미널 옵션이 있습니다. 툴체인 키는 예전 키들처럼 반전되어 있어서 no_toolchains = true가 끄는 쪽입니다.
프로젝트 안의 시크릿 숨기기
.env 파일은 프로젝트 안에 있고, 프로젝트는 읽고 쓸 수 있습니다. 네트워크가 켜져 있으면 에이전트는 거기서 읽은 것을 무엇이든 밖으로 보낼 수 있습니다. 마스킹하면 에이전트는 그 파일을 읽지 못합니다.
↔ 옆으로 밀어 전체 다이어그램을 확인하세요
--mask <PATH|GLOB>
일치하는 파일을 모두 빈 플레이스홀더로 바꿉니다. 에이전트는 파일이 있다는 것만 알고 내용은 받지 못하므로, 파일 존재 여부만 확인하는 도구는 계속 동작합니다. 마스킹은 샌드박스가 보는 것만 바꿉니다. 에이전트를 대신해 호스트에서 움직이는 도우미, 예를 들어 Docker 데몬이나 MCP 서버는 여전히 실제 파일을 읽습니다.
--deny-path <PATH|GLOB>
일치하는 경로에 접근하면 모두 권한 오류가 납니다.
--mask-except와 --deny-path-except
규칙에서 경로 하나를 예외로 빼냅니다. 보호를 약하게 만들기 때문에 프로젝트 파일에서는 설정할 수 없습니다.
# glob은 따옴표로 감싸야 셸이 확장하지 않고 패턴 그대로 ai-jail에 전달됩니다ai-jail --mask .env --mask '.env.*' --mask '*.pem' --deny-path secrets/ claude ai-jail --mask '.env.*' --mask-except .env.example claude# 프로젝트 파일은 조이는 것이 허용되므로 저장소 안에서도 동작합니다mask = [".env", ".env.*", "*.pem"]deny_paths = ["secrets/"]API 키는 어떤 설정 파일에도 넣지 않기
마스킹은 프로젝트 안의 파일을 다룹니다. 에이전트 자신의 키는 --env NAME으로 셸에서 넘기거나, 나만 읽을 수 있는 파일에서 --env-from-file로 넘기세요. 둘 다 .ai-jail 파일에 기록되지 않고, 프로젝트 파일에서는 설정할 수 없습니다. 필터링된 외부 연결이 켜져 있으면 --secret KEY=host로 실제 값을 샌드박스 밖에 둘 수도 있습니다. 아래 레시피에 예가 있습니다.
# 파일은 내 소유, 권한 0600, 프로젝트 바깥이어야 합니다chmod 600 ~/.secrets/claude.envai-jail --env-from-file ~/.secrets/claude.env claude# 전역 파일 전용. 프로젝트 파일에 설정하면 무시됩니다[commands.claude]env_from_file = ["~/.secrets/claude.env"]내 툴체인도 함께 들어갑니다
빌드에는 컴파일러, 패키지 관리자, 그리고 그 캐시가 필요합니다. Linux에서는 ai-jail이 이것들을 기본으로 들여옵니다. 도구는 읽기 전용으로, 캐시는 감옥 전용 저장소에, 패키지 레지스트리는 필터링 프록시를 통해 닿게 합니다.
↔ 옆으로 밀어 전체 다이어그램을 확인하세요
도구는 읽기 전용
2.4.1부터 ai-jail은 mise로 설치한 것과 그 설정을 읽기 전용으로 매핑합니다. Rust는 ~/.cargo/bin과 ~/.rustup을 같은 방식으로 매핑해서 cargo와 rustc가 잡힙니다. Cargo의 자격 증명과 config.toml은 들어가지 않습니다. mise는 읽기 전용 매핑에 아무것도 설치할 수 없으므로 ai-jail은 안쪽에 MISE_NOT_FOUND_AUTO_INSTALL=false를 설정해서, 없는 도구는 호출마다가 아니라 한 번만 실패하게 합니다.
감옥 전용 캐시
의존성 캐시는 ~/.local/share/ai-jail/cache/ 아래에 두고 세션 사이에 유지됩니다. Cargo의 레지스트리 캐시와 git 캐시가 여기로 갑니다. pip, uv, Go, npm, yarn, pnpm, bun, deno, Maven, Gradle, Coursier, Composer, Crystal, Zig의 기본 캐시도 내 컴퓨터에 그 도구의 디렉터리가 있으면 여기로 갑니다.
레지스트리는 프록시를 통해
툴체인이 켜져 있고 네트워크 플래그를 주지 않으면, 샌드박스는 --allow-host와 같은 프록시를 통해 crates.io, npm, PyPI, Go 프록시, Maven Central, Clojars, Packagist, github.com과 각각의 서브도메인에 닿습니다. 알려진 에이전트 자신의 API 호스트도 같은 길로 통과하며 macOS에서도 그렇습니다. 레지스트리는 Linux 전용입니다.
# Linux의 기본값ai-jail claude # 캐시는 켜고 네트워크는 전혀 없음ai-jail --no-network claude # 아무것도 매핑하지 않고 아무 데도 닿지 않음ai-jail --no-toolchains --no-network claude줄여 나가기
기본값은 일을 끝내는 데 맞춰져 있습니다. 아래 단계마다 하나씩 더 닫히고, --lockdown은 대부분을 한 번에 닫습니다. 각각이 무엇을 막는지는 보안 페이지에 있습니다.
- 기본값: 에이전트의 로그인과 자신의 API 호스트, Linux에서는 내 툴체인, 패키지 레지스트리, 그리고 읽기·쓰기 프로젝트.
--no-network: 완전히 오프라인.--allow-host목록을 함께 주면 샌드박스는 지정한 호스트에만 닿고, 자동 기본값은 붙지 않습니다.--no-agent-state: 로그인 없음. 하네스의 상태는 바깥에 남고 API 키도 복사되지 않습니다.--no-toolchains: 의존성 캐시도 패키지 레지스트리도 없습니다.--mask,--deny-path,--hide-dotdir는 경로를 하나씩 빼고, 좁은--map이나--rw-map은 넓은 허용을 대신합니다. 이들은 샌드박스가 보는 것을 바꿀 뿐입니다. Docker 데몬이나--forward-port뒤의 서비스 같은 호스트 쪽 도우미는 여전히 실제 파일을 읽습니다.--lockdown: 프로젝트는 읽기 전용, 로그인도 툴체인도 레지스트리도 없고, Landlock과 seccomp는 엄격하게. 그래도 VM은 아닙니다.
락다운: 읽기만 하고 고치면 안 되는 코드
--lockdown은 리뷰와 감사에 씁니다. 에이전트는 프로젝트를 읽고 질문에 답할 수 있지만 프로젝트 안의 파일은 바꿀 수 없습니다.
↔ 옆으로 밀어 전체 다이어그램을 확인하세요
달라지는 점
- 프로젝트가 읽기 전용으로 마운트됩니다
- Linux에서는
/tmp에만 쓸 수 있습니다. macOS에서는 쓸 수 있는 곳이 없습니다 - 홈의 점(.) 디렉터리, 추가 매핑, 오버레이가 모두 없습니다
- 환경을 비우고
PATH를 시스템 디렉터리로 고정합니다 - Landlock이 필수입니다. 적용할 수 없으면 실행이 실패합니다
- 프로세스 수, 열린 파일 수, 파일 크기 제한이 더 엄격해집니다
- 다른 플래그를 넘겼더라도 디스플레이, 오디오, GPU, KVM, Docker, SSH 에이전트, mise는 없습니다
- 툴체인 캐시, 레지스트리 외부 연결, 도구 자격 증명은 없습니다
- 에이전트 로그인이 없으므로 하네스는 로그아웃 상태로 시작합니다
ai-jail --lockdown claude레시피
하나를 골라 복사하세요. 무엇이 만들어지는지 보려면 먼저 --dry-run을 붙여 실행합니다.
매일 쓰는 클라우드 에이전트
알려진 에이전트는 로그인된 상태로 시작하고, 필터링 프록시를 통해 자신의 API 호스트에 닿으며, Linux에서는 패키지 레지스트리에도 닿습니다. 작업에 더 필요하면 전역 파일의 allow_hosts에 추가 호스트를 넣거나, network = true로 네트워크 전체를 여세요.
# 더할 것 없음: 로그인과 api.anthropic.com은 기본으로 옵니다ai-jail claude # 작업에 더 필요하면 ~/.ai-jail에 한 번만 (API 호스트와, Linux에서는 레지스트리에 더해짐)[commands.claude]allow_hosts = ["api.example.com"]# 아니면 네트워크 전체를 열기: network = trueai-jail이 모르는 에이전트
ai-jail은 다섯 에이전트의 API 호스트를 알아서 허용합니다. 그 밖의 에이전트는 --allow-host로 호스트를 직접 줘야 합니다. 목록에 그 호스트가 없으면 실행 시 경고에 호스트 이름이 나옵니다.
ai-jail --allow-host api.example.com myagent# 알려진 에이전트는 플래그가 필요 없음: ai-jail이 API 호스트를 알아서 허용로그아웃 상태 실행
에이전트에 자격 증명을 하나도 주지 않으려면 --no-agent-state를 씁니다. 상태 디렉터리와 API 키가 바깥에 남아 로그아웃 상태로 시작하고, 새 홈 안에서 로그인한 것은 실행이 끝나면 사라집니다.
ai-jail --no-agent-state claude전역 파일의 허용 호스트
목록은 그 명령을 실행할 때마다 에이전트 자신의 API 호스트에 더해져 적용됩니다. Linux에서는 github.com과 패키지 레지스트리에 이미 닿으므로 macOS에서만 적습니다. 허용된 호스트는 통째로 신뢰됩니다. 에이전트는 내 자격 증명이 허용하는 것이라면 무엇이든 그 호스트에 요청할 수 있습니다.
[commands.claude]allow_hosts = ["api.example.com"]로컬 MCP 서버나 데이터베이스
--network가 없으면 샌드박스는 자기만의 루프백을 쓰므로, 호스트 127.0.0.1의 서버에는 닿을 수 없습니다. --forward-port는 Linux에서 그 포트 하나만 중계합니다. 전역 파일에서는 forward_ports를 명령 테이블 아래에 두고, 기본 테이블에는 절대 넣지 마세요. 이 플래그는 --network와 함께 쓰면 거부되는데 --browser가 보통 그것을 포함하고, macOS에서도 거부되므로, 기본 테이블에 넣으면 그 실행들이 실패합니다.
ai-jail --forward-port 49374 claude # 또는 ~/.ai-jail에 한 번만, 명령 테이블 아래에[commands.claude]forward_ports = [49374]에이전트가 절대 보지 못하는 키
샌드박스의 ANTHROPIC_API_KEY에는 플레이스홀더가 들어가고, ai-jail의 프록시가 api.anthropic.com으로 가는 요청에만 실제 키를 넣습니다. 클라이언트는 그 호스트에 대해 프록시로 평문 HTTP를 보내야 하는데, http:// 기본 URL이 그 역할을 합니다. 그러면 ai-jail이 요청을 TLS로 실제 호스트까지 나릅니다. HTTPS 터널만 여는 클라이언트는 치환 없이 그대로 동작합니다.
# 키는 0600 파일에만 있고, 샌드박스에는 AIJAIL-PHANTOM-... 만 보입니다ai-jail --allow-host api.anthropic.com \ --env-from-file ~/.secrets/claude.env \ --secret ANTHROPIC_API_KEY=api.anthropic.com \ --env ANTHROPIC_BASE_URL=http://api.anthropic.com claudeSSH로 git push
--ssh는 ~/.ssh를 읽기 전용으로 마운트하고 SSH 에이전트 소켓을 전달합니다. 네트워크는 열지 않으므로 레시피에서는 --network와 함께 씁니다. gh 토큰으로 HTTPS 푸시를 하려면 GitHub CLI 레시피를 보세요.
ai-jail --network --ssh claude감옥 안에서 빌드하고 테스트하기
Linux에서는 더할 것이 없습니다. cargo build, npm install, go get은 프록시를 통해 레지스트리에서 받아 감옥 전용 저장소에 캐시하고, mise로 설치한 것도 읽기 전용으로 따라옵니다. 아무것도 건드리지 않고 아무 데도 닿지 않는 실행이 필요하면 둘 다 끄세요.
# Linux의 기본값: 캐시는 켜고, 레지스트리는 프록시를 통해 닿음ai-jail claude # 아무것도 매핑하지 않고 아무 데도 닿지 않음ai-jail --no-toolchains --no-network claude감옥 안에서 GitHub CLI 쓰기
--github은 gh 설정 디렉터리를 읽기 전용으로 마운트하고 활성 github.com 토큰을 GH_TOKEN으로 전달해서, 키링에 있든 없든 gh와 HTTPS git push가 로그인된 상태가 됩니다. Linux에서는 github.com과 그 서브도메인이 이미 기본 목록에 있어 호스트를 더할 필요가 없고, macOS에서는 --allow-host github.com을 더합니다. 그 뒤로는 감옥 안의 모든 것이 GitHub에서 나처럼 행동할 수 있습니다.
ai-jail --github claude # macOS: 거기서는 github.com이 기본 목록에 없음ai-jail --github --allow-host github.com claude에이전트용 브라우저
--browser만 주면 페이지를 불러올 수도 창을 열 수도 없는 브라우저가 됩니다. Linux에서는 --network와 --display가 함께 필요하고, X11 브라우저에는 --display 대신 --x11이 필요합니다.
# Waylandai-jail --browser=soft --network --display chromium# X11ai-jail --browser=soft --network --x11 chromiumClaude 프로필 분리
실행할 때마다 서로 다른 Claude 디렉터리를 지정해서 업무용 로그인과 개인용 로그인을 따로 관리합니다.
ai-jail --network --claude-dir ~/.claude-work claude위험한 리팩터링을 사본에서 해 보기
오버레이를 쓰면 에이전트가 쓴 내용은 프로젝트의 .ai-jail-overlays 아래 별도 레이어에 남습니다. 끝난 뒤 원본과 비교해서 마음에 드는 것만 가져오면 됩니다. Linux 전용.
ai-jail --network --overlay-map ~/Projects/my-app/src claude예전 설정도 계속 동작합니다
하위 호환성은 프로젝트 규칙입니다. 이 프로젝트는 플래그나 설정 키를 없애지 않습니다. 모르는 키는 무시하고 빠진 키에는 기본값을 쓰므로, 예전 버전용으로 쓴 파일도 그대로 읽힙니다.
오래된 스위치는 true가 끈다는 뜻인 반전된 이름을 그대로 씁니다. no_gpu, no_docker, no_display, no_mise, no_toolchains, no_landlock, no_seccomp, no_rlimits가 그렇습니다. 그래서 --gpu는 no_gpu = false로 저장됩니다. 새로 생긴 스위치는 network = true처럼 평범한 이름을 씁니다. --allow-tcp-port는 지금도 파싱되지만 UDP에 울타리를 칠 수 없어서 여전히 실행을 거부합니다. 오류 메시지는 --allow-host를 가리킵니다.
에이전트를 철창 안에 넣으세요
ai-jail은 바이너리 하나입니다. 데몬도 root 권한도 필요 없습니다. 평소 실행하던 명령 앞에 단어 하나만 붙이면 됩니다.
brew tap akitaonrails/tap && brew install ai-jailai-jail claude