gemini-cli : --sandbox

https://lingolandedu.com/ko/english-korean-dictionary/sandbox

sandbox 모드란?

• 보안:
  • run_shell_command나 파일 읽기/수정 등의 승인된 명령을 실행시
  • 호스트 시스템으로부터 해당 작업을 격리하여
  • 안전한 실험 환경을 제공.
• 격리:
  • file system 접근을
  • 현재 project directory 로 제한.
• 활성화 방법:
  • CLI 실행 시 gemini --sandbox 또는 -s 옵션 플래그를 붙여 실행
  • 또는 환경 변수 GEMINI_SANDBOX=true 를 설정.

https://geminicli.com/docs/cli/sandbox/

Sandboxing in the Gemini CLI

---

어원

• sandbox라는 단어는 원래 아이들이 모래를 담아 놓은 상자, 즉 sand box에서 출발한 말임.
• 컴퓨터 분야 등에선 "바깥에 피해를 주지 않고 마음껏 실험해볼 수 있는 공간"이라는 의미로 사용됨.

즉, 실제 시스템 전체를 건드리지 않고, 제한된 공간 안에서만 승인된 command를 실행하고 file을 만지게 하는 실행 구역이라는 뜻임.

 

특정 명령들이
실제로 접근할 수 있는 파일 시스템이나 네트워크 범위를
제한하는 것을 의미!

---

동작

• shell command 나 file modification 같은 potentially dangerous operation을 host system으로부터 격리
• 특히 file system access를 project directory로 제한하는 것이 핵심임.
• 즉, 보통은 현재 project 또는 workspace 안에서는 읽고 쓸 수 있지만, 그 바깥 경로에 대해서는 제한이 걸리게 됨

---

사용법

sandbox 모드로 실행하기

Gemini CLI에서 sandbox를 켜는 방법은 세 가지 우선순위로 정리되어 있음.

1. command flag: -s 또는 --sandbox
2. environment variable: GEMINI_SANDBOX=true|docker|podman|sandbox-exec|runsc|lxc
3. settings.json 의 tools.sandbox 설정

명령어 옵션 플래그로 하는 방법은 다음의 명령어 가능:

gemini -s

 

다음과 같이 환경변수를 지정가능:

export GEMINI_SANDBOX=true
gemini

 

프로젝트 루트의 .gemini/settings.json 파일에 다음과 같이 설정:

{
  "tools": {
    "sandbox": true
  },
  "context": {
    "includeDirectories": [
       "/absolute/path/to/datasets",
       "./local_data",
       "../shared_models"
     ]
  }
}

• tools.sandbox:
  • true: 기본 샌드박스 엔진을 활성화.
  • "docker", "podman", "sandbox-exec" 등 특정 방식을 문자열로 지정 가능.
• context.includeDirectories:
  • 샌드박스 내에서 접근을 허용할 디렉토리 경로들을 배열([]) 형태로 나열.
  • 절대 경로와 상대 경로 모두 지원하지만, 절대 경로를 추천.

---

접근 가능 디렉토리 추가

즉, 세션 시작 시 --include-directories를 사용하여 특정 directory 에 접근을 명시적으로 지정가능함.

즉, sandbox가 무조건 현재 폴더 하나만 보는 구조는 아니고, 명시적으로 허용한 디렉토리까지 범위를 넓힐 수 있음

다음과 같이 명시적으로 각각의 디렉토리를 추가 지정.

gemini --sandbox -I /path/to/data -I /path/to/models -I /path/to/logs

쉼표를 이용한 방법

gemini --sandbox -I "/path/to/data,/path/to/models"

주의할 점은

• 샌드박스 내부에서는 보안을 위해 절대 경로를 사용하는 것이 가장 정확
• .gemini/settings.json 에 context.includeDirectories 에 배열로 기재하면 이후 계속해서 처리됨.

---

--approval-mode (승인모드) 와 차이점.

--approval-mode 에서는 특정 명령들을 실행 시 어떤 수준으로 사용자에게 확인을 구할지를 결정하는 정책임.

 

선택할 수 있는 종류는 다음과 같음:

• 사용자의 승인을 물어볼지(default)
• 파일편집은 자동승인하고 나머진 확인할지 (auto_edit)
• 모든 작업 자동 승인할지 (yolo)

아래와 같이 설정 가능함.

gemini --approval-mode default

gemini --approval-mode auto_edit

gemini -y
gemini --approval-mode yolo

 

 

--sandbox는 "실행이 허용된 작업이라도 어디까지 접근할 수 있는가"를 운영 환경 차원에서 제한하는 격리 장치임.

즉, 승인된 명령이 실제로 접근할 수 있는 파일 시스템이나 네트워크 범위를 제한하는 옵션으로 실행 경계를 정하게 됨.

---

같이 읽으면 좋은 자료들