샌드박스 모드

샌드박스 모드 (Sandbox Mode)

sbx 가 관리하는 격리된 샌드박스 VM에서 에이전트를 실행해요.

출처: 문서

본문

개요 (Overview)

샌드박스 모드는 Docker의 샌드박스 제품인 sbx 와의 Docker Agent 통합이에요. sbx 는 런타임, CLI, VM을 제공하고, Docker Agent는 그 내장 에이전트 중 하나예요. --sandbox 플래그는 sbx 에 VM을 만들거나 재사용하라고 요청하고 그 안에서 Docker Agent를 실행해요.

모든 셸, 파일시스템, 프로세스 활동이 그 VM 안에서 일어나므로, 잘못 동작하는 에이전트가 마운트된 작업 디렉터리 밖의 파일에 닿거나 오래 지속되는 호스트 상태에 도달할 수 없어요. Docker Agent는 샌드박스를 구현하거나 원시 docker run 컨테이너를 시작하지 않아요; 설치된 sbx CLI를 오케스트레이션해요.

Note 요구 사항 (Requirements) --sandbox 를 사용하기 전에 sbx CLI를 설치하고 구성하세요.

사용법 (Usage)

docker agent run 명령에서 --sandbox 플래그로 샌드박스 모드를 활성화해요:

docker agent run --sandbox agent.yaml

Docker Agent는 sbx 에 샌드박스 VM을 실행하거나 재사용하라고 요청하고, 현재 작업 디렉터리를 마운트하고, 그 안에서 에이전트를 실행해요.

플래그 (Flags)

Flag	Default	Description
--sandbox	false	샌드박스 모드 활성화
--template	docker/docker-agent-sbx-templates:latest	샌드박스 템플릿으로 사용할 OCI 이미지. sbx create -t 로 전달. Sandbox templates 참고.
--no-kit	false	auto-kit 비활성화 — 스킬이나 프롬프트 파일을 샌드박스에 스테이징하지 않음

# Use a custom template image
docker agent run --sandbox --template myorg/custom-agent-template:latest agent.yaml

# Run without staging skills / prompt files into the sandbox
docker agent run --sandbox --no-kit agent.yaml

특정 에이전트를 항상 샌드박스로 (Always sandbox a given agent)

alias에 --sandbox 를 추가하면 그 alias가 호출될 때마다 샌드박스 경로가 자동으로 택해져요:

docker agent alias add safe-coder myorg/coder --sandbox
docker agent run safe-coder

명령줄의 명시적 --sandbox=false 는 여전히 이겨요, 그래서 alias를 건드리지 않고 단일 실행에 대해 샌드박스를 거부할 수 있어요.

에이전트 구성에 기본값 굽기 (Bake the default into the agent config)

에이전트 작성자는 YAML 자체에서 샌드박스 기본값을 선언할 수 있어요. 그러면 에이전트의 어떤 호출자든 --sandbox 를 전달해야 한다는 걸 알거나 기억하지 않아도 자동으로 샌드박스 경로를 얻어요:

# agent.yaml
runtime:
  sandbox: true

agents:
  root:
    model: openai/gpt-4o
    description: A helpful assistant
    instruction: You are a helpful assistant.
    toolsets:
      - type: shell

docker agent run agent.yaml # runs in a sandbox automatically

규칙은 alias와 같아요: CLI의 명시적 --sandbox=false 가 구성 기본값을 재정의하므로, YAML을 편집하지 않고 호스트에서 에이전트를 디버깅할 수 있어요.

네트워크 허용 목록 선언 (Declare a network allowlist)

러너는 이미 도구 설치 호스트와 모델 게이트웨이를 자동으로 열지만, 그 해석기들이 추론할 수 없는 엔드포인트에 통신하는 에이전트(커스텀 MCP 서버, 타사 API, aqua 해석기가 다루지 않는 레지스트리)는 첫 접촉 시 샌드박스 프록시에서 여전히 403을 볼 거예요. runtime.network_allowlist 에 그 호스트들을 선언하면 추론된 집합과 합집합되어, 에이전트가 첫 요청에 도달할 수 있어요:

