로컬 Docker Sandboxes 시작하기

로컬 Docker Sandboxes 시작하기 (Get started with local Docker Sandboxes)

첫 샌드박스에서 에이전트를 실행하고, 격리 방식을 보고, 네트워크로 닿는 범위를 통제하는 방법을 알아볼게요.

출처: 문서

본문

이 워크스루는 로컬 샌드박스를 사용해요. 클라우드 자격 증명과 첫 클라우드 세션은 클라우드 샌드박스 시작하기 문서를 보세요.

Docker Sandboxes는 AI 코딩 에이전트를 격리된 microVM 샌드박스에서 실행해요. 각 샌드박스는 고유한 Docker 데몬, 파일시스템, 네트워크를 가져요. 즉 에이전트가 공유한 것 외의 호스트 리소스는 건드리지 않고 컨테이너를 빌드하고, 패키지를 설치하고, 파일을 수정할 수 있어요.

이 페이지는 첫 세션을 안내해요. 샌드박스에서 에이전트를 실행하고, 샌드박스가 어떻게 격리하는지 보고, 네트워크로 닿는 범위를 통제하고, 정리하는 방법까지요.

사전 준비

sbx CLI를 설치하고 Docker에 로그인하세요.

사용할 에이전트의 인증 방법을 구성하세요. 대부분의 에이전트는 모델 제공자의 API 키가 필요해요. 제공자별 지침은 에이전트 페이지에서 확인하세요.

에이전트 인증하기

Claude 구독(Max, Team, Enterprise)이 있는 Claude Code는 추가 설정 없이 바로 쓸 수 있어요. 샌드박스 안에서 /login 명령으로 OAuth 로그인을 하면 돼요. 세션 토큰은 호스트에 남고 샌드박스 안에는 저장되지 않아요.

API 키로 인증하고 싶다면, sbx secret set으로 키를 저장하는 방법을 Credentials 문서에서 보세요.

에이전트가 풀 리퀘스트를 만들거나 저장소와 상호작용하기 위해 GitHub에 접근하도록 하려면:

$ sbx secret set github --command 'gh auth token'

첫 샌드박스 실행하기

프로젝트 디렉터리를 고르고 sbx run으로 에이전트를 실행하세요:

$ cd ~/my-project
$ sbx run --name my-sandbox claude

첫 실행에서 CLI가 기본 네트워크 프리셋을 고르라고 물어요:

Initialize the global network policy for your sandboxes:

 Applies to all sandboxes, current and future — change it later with
 "sbx policy allow/deny/rm". Kits, including built-in agent kits, may
 also add per-sandbox rules.

 1. Open — All network traffic allowed, no restrictions.
 ❯ 2. Balanced — Default deny, with common dev sites allowed.
 3. Locked Down — All network traffic blocked unless you allow it.

 Use ↑/↓ or 1–3 to navigate, Enter to confirm, Esc to cancel.

Balanced는 좋은 출발점이에요. 일반적인 개발 서비스로의 트래픽은 허용하면서 나머지는 차단해요. 개별 규칙은 나중에 조정할 수 있어요. 각 옵션의 전체 설명은 Local policy 문서를 보세요.

claude를 사용할 에이전트로 바꾸세요. 전체 목록은 Agents 문서에서 보세요.

첫 실행은 에이전트 이미지를 가져오느라 조금 더 걸려요. 이후 실행은 캐시된 이미지를 재사용해서 몇 초 안에 시작돼요.

이렇게 하면 샌드박스 안에서 실행 중인 에이전트에 연결돼요. 실제 작업을 줘 보세요. 기능을 추가하거나, 의존성을 설치하거나, 프로젝트를 빌드·실행해 달라고 해 보세요. 에이전트는 자체 Docker 데몬을 가진 완전한 Linux 환경을 갖고 있으므로, 작업하는 동안 스스로 패키지를 설치하고 이미지를 빌드하고 컨테이너를 시작할 수 있어요.

에이전트가 닿을 수 있는 것을 확인하기

다른 터미널에서 샌드박스를 나열하세요:

$ sbx ls
SANDBOX     AGENT   STATUS    PORTS   WORKSPACE
my-sandbox  claude  running           ~/my-project

