핵심 요약
- gemini -s를 실행하면 셸 명령, 파일 수정, 네트워크 요청을 포함한 세션 전체가 격리된 샌드박스 안에서 실행됩니다. 푸터에 샌드박스 표시가 나타나므로 활성 여부를 바로 확인할 수 있습니다.
- 활성화 방법은 세 가지이며 우선순위대로 적용됩니다: -s / --sandbox 플래그, GEMINI_SANDBOX 환경 변수, settings.json tools 객체의 "sandbox": true.
- 백엔드는 OS별로 선택합니다: macOS는 Seatbelt 프로파일(기본 permissive-open), Linux는 가장 강한 gVisor runsc, 그 외 플랫폼은 Docker 또는 Podman 컨테이너.
- YOLO 모드(--yolo)는 모든 권한 확인을 건너뜁니다 - 샌드박스와 함께 쓰세요. v0.61.0(2026년 9월 23일)에서 샌드박스 파일시스템 경계가 강화되고 런타임 상태가 분리되었습니다.
Gemini CLI Essentials – Full Course (sandboxing chapter)
채널: freeCodeCamp.org3:49:40
Gemini CLI: Everything You Need To Know (Full Tutorial)
채널: lustoykov42:54
Sandboxing in Gemini CLI — official documentation
공식 문서: google-gemini/gemini-cli (GitHub)
스크린샷은 freeCodeCamp 코스의 샌드박스 챕터에서 가져왔습니다. 플래그명·설정·프로파일 이름은 공식 샌드박스 문서와 v0.61.0 릴리스 노트로 이중 확인했습니다.
스크린샷 출처: freeCodeCamp.org 및 lustoykov - 출처를 밝혀 시각 참고자료로 사용했으며, 모든 단계 텍스트는 본 사이트의 자작입니다.
단계별로 Gemini CLI 샌드박스 만들기
첫 샌드박스 세션 실행하기
- 1
샌드박스가 실제로 무엇을 격리하는지 알기
샌드박스는 AI 에이전트를 위험하게 만드는 작업 - 셸 명령, 파일 쓰기, 네트워크 접근 - 을 호스트 시스템으로부터 분리합니다. Gemini CLI v0.61.0(2026년 9월 23일)은 샌드박스 파일시스템 경계를 강화하고 런타임 상태를 분리해, 빌드 파일과 신뢰할 수 없는 플래그를 통한 간접 프롬프트 인젝션 경로를 막았습니다.
샌드박스의 실체: 플랫폼마다 선택되는 OS 수준 격리 라이브러리.140:00에 보기 - 2
플래그로 바로 샌드박스 실행
가장 빠른 방법은 커맨드 플래그입니다: gemini -s(전체 형태 --sandbox)를 실행하세요. 첫 실행은 샌드박스 이미지를 받아오느라 시간이 걸릴 수 있습니다. 일회성 작업은 프롬프트와 함께: gemini -s -p "analyze the code structure".
플래그 켜고, 푸터 표시 확인 - 2초짜리 점검.140:50에 보기 - 3
세 가지 활성화 방법과 우선순위 이해하기
Gemini CLI는 샌드박스 설정을 우선순위로 해석합니다: 먼저 -s / --sandbox 커맨드 플래그, 다음 GEMINI_SANDBOX 환경 변수(true, docker, podman, sandbox-exec, runsc, lxc), 마지막으로 settings.json tools 객체의 "sandbox" 항목.
공식 문서가 세 가지 방법을 우선순위와 함께 나열합니다.145:45에 보기 - 4
푸터에서 샌드박스 활성화 확인
CLI가 뜨면 상태 푸터에 샌드박스 버전 표시가 모델 선택기 바로 옆에 나타납니다. 표시가 없으면 샌드박스가 꺼진 것 - 활성화됐다고 믿었던 플래그나 설정을 다시 확인하세요.
실제 샌드박스 세션: 표시가 Auto (Gemini 3) 바로 옆에 있습니다.146:40에 보기
OS에 맞는 백엔드 고르기
- 5
macOS는 내장 Seatbelt 활용
macOS는 컨테이너가 필요 없습니다. Gemini CLI가 Seatbelt(sandbox-exec)로 프로세스를 감쌉니다. 기본 프로파일 permissive-open은 쓰기를 프로젝트 디렉터리로 제한하고 읽기와 네트워크는 열어둡니다. 더 엄격하게는 SEATBELT_PROFILE 환경 변수로 permissive-proxied, restrictive-open, restrictive-proxied, strict-open, strict-proxied를 고르세요.
- 6
Linux / WSL2는 gVisor runsc
Google의 gVisor(runsc 런타임)는 가장 강한 격리를 제공합니다: 컨테이너가 모든 시스템 콜을 가로채는 사용자 공간 커널 위에서 동작합니다. GEMINI_SANDBOX=runsc 또는 "sandbox": "runsc"로 명시적으로 선택(자동 감지 안 됨)하면 Gemini CLI가 docker run --runtime=runsc를 대신 실행해 줍니다.
문서는 runsc를 가장 강한 Linux 전용 백엔드로 소개합니다.141:20에 보기 - 7
runsc 런타임 설치
Ubuntu(네이티브든 WSL2든)에서는 apt 한 줄이면 됩니다: sudo apt get install runsc. Gemini CLI는 runsc를 독립 도구가 아니라 Docker 런타임으로 구동하므로 Docker도 미리 설치해 실행 상태여야 합니다.
WSL2 Ubuntu 터미널에 설치 명령 입력.143:35에 보기 - 8
설치 결과 확인
apt는 runsc를 Ubuntu 보안 업데이트 저장소에서 바로 풀어줍니다. 별도 PPA는 불필요. 이 단계를 건너뛰면 이후 Linux의 gemini -s가 실패하거나 조용히 컨테이너 백엔드로 폴백하므로, 첫 샌드박스 실행 전에 패키지를 확인하세요.
Ubuntu 24.04에서 runsc 언팩이 끝난 장면.144:15에 보기 - 9
컨테이너 선호? 어떤 OS든 Docker 또는 Podman
컨테이너 기반 샌드박스는 Docker나 Podman이 도는 곳이라면 어디서든 동작하며, 시작 전 두 가지 모두 설치·실행 상태여야 합니다 - docker를 한 번 실행해 응답을 확인하세요. 샌드박스는 기본으로 ghcr.io/google/gemini-cli:latest 이미지를 쓰고, 작업 디렉터리를 호스트와 완전히 같은 절대 경로로 컨테이너에 마운트합니다.
docker를 한 번 실행해 엔진 응답 확인.145:30에 보기
YOLO 모드 안심하고 돌리기
- 10
샌드박스와 YOLO 모드 결합
gemini --yolo(--approval-mode=yolo의 약칭)는 모든 권한 확인을 위험할 정도로 건너뜁니다 - 자율 실행에 필요한 동작이자, 샌드박스가 존재하는 이유입니다. 샌드박스 플래그와 함께 YOLO 세션을 실행하면 건너뛴 확인들도 격리 환경 안에 머뭅니다.
한 장으로 보는 YOLO 모드: 중단 없음, 모든 권한 즉시 통과.148:20에 보기 - 11
자율 실행이 샌드박스 안에 있었는지 검증
YOLO 세션 동안 푸터에는 파란 YOLO Mode 배지가 표시됩니다 - 확인이 건너뛰어지고 있다는 신호입니다. 실행 후 /stats 상호작용 요약이 어떤 도구가 동작했는지 보여주고, 샌드박스 표시는 작업이 상자 안에서 이뤄졌다는 증거로 남습니다.
자율 세션 종료 후 푸터의 YOLO Mode 배지.147:40에 보기
커스텀 샌드박스 이미지와 컨테이너 플래그
기본 컨테이너 이미지로 일반 코딩은 충분합니다. 프로젝트 고유의 툴체인이 필요하거나 컨테이너 환경이 발목을 잡을 때는 조정 지점이 네 가지 있습니다.
- 1이미지 지정: GEMINI_SANDBOX_IMAGE를 설정하거나 settings.json에서 객체 형태 "sandbox": "command": "docker", "image": "..." (a JSON object)를 사용하세요. bash가 들어 있는 Docker / Podman 이미지라면 무엇이든 됩니다.
- 2직접 빌드: 프로젝트 루트에 .gemini/sandbox.Dockerfile을 두고 BUILD_SANDBOX=1로 실행하면 Gemini CLI가 자동 빌드합니다. 자동 빌드는 소스에서 실행할 때만 가능하며, npm 설치는 사전 빌드 이미지를 참조해야 합니다.
- 3컨테이너 명령 조정: SANDBOX_FLAGS로 docker/podman에 플래그를 추가합니다 - 예컨대 export SANDBOX_FLAGS="--security-opt label=disable"은 Podman에서 SELinux가 볼륨 마운트를 거부할 때의 표준적인 해결책입니다.
- 4Linux 파일 소유권 수정: 샌드박스는 사용자 권한을 자동 매핑하지만, 생성 파일의 소유자가 어긋날 때는 SANDBOX_SET_UID_GID=true로 호스트 UID/GID를 강제하세요.
Gemini CLI 자체를 컨테이너 안에서 구동하면서 샌드박스를 더하고 싶다면: /var/run/docker.sock을 마운트해 CLI가 호스트 데몬으로 형제 컨테이너를 띄울 수 있게 하고, 워크스페이스 경로를 호스트 절대 경로와 정확히 일치시키세요. 볼륨 마운트를 해석하는 쪽은 컨테이너가 아니라 호스트 데몬입니다.
문제 해결: 오류, 파일 접근, 비활성화
샌드박스 문제의 대부분은 다섯 가지 유형으로 환원됩니다. 무엇보다 먼저 디버그 출력으로 재현하세요: DEBUG=1 gemini -s -p "your prompt".
- 1"Operation not permitted" - 명령이 샌드박스 밖 접근을 요구합니다. 더 관대한 프로파일(macOS: SEATBELT_PROFILE)로 바꾸거나 필요한 마운트를 추가하세요.
- 2샌드박스 안에 명령이 없음 - 커스텀 이미지에 도구를 구워 넣거나 sandbox.bashrc로 설치하세요. BUILD_SANDBOX 자동 빌드는 소스 체크아웃 전용입니다.
- 3네트워크 실패 - 현재 프로파일이 네트워크를 허용하는지 확인하고 프록시 설정을 점검하세요. -proxied 프로파일은 샌드박스 프록시로 트래픽을 보냅니다.
- 4Linux에서 생성 파일 소유자가 다름 - SANDBOX_SET_UID_GID를 전환하세요(true는 호스트 UID/GID 강제, false는 매핑 비활성화).
- 5Windows 파일이 Low 무결성 표시로 남음 - 네이티브 샌드박스는 icacls로 쓰기 가능 경로를 표시합니다. icacls "C:\path\to\dir" /setintegritylevel Medium으로 되돌리세요.
샌드박스가 무엇에 접근 가능한지 보려면 CLI에게 물어보세요: gemini -s -p "run shell command: env | grep SANDBOX"가 샌드박스 환경 변수를, mount | grep workspace가 마운트를 보여줍니다. 파일은 내보내기가 필요 없습니다 - 컨테이너 샌드박스는 프로젝트를 같은 절대 경로로 마운트하므로 편집이 곧바로 폴더에 반영됩니다. 비활성화는: -s 플래그 제거, GEMINI_SANDBOX unset, settings.json의 "sandbox" 항목 삭제. 도구 수준 샌드박스는 별도 스위치 "security": "toolSandboxing": false(재시작 필요)입니다.