설치하고, 안을 둘러보고, 에이전트 실행하기
ai-jail은 프로그램 하나이고 데몬도 root도 필요 없습니다. 설치한 다음 평소 입력하던 명령 앞에 이름을 붙이면 에이전트가 샌드박스 안에서 시작됩니다.
설치
평소 명령줄 도구를 설치하던 방식을 고르세요. 어느 방법을 쓰든 똑같은 ai-jail 프로그램 하나가 설치됩니다.
brew tap akitaonrails/tap && brew install ai-jailmacOS와 Linux에서 됩니다.
yay -S ai-jail-binyay -S ai-jail첫 번째 패키지는 Linux x86_64용으로 미리 빌드된 바이너리입니다. 두 번째는 소스에서 빌드합니다.
cargo install --locked ai-jailRust 툴체인이 필요합니다. --locked를 주면 릴리스를 테스트할 때 쓴 의존성 버전으로 빌드합니다.
nix run github:akitaonrails/ai-jail -- claudenix profile install github:akitaonrails/ai-jail첫 줄은 아무것도 설치하지 않고 에이전트를 실행합니다. 둘째 줄은 내 사용자 계정에 설치합니다. flake는 ai-jail이 자체 포함된 bubblewrap을 쓰도록 연결합니다.
ai-jail-linux-x86_64.tar.gzai-jail-macos-aarch64.tar.gz압축 파일은 서명되어 있고 체크섬이 함께 올라와 있습니다. 하나를 풀어서 ai-jail을 PATH에 있는 위치에 두세요. 서명 확인 방법은 보안 페이지에 있습니다.
cargo build --release --lockedinstall -Dm755 target/release/ai-jail ~/.local/bin/ai-jail필요한 Rust 버전은 1.97.1입니다.
시스템 요구 사항
Linux
bubblewrap을 설치하세요. ai-jail이 샌드박스를 구성할 때 쓰는 작은 프로그램입니다. 대부분의 배포판에 bubblewrap이라는 패키지로 있습니다.
pacman -S bubblewrapapt install bubblewrapdnf install bubblewrapmacOS
설치할 것이 없습니다. ai-jail은 macOS에 포함된 sandbox-exec를 씁니다. Apple은 이 인터페이스를 deprecated로 표시하고 있습니다.
Windows
지원하지 않습니다. WSL2를 쓰고 그 안에서 Linux 절차를 따르세요.
첫 실행
명령 세 개로 계획을 확인하고, 안을 둘러보고, 에이전트를 실제로 돌립니다. ai-jail은 요청하기 전까지 아무것도 열지 않습니다.

아무것도 실행하지 않고 계획 보기
프로젝트로 이동해서 드라이 런을 요청합니다. ai-jail은 사용할 샌드박스 명령을 출력하고 종료합니다. 드라이 런은 파일을 쓰지 않습니다.
cd ~/Projects/my-appai-jail --dry-run claude안을 둘러보기
감옥 안에서 일반 셸을 시작합니다. 프로젝트는 실제 경로에 그대로 있고 편집할 수 있습니다. 홈 디렉터리는 새로 만든 빈 디렉터리이고 셸에 있던 토큰은 없습니다. 나가려면
exit를 입력합니다.ai-jail bash필요한 두 가지를 주고 에이전트 실행하기
클라우드 모델과 통신하는 에이전트에는 모델에 닿기 위한 네트워크와 내가 누구인지 증명하는 저장된 로그인이 필요합니다. 둘 다 기본으로 꺼져 있으니
--network와--agent-state로 켭니다. 버전 1.22부터는 알려진 에이전트를 둘 중 하나 없이 시작하면 ai-jail이 빠진 플래그 이름을 담은 경고를 출력합니다.ai-jail --network --agent-state claude그 에이전트의 기본값으로 만들기
두 설정을 내 설정 파일인
~/.ai-jail에 에이전트 이름 아래로 넣습니다. 그 뒤로는 짧은 명령만 입력하면 됩니다. 프로젝트에 생길 수 있는.ai-jail파일은 감옥을 더 조일 수만 있습니다. 네트워크나 로그인을 켤 수는 없으므로, 클론한 저장소가 스스로 감옥을 열 수는 없습니다.[commands.claude]network = trueagent_state = true # from now on, in any project:# ai-jail claude
안에서 보이는 것
프롬프트가 (jail)로 바뀌고 프로젝트는 원래 있던 자리에 있습니다. 훔칠 만한 것은 보이지 않습니다.
$ ai-jail bash# 프로젝트는 실제 경로에 있습니다(jail) ~/Projects/my-app $ pwd/home/you/Projects/my-app# 셸에 export한 토큰은 따라오지 않았습니다(jail) ~/Projects/my-app $ echo $GITHUB_TOKEN # 이 홈에는 키가 없습니다(jail) ~/Projects/my-app $ cat ~/.ssh/id_ed25519cat: /home/you/.ssh/id_ed25519: No such file or directory# 감옥에는 전용 호스트 이름이 있습니다(jail) ~/Projects/my-app $ hostnameai-sandboxLinux 세션입니다. macOS에는 별도의 파일 트리를 만들 방법이 없어서 같은 경로가 존재하고, 읽으려고 하면 거부됩니다.

