샌드박스에서 코딩 에이전트 실행하기

샌드박스에서 코딩 에이전트 실행하기

코딩 에이전트는 명령을 실행하고, 도구를 설치하고, 승인을 위해 멈추지 않고 Docker를 사용할 수 있는 완전 자율(Full-autonomy) 모드에서 더 빠르게 작업할 수 있어요. 하지만 에이전트에 머신에서 직접 접근 권한을 주면 실수의 영향 범위도 넓어져요. Docker Sandboxes는 에이전트가 실행되는 위치를 바꿔줘요. 이 튜토리얼에서 기존 코딩 에이전트 워크플로를 샌드박스로 옮겨 봐요.

출처: 문서

본문

코딩 에이전트는 명령을 실행하고, 도구를 설치하고, 승인을 위해 멈추지 않고 Docker를 사용할 수 있는 완전 자율 모드에서 더 빠르게 작업할 수 있어요. 에이전트에 머신에서 직접 그런 접근 권한을 주면 실수의 영향 범위도 넓어져요.

Docker Sandboxes는 에이전트가 실행되는 위치를 바꾸지, 에이전트와 작업하는 방식을 바꾸지는 않아요. 에이전트는 자체 운영 체제와 Docker 데몬을 가진 비공개 환경을 받게 돼요. 프로젝트는 호스트에 그대로 남아 있고, 에이전트가 설치하는 도구와 수행하는 시스템 변경은 버릴 수 있는 환경 안에 머물러요.

이 튜토리얼에서 기존 코딩 에이전트 워크플로를 샌드박스로 옮겨요.

시작 전에

호스트에 Docker Desktop이나 Docker Engine이 있을 필요는 없어요.

설치 및 로그인

운영 체제에 맞는 Docker Sandboxes를 설치한 다음 Docker에 로그인해요.

$ sbx login

에이전트 설정 가져오기

이 단계는 선택 사항이에요. 깨끗한 에이전트 설정으로 시작하고 싶다면 건너뛰세요.

호스트에서 에이전트 스킬을 사용한다면 미리 보고 가져올 수 있어요.

$ sbx skills import --dry-run
$ sbx skills import

가져온 스킬은 지원되는 에이전트가 샌드박스 전반에서 사용할 수 있게 돼요. 이 기능은 실험적이에요. 에이전트 스킬 공유에서 지원되는 에이전트와 보안 고려 사항을 확인하세요.

인증 방법 선택

에이전트는 모델 제공자에 접근해야 해요. 구독 로그인은 OAuth를 사용하고, API 키는 호스트에 저장되어 샌드박스 프록시를 통해 에이전트에 제공돼요. 준비 단계를 위해 에이전트와 인증 방법을 선택하세요.

에이전트 Codex Claude Code OpenCode
인증 ChatGPT 구독 / OpenAI API 키 Claude 구독 / Anthropic API 키 / Anthropic API 키 OpenAI API 키 / OpenRouter API 키 / Google API 키

Codex: 비밀 구성이 필요 없어요. Codex를 실행하면 sbx가 샌드박스를 만들기 전에 호스트에서 OpenAI 로그인 흐름을 열어요.

Claude Code: 비밀 구성이 필요 없어요. Claude Code가 샌드박스에서 시작된 후 /login을 입력하고 Claude 계정으로 로그인해요.

OpenAI API 키: 호스트 자격 증명 저장소에 OpenAI API 키를 저장해요. 명령은 키를 표시하지 않고 입력받아요.

$ sbx secret set openai

Anthropic API 키: 호스트 자격 증명 저장소에 Anthropic API 키를 저장해요. 명령은 키를 표시하지 않고 입력받아요.

$ sbx secret set anthropic

Anthropic API 키 (OpenCode): 호스트 자격 증명 저장소에 Anthropic API 키를 저장해요. 명령은 키를 표시하지 않고 입력받아요.

$ sbx secret set anthropic

OpenAI API 키 (OpenCode): 호스트 자격 증명 저장소에 OpenAI API 키를 저장해요. 명령은 키를 표시하지 않고 입력받아요.

$ sbx secret set openai

OpenRouter API 키: 호스트 자격 증명 저장소에 OpenRouter API 키를 저장해요. 명령은 키를 표시하지 않고 입력받아요.

$ sbx secret set openrouter

Google API 키: 호스트 자격 증명 저장소에 Google API 키를 저장해요. 명령은 키를 표시하지 않고 입력받아요.

$ sbx secret set google

이미 지원되는 API 키를 셸에 내보냈다면 별도로 설정하는 대신 가져올 수 있어요.

$ sbx secret import --dry-run
$ sbx secret import

dry run은 sbx가 찾은 내보낸 키를 보여줘요. import 명령은 각 키를 저장하기 전에 확인을 요청해요. dry run에서 아무것도 찾지 못하면 선택기에서 sbx secret set 명령을 사용해요. 자격 증명에서 다른 비밀 소스를, 지원되는 코딩 에이전트에서 에이전트별 인증을 확인하세요.

에이전트 실행

프로젝트를 열고 선호하는 에이전트를 시작해요. 이 예시는 Codex를 사용해요.

$ cd ~/my-project
$ sbx run --name my-project codex

codex를 claude, copilot, cursor, gemini 같은 다른 지원되는 에이전트 식별자로 바꿔요.

샌드박스를 처음 실행하면 sbx가 기본 네트워크 정책을 선택하라고 요청해요. 이 정책은 샌드박스가 도달할 수 있는 외부 서비스를 제어해요. Balanced를 선택해 일반적인 개발 서비스를 허용하고 다른 대상은 기본적으로 차단해요. 이 규칙은 나중에 sbx policy로 변경할 수 있어요.

내장 통합은 완전 자율 모드로 코딩 에이전트를 시작해요. 예를 들어 Codex는 승인을 우회하고, Claude Code는 권한 프롬프트를 건너뛰며, Cursor, Copilot, Gemini는 YOLO 모드를 사용해요. 그런 플래그를 직접 추가할 필요는 없어요.

호스트에서 주던 것과 같은 작업을 에이전트에 줘요. 소스 변경은 작업 트리에서 나타나므로 평소 도구로 검사할 수 있어요.

$ git diff

프로젝트 디렉터리는 샌드박스 경계의 예외예요. 읽기-쓰기로 공유되므로 에이전트가 파일을 수정하거나 삭제할 수 있고, 변경 사항을 즉시 볼 수 있어요. 작업을 버전 관리 아래에 두세요. 에이전트가 설치한 도구와 샌드박스 운영 체제에 대한 변경은 샌드박스 안에 머물러요.

돌아가거나 다시 시작하기

작업이 끝나면 에이전트를 종료해요. 나중에 같은 환경에 다시 연결해요.

$ sbx run --name my-project

깨끗한 환경이 필요하면 샌드박스를 제거해요.

$ sbx rm my-project

샌드박스를 제거하면 환경과 그 안에 설치된 모든 것이 삭제돼요. 프로젝트 디렉터리는 삭제되지 않아요.

무엇이 바뀌었나요

프로젝트, 에이전트, 스킬, 자격 증명, 프롬프팅 워크플로는 그대로 유지했어요. 필수 변경은 sbx run으로 에이전트를 실행한 것뿐이에요. 이 한 줄이 완전 자율 실행을 여러분이 제어하고 버릴 수 있는 환경으로 옮겼어요.

다음 단계

Docker Sandboxes 매뉴얼로 계속 진행해요.

더 알아보기 (Learn more)