본문으로 건너뛰기
메뉴
나에게 필요할까?에이전트가 내 컴퓨터에서 닿을 수 있는 것작동 방식에이전트와 시스템 사이에 놓이는 계층비교내장 샌드박스, Docker, VM설정작업에 필요한 것만 열기보안위협 모델과 한계설치
설치

설치하고, 안을 둘러보고, 에이전트 실행하기

ai-jail은 프로그램 하나이고 데몬도 root도 필요 없습니다. 설치한 다음 평소 입력하던 명령 앞에 이름을 붙이면 에이전트가 샌드박스 안에서 시작됩니다.

설치

평소 명령줄 도구를 설치하던 방식을 고르세요. 어느 방법을 쓰든 똑같은 ai-jail 프로그램 하나가 설치됩니다.

terminal
brew tap akitaonrails/tap && brew install ai-jail

macOS와 Linux에서 됩니다.

시스템 요구 사항

Linux

bubblewrap을 설치하세요. ai-jail이 샌드박스를 구성할 때 쓰는 작은 프로그램입니다. 대부분의 배포판에 bubblewrap이라는 패키지로 있습니다.

terminal
pacman -S bubblewrapapt install bubblewrapdnf install bubblewrap

macOS

설치할 것이 없습니다. ai-jail은 macOS에 포함된 sandbox-exec를 씁니다. Apple은 이 인터페이스를 deprecated로 표시하고 있습니다.

Windows

지원하지 않습니다. WSL2를 쓰고 그 안에서 Linux 절차를 따르세요.

첫 실행

명령 세 개로 계획을 확인하고, 안을 둘러보고, 에이전트를 실제로 돌립니다. ai-jail은 요청하기 전까지 아무것도 열지 않습니다.

왼쪽에서 오른쪽으로 패널 세 개. 드라이 런에서는 감방이 점선 윤곽뿐이고 에이전트는 바깥에서 기다립니다. 둘러보기에서는 감방이 실선이고 그 안에 터미널과 프로젝트 폴더가 있습니다. 에이전트 실행에서는 에이전트와 프로젝트가 안에 있고 벽에 구멍이 두 개 나 있습니다. 하나는 네트워크용, 하나는 에이전트 로그인용입니다. 홈 폴더는 세 패널 모두에서 바깥에 막혀 있습니다.
홈 디렉터리는 모든 단계에서 바깥에 있습니다. 무언가를 여는 것은 마지막 단계뿐이고, 그것도 클라우드 에이전트에 필요한 두 가지만 엽니다.
  1. 아무것도 실행하지 않고 계획 보기

    프로젝트로 이동해서 드라이 런을 요청합니다. ai-jail은 사용할 샌드박스 명령을 출력하고 종료합니다. 드라이 런은 파일을 쓰지 않습니다.

    드라이 런
    cd ~/Projects/my-appai-jail --dry-run claude
  2. 안을 둘러보기

    감옥 안에서 일반 셸을 시작합니다. 프로젝트는 실제 경로에 그대로 있고 편집할 수 있습니다. 홈 디렉터리는 새로 만든 빈 디렉터리이고 셸에 있던 토큰은 없습니다. 나가려면 exit를 입력합니다.

    감옥 안의 셸
    ai-jail bash
  3. 필요한 두 가지를 주고 에이전트 실행하기

    클라우드 모델과 통신하는 에이전트에는 모델에 닿기 위한 네트워크와 내가 누구인지 증명하는 저장된 로그인이 필요합니다. 둘 다 기본으로 꺼져 있으니 --network--agent-state로 켭니다. 버전 1.22부터는 알려진 에이전트를 둘 중 하나 없이 시작하면 ai-jail이 빠진 플래그 이름을 담은 경고를 출력합니다.

    실제 실행
    ai-jail --network --agent-state claude
  4. 그 에이전트의 기본값으로 만들기

    두 설정을 내 설정 파일인 ~/.ai-jail에 에이전트 이름 아래로 넣습니다. 그 뒤로는 짧은 명령만 입력하면 됩니다. 프로젝트에 생길 수 있는 .ai-jail 파일은 감옥을 더 조일 수만 있습니다. 네트워크나 로그인을 켤 수는 없으므로, 클론한 저장소가 스스로 감옥을 열 수는 없습니다.

    ~/.ai-jail
    [commands.claude]network = trueagent_state = true # from now on, in any project:# ai-jail claude

안에서 보이는 것

프롬프트가 (jail)로 바뀌고 프로젝트는 원래 있던 자리에 있습니다. 훔칠 만한 것은 보이지 않습니다.

Linux에서 실행한 ai-jail bash
$ 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-sandbox

Linux 세션입니다. macOS에는 별도의 파일 트리를 만들 방법이 없어서 같은 경로가 존재하고, 읽으려고 하면 거부됩니다.

감방 안에서 본 모습. 에이전트가 크고 밝은 프로젝트 폴더 옆에 있고, 뒤에는 빈 홈과 시스템 도구가 있습니다. 창살 바깥에는 SSH 키, 클라우드 로그인, 다른 프로젝트, 네트워크가 흐리게 막혀 있습니다.

안에서 보면 내 것 중에 존재하는 것은 프로젝트뿐입니다. --network를 넘기기 전에는 네트워크도 바깥에 있습니다.

시작되지 않을 때

README의 문제 해결 항목에 나오는 경우와, 설정하다가 자주 걸리는 규칙 두 가지입니다.

bwrap: setting up uid map: Permission denied

Ubuntu 24.04 이상과 Debian 13 이상에는 프로그램이 root 없이 사용자 네임스페이스를 만들지 못하게 하는 AppArmor 정책이 들어 있습니다. bubblewrap은 바로 이 방법으로 감옥을 격리합니다. root 없이 동작하는 같은 종류의 도구가 모두 영향을 받습니다. 시스템 전체에서 정책을 완화하려면 이렇게 합니다.

terminal
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을 실행하세요.

/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 설정도 설치된 도구도 없어서 활성화를 건너뜁니다. 내 설정 파일에서 두 디렉터리를 읽기 전용으로 매핑하세요.

~/.ai-jail
[commands.claude]ro_maps = ["~/.config/mise", "~/.local/share/mise"]

시작할 때 Failed to create stream fd가 나옵니다

Ubuntu 데스크톱에서 mise를 준비하는 동안 로그인 스크립트가 내는 메시지입니다. 해롭지 않고 mise도 정상 동작합니다. --no-mise를 주면 mise 준비를 건너뛰고 메시지도 나오지 않습니다.

terminal
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 권한도 필요 없습니다. 평소 실행하던 명령 앞에 단어 하나만 붙이면 됩니다.

terminal
brew tap akitaonrails/tap && brew install ai-jailai-jail claude