Gemini 에이전트

이 페이지는 로컬 샌드박스를 다뤄요. 클라우드 동작과 제한은 Compare local and cloud sandboxes를 참고해요. 이 가이드는 샌드박스 환경에서 Google Gemini의 인증, 구성, 사용을 다뤄요.

출처: 문서

본문

공식 문서: Gemini CLI

빠른 시작 (Quick start)

샌드박스를 만들고 프로젝트 디렉터리에 대해 Gemini를 실행해요.

$ sbx run gemini ~/my-project

sbx run의 작업 공간 기본값은 현재 디렉터리예요.

$ cd ~/my-project
$ sbx run gemini

마운트 없는(mountless) 샌드박스를 만들려면 작업 공간 경로 없이 sbx create를 사용한 뒤, 이름으로 attach해요.

인증 (Authentication)

Gemini는 Google API 키 또는 Gemini 접근 권한이 있는 Google 계정이 필요해요.

API 키: 저장된 시크릿으로 키를 저장해요.

$ sbx secret set google

Google 계정: API 키가 설정되지 않으면 Gemini는 시작할 때 인터랙티브하게 로그인하도록 프롬프트를 띄워요. 인터랙티브 인증은 샌드박스 범위로 한정되며, 샌드박스를 제거하고 다시 만들면 유지되지 않아요.

구성 (Configuration)

샌드박스는 호스트의 사용자 수준 구성(예: ~/.gemini)을 가져오지 않아요. 작업 디렉터리의 프로젝트 수준 구성만 샌드박스 안에서 사용할 수 있어요. 해결 방법은 "Why doesn't the sandbox use my user-level agent configuration?"을 참고해요.

샌드박스는 Gemini의 내장 샌드박스 도구를 비활성화해요(샌드박스 자체가 격리를 제공하므로).

기본 시작 명령

인자 없이 실행하면 샌드박스는 다음을 실행해요.

gemini --yolo

첫 인자가 플래그(-로 시작)일 때 -- 뒤의 인자는 기본 플래그 뒤에 추가되므로 --yolo가 보존돼요.

$ sbx run --name <sandbox-name> -- -p "explain this"  # runs gemini --yolo -p "explain this"

첫 인자가 서브커맨드나 프롬프트 같은 단어일 때는 기본값을 대신해요.

베이스 이미지

템플릿: docker/sandbox-templates:gemini

Gemini는 내장 OAuth 흐름을 비활성화하도록 구성되어 있어요. 인증은 API 키로 프록시를 통해 관리돼요. 도구를 미리 설치하거나 환경을 커스터마이즈하려면 Customize를 참고해요.

Gemini 에이전트