로컬 Docker 샌드박스에서 Gemini CLI를 실행하는 방법 (안전하고 쉬운 방법!)

터미널에서 작업하는 것을 즐기고 일상적인 번거로움을 자동화하는 것을 좋아하는 사람이라면, AI 에이전트(AI agent)를 워크플로우에 도입하는 것은 마치 초능력을 얻는 것처럼 느껴질 것입니다. 하지만 솔직해집시다. 로컬 머신에서 AI 에이전트를 실행할 생각을 하는 순간, 머릿속에서 작은 경고음이 울립니다.

이 AI가 정확히 무엇에 접근할 수 있는 거지? 내 비밀 파일을 읽고 있는 건가?

오늘 우리는 그 문제를 해결할 것입니다. Docker를 사용하여 완전히 격리되고 안전한 샌드박스(sandbox) 환경에서 로컬 시스템에 Gemini CLI를 실행하는 방법을 보여드리겠습니다.

왜 샌드박스인가?

어떤 AI 에이전트를 실행하든, 보안과 접근 제어(access control)가 최우선 순위가 되어야 합니다.

1. 완전한 격리 (Total Isolation): AI가 당신의 파일 시스템 전체를 뒤지는 것을 원하지 않을 것입니다. 숨기고 싶은 기밀 파일이 있을 수도 있습니다.
2. 토큰 절약 (Saving Tokens): AI가 너무 많은 파일에 접근할 수 있으면, 불필요한 데이터를 컨텍스트 윈도우(context window)로 가져와 소중한 토큰(그리고 당신의 돈!)을 낭비할 수 있습니다.
3. 제어 (Control): 샌드박스에서는 당신이 주도권을 갖습니다. 에이전트가 볼 수 있는 단 하나의 폴더를 정확히 결정할 수 있으며, 읽기 전용(read-only) 또는 읽기-쓰기(read-write) 권한을 부여할 수 있습니다.
4. 다중 인스턴스 (Multiple Instances): Docker를 사용하기 때문에 여러 개의 독립적인 컨테이너를 실행할 수 있습니다. 컨테이너들은 서로를 알지 못하므로, 작업이 서로 섞이지 않게 하면서 동시에 서로 다른 작업을 실행할 수 있습니다.

게다가 자동 수락 모드(auto-accept mode), 플랜 모드(plan mode), 그리고 fast 또는 pro 모델 간의 전환과 같은 Gemini CLI의 모든 멋진 기능들을 그대로 사용할 수 있습니다!

사전 요구 사항

시작하기 전에, 필요한 것들이 있는지 확인해 봅시다:

• Gemini API Key: Google AI Studio에서 가져올 수 있습니다.
• Docker: 로컬 시스템에 설치되어 실행 중이어야 합니다.
• 이 글 읽기: 솔직히 말해서, 이것이 현재 당신에게 가장 중요한 핵심입니다. 끝까지 함께하세요!

1단계: Docker가 깨어 있는지 확인하기

가장 먼저, Docker가 실제로 실행 중인지 확인합시다. Mac(또는 Linux)을 사용 중이라면, 터미널을 열고 다음을 입력하세요:

docker ps

작은 표가 나타난다면(비어 있더라도), Docker 데몬이 정상적으로 실행 중인 것입니다. 만약 에러가 발생한다면, Docker Desktop을 실행하세요!

2단계: Dockerfile

Google의 공식 문서에서는 Node.js를 통해 Gemini CLI를 설치할 것을 권장합니다. 따라서 우리는 샌드박스 (sandbox)를 구축하기 위해 경량 Node 이미지를 사용할 것입니다.

파일에 빠르게 접근하려면 GITHUB를 참조하세요.

gemini-sdbx.Dockerfile이라는 이름의 파일을 생성하고 다음 내용을 붙여넣으세요:

FROM node:slim@sha256:aa27a5fbf5acb298116a38133794f080406c6f8dfe52e2e2836bb55dc7cae8f0 AS base
FROM base AS installation

...

잠깐, 왜 sandboxuser를 만들었나요? 아주 좋은 질문입니다! Docker 컨테이너는 완전히 격리된 네임스페이스 (namespace)에서 실행되며 호스트 커널 (host kernel)과 직접 상호작용하지 않지만, 모든 것을 root (sudo) 사용자로 실행하는 것은 여전히 좋지 않은 습관입니다. 전용 sandboxuser를 생성함으로써 추가적인 안심 계층을 더할 수 있습니다. 우리는 Gemini가 자신만의 작은 상자 안에서조차 루트 권한 (root privileges)을 갖는 것을 원하지 않습니다!

3단계: Docker Compose 파일

다음으로, 방금 구축한 컨테이너를 실제로 구동하기 위해 Compose 파일을 사용할 것입니다.

docker-compose.yml이라는 이름의 파일을 생성하고 다음 내용을 붙여넣으세요:

services:
  gemini-sandbox:
    build:
...

4단계: 환경 변수 설정

위의 compose 파일에서 볼 수 있듯이, 마법을 구현하기 위해서는 두 가지 환경 변수 (environment variables)가 필요합니다:

1. GEMINI_API_KEY: 귀하의 비밀 키
2. LOCAL_DIRECTORY_PATH: Gemini가 접근하기를 원하는 컴퓨터 내 특정 폴더의 경로

export GEMINI_API_KEY="sk-asdfghjk"
export LOCAL_DIRECTORY_PATH="/this/is/my/directory"

우리는 이 특정 폴더를 컨테이너 내부의 /workspace에 마운트 (mounting)하기 때문에, Gemini는 오직 해당 폴더 안에서만 작업할 수 있습니다. Gemini는 귀하의 컴퓨터에 다른 무엇이 있는지 전혀 알 수 없습니다.

준비, 시작!

파일을 저장하고 환경 변수 설정을 마쳤다면, 다음을 실행하기만 하면 됩니다:

docker compose run gemini-sandbox

짠! 이제 터미널에서 바로 당신을 도와줄 준비가 된, 완전히 기능적이고 완벽하게 격리된 AI 어시스턴트 (AI assistant)를 갖게 되었습니다. 보안 걱정도 없고, 토큰 낭비도 없이 그저 순조롭게 진행될 뿐입니다.

즐거운 자동화 되세요!