# agent.yaml
runtime:
  sandbox: true
  network_allowlist:
    - api.example.com
    - registry.npmjs.org

각 항목은 선택적 :port 접미사가 있는 호스트 이름이에요. 쉼표와 공백은 거부되어 단일 항목이 여러 규칙을 정책 엔진으로 밀반입하지 못하게 해요. 러너는 실행 전에 결과 허용 목록을 출력하므로, 실행이 열어놓는 호스트가 정확히 어떤 것인지 감사할 수 있어요.

자신만의 허용 목록 유지 (Persist your own allowlist)

에이전트를 가로질러 계속 필요로 하는 호스트(회사 프록시, 자체 호스팅 레지스트리, ...)에 대해 docker agent sandbox allow 가 항목을 ~/.config/cagent/config.yaml 에 한 번 쓰고, 이후 모든 --sandbox 실행에서 추론된 집합 및 에이전트 선언 집합과 합집합해요:

# I just got a `Blocked by network policy` 403 on api.example.com.
docker agent sandbox allow api.example.com

# See what's currently persisted.
docker agent sandbox list

# Drop a host you no longer need.
docker agent sandbox deny api.example.com

kit의 toolset별 호스트 해석기가 실패하면(시작 요약의 ! using fallback host set 라인), 러너가 이 명령을 가리키는 힌트를 출력하므로, 더 넓은 보수적 폴백 호스트 집합에 의존하는 대신 누락된 호스트를 한 줄의 영구 수정으로 바꿀 수 있어요.

샌드박스 템플릿 (Sandbox templates)

샌드박스 템플릿은 샌드박스 VM이 부팅되는 OCI 이미지예요. 그것이 기본 OS와 VM 안에서 사용 가능한 도구(이미 docker-agent 바이너리가 있는지 포함)를 결정해요. --template(또는 sbx create 의 -t) 로 선택해요.

기본 템플릿 (The default template)

--template 은 기본적으로 docker/docker-agent-sbx-templates:latest 로, 이 저장소의 자체 CI가 가장 최근의 v* 릴리스에서 빌드해 게시하는 템플릿이에요 — 무엇을 담고 있고 다른 사용 가능한 태그가 무엇인지는 The repo-published templates 참고.

저장소 게시 템플릿 (The repo-published templates)

이 저장소의 자체 CI는 Dockerfile의 template 스테이지에서 docker/docker-agent-sbx-templates 로 샌드박스 템플릿을 빌드해 게시해요:

Tag	Built from	Use it when
:latest	가장 최근 v* 릴리스	릴리스 안정성을 가진 최신 Docker Agent 템플릿을 원할 때 (기본값)
:edge	현재 main 브랜치	오늘의 main 빌드를 원하고 낮은 안정성을 감수할 수 있을 때

(각 릴리스는 일치하는 버전 고정 태그도 게시해요, 예: docker/docker-agent-sbx-templates:1.2.3.)

:latest 가 기본이에요. 미출시 수정이나 기능이 구체적으로 필요하고 가끔 깨져도 감수할 수 있을 때만 :edge 를 사용하세요. 재현 가능한 실행을 위해서는 태그 대신 다이제스트로 고정하세요, 예: docker/docker-agent-sbx-templates@sha256:....

--template 으로 하나를 선택해요:

$ docker agent run --sandbox --template docker/docker-agent-sbx-templates:edge agent.yaml

또는 Docker Agent를 거치지 않고 sbx CLI가 직접 가리키게 해요:

$ sbx create -t docker/docker-agent-sbx-templates:latest

Tip sbx 문서는 Docker Agent와 독립적으로 샌드박스 CLI와 런타임을 다뤄요.

무엇을 포함하는지 (What they contain)

이 저장소의 Dockerfile의 template 스테이지는 docker/sandbox-templates:shell-docker 위에 레이어링하고 다음을 추가해요:

• docker-agent 바이너리.
• VM 안에서 대화형 디버깅용 vim 과 tmux.
• ~/.docker/cli-plugins/docker-mcp 에 설치된 docker-mcp Docker CLI 플러그인.