안에서 보면 내 것 중에 존재하는 것은 프로젝트뿐입니다. --network를 넘기기 전에는 네트워크도 바깥에 있습니다.
시작되지 않을 때
README의 문제 해결 항목에 나오는 경우와, 설정하다가 자주 걸리는 규칙 두 가지입니다.
bwrap: setting up uid map: Permission denied
Ubuntu 24.04 이상과 Debian 13 이상에는 프로그램이 root 없이 사용자 네임스페이스를 만들지 못하게 하는 AppArmor 정책이 들어 있습니다. bubblewrap은 바로 이 방법으로 감옥을 격리합니다. root 없이 동작하는 같은 종류의 도구가 모두 영향을 받습니다. 시스템 전체에서 정책을 완화하려면 이렇게 합니다.
echo 'kernel.apparmor_restrict_unprivileged_userns=0' \ | sudo tee /etc/sysctl.d/60-userns.confsudo sysctl --system정책은 그대로 두고 bwrap만 예외로 둘 수도 있습니다. 아래 내용을 /etc/apparmor.d/bwrap으로 저장한 뒤 sudo apparmor_parser -r /etc/apparmor.d/bwrap을 실행하세요.
abi <abi/4.0>,include <tunables/global>profile bwrap /usr/bin/bwrap flags=(unconfined) { userns,}BWRAP_BIN이 거부됩니다
BWRAP_BIN으로 ai-jail이 쓸 bubblewrap을 지정할 수 있습니다. ai-jail은 그 경로가 root 소유이고 다른 사용자가 쓸 수 없는 프로그램이거나, 표준 다중 사용자 /nix/store 안의 프로그램일 때만 받아들입니다. 내 홈에 있는 사본은 거부합니다. 그 파일을 바꿔치기할 수 있는 사람이 감옥을 통제하게 되기 때문입니다.
안에서 mise 도구가 보이지 않습니다
ai-jail은 mise를 찾으면 활성화합니다. 하지만 새 홈에는 mise 설정도 설치된 도구도 없어서 활성화를 건너뜁니다. 내 설정 파일에서 두 디렉터리를 읽기 전용으로 매핑하세요.
[commands.claude]ro_maps = ["~/.config/mise", "~/.local/share/mise"]시작할 때 Failed to create stream fd가 나옵니다
Ubuntu 데스크톱에서 mise를 준비하는 동안 로그인 스크립트가 내는 메시지입니다. 해롭지 않고 mise도 정상 동작합니다. --no-mise를 주면 mise 준비를 건너뛰고 메시지도 나오지 않습니다.
ai-jail --no-mise claude에이전트별 안내
ai-jail은 에이전트마다 로그인을 어디에 보관하는지 알고 있습니다. --agent-state는 시작하는 에이전트의 폴더만, 그것도 존재할 때만 마운트합니다.
| 실행하는 명령 | --agent-state가 마운트하는 것 | 알아 둘 점 |
|---|---|---|
ai-jail claude | ~/.claude~/.claude.json | 두 번째 Claude 프로필을 쓰려면 --claude-dir로 해당 디렉터리를 지정하세요. |
ai-jail codex | ~/.codex | 창 크기를 바꾸면 ai-jail이 Codex에 다시 그리기 키를 보내 화면을 새로 그리게 합니다. |
ai-jail opencode | ~/.config/opencode~/.local/share/opencode | |
ai-jail gemini | ~/.gemini | |
ai-jail ai-memory run claude | 실행된 에이전트의 폴더 | ai-jail은 ai-memory가 실행하는 에이전트를 인식해서 그 에이전트의 설정을 적용하고, 두 프로그램을 한 감옥 안에서 실행합니다. |
crush, grok, jcode, pi, aider, soulforge, omp, 그리고 kimi 명령도 똑같이 동작합니다. 그 밖의 명령도 실행됩니다. 같은 감옥을 받고 로그인 폴더는 받지 않습니다.
에이전트를 철창 안에 넣으세요
ai-jail은 바이너리 하나입니다. 데몬도 root 권한도 필요 없습니다. 평소 실행하던 명령 앞에 단어 하나만 붙이면 됩니다.
brew tap akitaonrails/tap && brew install ai-jailai-jail claude