각 행은 샌드박스의 이름, 실행 중인 에이전트, 상태, 공개된 포트, 그리고 샌드박스에 공유된 호스트 디렉터리인 워크스페이스를 보여줘요. 그 워크스페이스가 에이전트가 볼 수 있는 머신의 유일한 부분이에요.

워크스페이스 경로를 넘기지 않고 프로젝트 디렉터리에서 sbx run을 실행하면 현재 디렉터리가 read-write로 마운트돼요. 에이전트와 호스트는 같은 파일을 봐요. 에이전트가 프로젝트에 하는 편집은 쓰는 즉시 작업 트리에 나타나고, 커밋하기 전에 일반 Git diff처럼 검토할 수 있어요.

나머지는 전부 microVM 안에서 실행되어 호스트와 격리돼요:

에이전트는 고유한 파일시스템, Docker 데몬, 네트워크를 가져요.
설치한 패키지, 가져온 이미지, 시작한 컨테이너는 샌드박스 안에 남아요. 호스트 시스템은 건드리지 않고, 샌드박스를 제거하면 함께 버려져요.

에이전트가 작업 트리를 아예 건드리지 않기를 원한다면(예: 한 저장소에서 여러 에이전트를 실행할 때), 대신 개인 복제본을 주는 clone mode를 쓰세요.

에이전트가 닿을 수 있는 범위 통제하기

격리는 파일시스템만의 문제가 아니에요. 샌드박스가 네트워크로 닿을 수 있는 범위도 통제해요. 샌드박스 시작 전에 기본 정책을 골랐고, 언제든 검사하거나 조정할 수 있어요.

어떤 규칙이 적용되는지 확인하세요:

$ sbx policy ls

특정 호스트를 허용하려면:

$ sbx policy allow network registry.npmjs.org

Locked Down에서는 모델 제공자 API조차 명시적으로 허용하지 않으면 차단돼요. Balanced에서는 일반적인 개발 서비스가 기본으로 허용돼요. 전체 규칙과 커스터마이즈 방법은 local policy 문서를 보세요.

정리하기

에이전트가 종료된 후에도 샌드박스는 유지되므로, 중지했다가 나중에 이어서 할 수 있어요:

$ sbx stop my-sandbox

설치한 패키지, Docker 이미지, 설정 변경은 재시작을 거쳐도 보존돼요. 샌드박스 사용이 끝나면 제거해서 디스크 공간을 되찾으세요:

$ sbx rm my-sandbox

샌드박스를 제거하면 그 안의 모든 것이 삭제돼요. 설치한 패키지, Docker 이미지, clone mode를 썼다면 샌드박스 안의 Git 클론까지요. 호스트 작업 트리의 파일은 영향받지 않아요.

다음 단계

에이전트를 실행하고, 샌드박스가 어떻게 격리하는지 보고, 네트워크 접근을 통제해 봤어요. 여기서 몇 갈래로 나아갈 수 있어요.

sbx를 인자 없이 실행하면 대화형 대시보드가 열려요. 모든 샌드박스의 실시간 보기에서 에이전트에 연결하고, 셸을 열고, 네트워크 규칙을 한곳에서 관리할 수 있어요.

그다음 이것들을 살펴보세요:

Usage guide — 기본 명령, 재연결, 워크스페이스, 포트 공개.
Workflow patterns — Git 전략, 로컬 서비스, CI, 인증된 도구.
Sandbox environment files — sbxenv.yaml으로 반복 가능한 로컬 샌드박스 구성을 선언하고 공유해요.
Customize with kits — 에이전트, 도구, 네트워크 규칙을 단일 플래그로 실행하는 재사용 가능한 정의로 패키징해요.
Agents — 지원되는 에이전트의 전체 목록과 각각의 구성 방법.
Governance — 팀 전체에서 네트워크·파일시스템·MCP 정책을 중앙 관리해요.

더 알아보기 (Learn more)

클라우드 샌드박스 시작하기, Credentials, Local policy, Agents, Usage guide, Workflow patterns, Sandbox environment files, Customize with kits, Governance 문서를 참고하세요.