이미지는 라벨 com.docker.sandboxes.flavor=docker-agent-docker 를 담아 샌드박스 도구가 식별할 수 있게 해요.

예제 (Example)

# agent.yaml
agents:
  root:
    model: openai/gpt-4o
    description: Agent with sandboxed shell
    instruction: You are a helpful assistant.
    toolsets:
      - type: shell

docker agent run --sandbox agent.yaml

동작 원리 (How It Works)

• --sandbox 는 Docker Agent에게 설치된 sbx CLI를 호출하라고 지시해요.
• --template 으로 전달된 이미지에서 새 샌드박스 VM이 생성돼요.
• 현재 작업 디렉터리가 VM에 마운트되고, 에이전트 바이너리가 복사돼요.
• auto-kit이 호스트에서 스테이징되어 읽기 전용으로 VM에 바인드 마운트되므로, 에이전트가 샌드박스 안에서 스킬과 프롬프트 파일을 봐요.
• 기본-deny 네트워크 프록시가 구성된 모델 게이트웨이와 에이전트의 MCP/LSP toolset에 대해 auto-installer가 필요로 하는 패키지 호스트용으로 열려요.
• 모든 도구(셸, 파일시스템, 백그라운드 작업 등)가 VM 안에서 실행돼요.
• 세션이 끝나면 Docker Agent는 종료하지만 샌드박스 VM을 중지하거나 제거하지 않아요; VM과 kit 모두 보관되어 같은 워크스페이스의 이후 실행이 재사용할 수 있어요. 새 샌드박스는 마운트 집합이 변경될 때만 만들어져요.

기본 템플릿이 포함하는 것 (What the default template includes)

기본 템플릿(docker/docker-agent-sbx-templates:latest)은 이 저장소의 자체 Dockerfile에서 빌드돼요 — docker-mcp CLI 플러그인을 포함한 정확한 내용은 What they contain 참고.

자동 키트 (Auto-Kit)

샌드박스 VM은 자체 파일시스템과 $HOME 을 가져요 — 호스트의 ~/.agents/skills/, ~/.claude/skills/, 프로젝트 레벨 .agents/skills/, AGENTS.md 나 CLAUDE.md 같은 프롬프트 파일 중 어느 것도 안에 보이지 않아요. 그 간극을 메우기 위해 Docker Agent는 자동으로 kit 를 빌드해요: 샌드박스가 시작되기 전에 호스트에서 스테이징되어 같은 경로에서 읽기 전용으로 VM에 바인드 마운트되는 자체 포함 디렉터리예요.

kit은 --sandbox 가 에이전트 참조와 함께 사용될 때마다 빌드돼요. --no-kit 로 거부할 수 있어요.

무엇이 스테이징되는가 (What gets staged)

명령줄에서 참조된 에이전트에 대해 kit은 다음을 수집해요:

• 로컬 스킬 — 호스트에서 발견된 모든 SKILL.md(전역 ~/.codex/skills/, ~/.claude/skills/, ~/.agents/skills/, 더하기 프로젝트 .claude/skills/, .github/skills/, .agents/skills/)가 <kit>/skills/<skill-name>/ 아래로 복사돼요. 샌드박스 안 스킬 로더는 (존재하지 않는) 호스트 $HOME 대신 kit에서 읽어요.
• 프롬프트 파일 — 에이전트의 add_prompt_files(AGENTS.md, CLAUDE.md, …)로 참조된 모든 파일이 수집돼요. 이미 작업 디렉터리 아래에 있는 파일은 그대로 두고(라이브 워크스페이스 마운트가 표면화함); 밖에 있는 파일(예: $HOME 의 AGENTS.md)은 <kit>/prompt_files/ 아래로 복사돼요.
• 매니페스트 — <kit>/manifest.json 이 무엇이 스테이징됐는지 기록해요. 온디스크 사본은 정화되어 샌드박스 안에서 호스트 파일시스템을 매핑하는 데 사용될 수 없게 해요.

실행 전에 Docker Agent는 스테이징된 것의 요약을 출력하므로, 에이전트가 샌드박스 안에서 정확히 어떤 스킬과 프롬프트 파일에 접근할 수 있는지 볼 수 있어요.

시크릿 지우기 (Secret redaction)

kit으로 복사되는 모든 텍스트 파일은 portcullis 를 통과하며, 스테이징된 사본에서 감지 패턴(API 키, 토큰 등)과 일치하는 시크릿을 지워요. kit의 출력 요약은 하나 이상의 시크릿이 대체될 때마다 파일을 (redacted) 로 표시해요. 감지는 best-effort예요 — portcullis는 일반적인 시크릿 형식을 인식하지만 새롭거나 난독화된 토큰은 빠져나갈 수 있으므로, kit은 처음부터 시크릿을 스킬 소스에 두지 않게 하는 것의 대체가 아니에요.

네트워크 허용 목록 (Network allowlist)

샌드박스 템플릿은 기본-deny 네트워크 프록시를 탑재하는데, 주요 모델 제공자는 허용하지만 *.docker.com 과 auto-installer가 닿는 모든 패키지 레지스트리/소스 호스트는 차단해요. 에이전트가 command 와 installable version 이 있는 MCP 또는 LSP toolset을 선언하면, kit 빌드가 각 toolset의 패키지를 aqua 레지스트리에 대해 해석하고 샌드박스 안 auto-installer가 필요로 할 최소 호스트 집합(go_install 패키지용 Go 모듈 프록시 + 툴체인 부트스트랩, github_release 패키지용 GitHub 릴리스 호스트 등)을 계산해요. 그 호스트들, models.dev(샌드박스 안 에이전트가 컨텍스트 한도, 가격, 능력 같은 모델 메타데이터를 해석할 수 있게 필요한데, 없으면 첫 카탈로그 조회가 403 Blocked by network policy 에러로 실패함), 그리고 구성된 --models-gateway 가 샌드박스 프록시에 허용 목록으로 추가돼요. toolset별 레지스트리 조회가 실패하면 보수적 폴백 합집합이 사용되어 실행이 여전히 성공할 수 있게 하고, 영향받는 toolset은 출력 요약에 표면화돼요.

캐싱 (Caching)

kit은 Docker Agent 캐시 디렉터리(macOS에서는 ~/Library/Caches/cagent/sandbox-kits/<hash>) 아래에 에이전트 참조의 콘텐츠 해시로 키가 매겨 저장돼요. 실행 간에 같은 에이전트를 재사용하면 같은 kit 디렉터리를 제자리에서 재사용해요; 디스크 사용량은 실행한 서로 다른 에이전트의 수로 제한돼요. kit은 의도적으로 실행 간에 디스크에 유지되는데, 재사용된 샌드박스 VM이 kit의 바인드 마운트 경로에 대한 하드 참조를 들고 있기 때문이에요 — 삭제하면 샌드박스를 시작할 수 없게 돼요.

kit 비활성화 (Disabling the kit)

--no-kit 을 전달해 kit 빌드를 완전히 건너뛰어요. 그러면 에이전트가 샌드박스 안에서 보이는 호스트 측 스킬이나 외부 프롬프트 파일 없이 실행되고, 네트워크 허용 목록은 템플릿 기본값으로 폴백돼요. 샌드박스 자체를 디버깅하거나 호스트 스킬에 의존하지 않는 에이전트에 유용해요.

docker agent run --sandbox --no-kit agent.yaml

Warning 한계 (Limitations)

• 샌드박스는 같은 워크스페이스에서 실행 간에 재사용돼요; 필요한 마운트 집합이 변경되면(예: 새 kit 스테이징), 이전 샌드박스가 제거되고 새 것이 생성돼요.
• 작업 디렉터리, 에이전트 구성 디렉터리, (스테이징될 때) kit 디렉터리만 마운트돼요; 다른 호스트 파일은 에이전트에게 보이지 않아요.
• 네트워크 이그레스는 샌드박스 백엔드의 기본-deny 정책과 위에서 설명한 실행별 허용 목록으로 제약돼요.

더 알아보기 (Learn more)