샌드박스 워크로드용 기본 이미지

샌드박스 워크로드용 기본 이미지 (Base images for sandbox workloads)

워크로드에 운영체제와 시작 도구 집합을 주는 기본 이미지 선택 방법을 알아볼게요.

출처: 문서

본문

기본 이미지(base image)는 워크로드에 운영체제와 시작 도구 집합을 제공해요. Docker는 에이전트가 이미 설치된 이미지를 제공해요. 다른 Linux 이미지에서 시작해 직접 준비할 수도 있어요. 워크로드의 Dockerfile에서 기본 이미지를 고르세요. 키트 디스크립터로 네트워크 접근, 자격 증명, 기타 샌드박스 동작을 구성해요. 키트 세트(set)는 그 워크로드의 기본 이미지를 사용해요.

대화형으로 구성한 환경을 저장해 재사용하려면 Save a sandbox as a template 문서를 보세요.

Docker 제공 이미지 (Docker-provided images)

Docker의 샌드박스 템플릿은 docker/sandbox-templates:<variant>로 게시돼요. Ubuntu에 기반하고 sudo 접근이 있는 non-root agent 사용자로 실행돼요. 대부분 변형은 Git, Docker CLI, 그리고 Node.js·Python·Go·Java 같은 흔한 개발 도구를 포함해요.

v3 워크로드에서 이미지 사용하기 (Use an image in a v3 workload)

워크로드의 Dockerfile을 FROM으로 시작하고, 필요한 도구와 설정을 추가해요. 시스템 패키지는 root로 설치하고, 에이전트의 홈 디렉터리에 도구를 설치하기 전에 agent로 되돌아가요. 그 설치 프로그램을 root로 실행하면 파일이 /root/ 아래에 들어가 에이전트가 쓸 수 없어요.

기본 이미지가 제공하는 것 (What the base image provides)

FROM은 이미지의 파일과 설정을 상속해요. 이미지가 게시된 키트라 해도 그 능력(capabilities)은 넘어오지 않아요. 네트워크 접근, 자격 증명, 저장소, 훅을 자신의 디스크립터에 선언하세요. 기존 키트의 능력을 유지하면서 도구를 추가하려면 키트 세트를 구성하세요.

디스크립터가 키트 형식 버전을 결정해요. v3 디스크립터는 기본 이미지로 Docker 템플릿 이미지를 써도 v3 키트를 만들어요. Version compatibility 문서를 보세요.

기존 에이전트 이미지 패키징하기 (Package an existing agent image)

이 예시는 Docker의 OpenCode 이미지를 v3 워크로드로 패키징해요. 이미지에 에이전트가 이미 설치되어 있으므로, 실행 명령을 고르고 무엇이 필요한지 설명하기만 하면 돼요. 결과 키트를 직접 실행하거나 추가 도구와 함께 세트에 포함할 수 있어요.

두 파일이 있는 디렉터리를 만들어요:

opencode-workload/
├── opencode-workload.yaml
└── opencode-workload.dockerfile

Dockerfile은 기본 이미지를 선택하고 Docker Sandboxes가 agent 사용자로 OpenCode를 실행하게 해요:

opencode-workload/opencode-workload.dockerfile

FROM docker/sandbox-templates:opencode
USER agent
ENTRYPOINT ["opencode"]
CMD []

템플릿은 OpenCode, Python, uv, agent 사용자를 제공해요. 워크로드로 식별하고 OpenCode가 필요한 것 — 네트워크 접근, Anthropic API 키, 그 환경에 대한 지침 — 을 선언하는 YAML 디스크립터를 만들어요:

opencode-workload/opencode-workload.yaml

# syntax=docker/sandbox-kit:3
schemaVersion: "3"
kind: workload

capabilities:
  - type: com.docker.sandbox/sbx@1
  - type: com.docker.sandbox/network-policy@1
    config:
      runtime:
        allow:
          - api.anthropic.com
          - opencode.ai
          - models.dev
          - registry.npmjs.org
          - pypi.org
          - files.pythonhosted.org
  - type: com.docker.sandbox/credential@1
    config:
      service: anthropic
      phase: runtime
      apiKey:
        name: ANTHROPIC_API_KEY
        proxyManaged: true
        inject:
          - domain: api.anthropic.com
            header: x-api-key
            format: "%s"
  - type: com.docker.sandbox/agent-context@1
    config:
      filename: AGENTS.md
      content: |
        OpenCode runs as the agent user. Python and uv are available.
        Use the project's environment and dependency configuration.

자격 증명 항목은 서비스를 이름 짓고 API 요청을 어떻게 인증할지 설명해요. 실제 API 키는 호스트에 저장해요.

sbx는 샌드박스를 만들 때 이 디렉터리를 빌드할 수 있어요. 결과는 키트의 파일과 디스크립터가 담긴 컨테이너 이미지로, 다른 사람이 쓰도록 레지스트리에 게시할 수도 있어요.

자신만의 Linux 이미지 사용하기 (Use your own Linux image)

다른 운영체제나 패키지 집합이 필요하면 원하는 Linux 이미지에서 시작해요. Docker Sandboxes가 기대하는 도구와 사용자 계정을 추가한 뒤 에이전트를 설치해야 해요.

다음 요구사항들이 그 이미지를 준비하는 데 도움을 줘요. 단계별 예시는 Build an agent workload를 따라가 보세요.

기본 이미지 요구사항 (Base image requirements)

이미지를 다음으로 준비해요:

• 도구: 소스 저장소에 접근하고 HTTPS 요청을 하기 위한 curl, git, 신뢰할 수 있는 CA 인증서 포함
• 셸: 설정 명령과 에이전트 실행을 위한 실행 가능한 /bin/sh와 /bin/bash 파일 제공
• 사용자 계정: UID 1000과 홈 디렉터리 /home/agent를 가진 non-root agent 계정 생성. /etc/passwd에 계정을 추가하고 이미지에서 USER agent를 설정
• 실행 명령: 샌드박스가 실행할 에이전트나 셸로 ENTRYPOINT 또는 CMD 설정

Docker Sandboxes는 명령을 실행하고 파일을 쓸 때 사용자 ID, 그룹 ID, 홈 디렉터리를 결정하기 위해 /etc/passwd의 계정 항목을 사용해요.

마운트된 워크스페이스가 있는 샌드박스에서는 WORKDIR이 마운트 위치를 고르지 않아요. 마운트된 워크스페이스가 없는 샌드박스에서는 sbx가 이미지의 절대 WORKDIR을 작업 디렉터리로 사용해요. 이미지가 쓸 수 있는 절대 경로를 지정하지 않으면 sbx는 /home/agent/workspace로 대체해요.

에이전트 실행 계약 선언하기 (Declare the agent launch contract)

sbx는 이미지의 실행 명령을 사용해 에이전트를 별도 프로세스로 시작하며 샌드박스를 계속 실행시켜요. com.docker.sandbox/sbx@1 능력은 여러분의 워크로드가 이렇게 실행될 준비가 되었다고 선언해요:

capabilities:
  - type: com.docker.sandbox/sbx@1

이 능력은 config를 받지 않고 추가 권한을 요청하지 않아요. 게시 전에 이미지가 셸·사용자 계정 요구사항을 충족하는지 업스트림 적합성(conformance) 테스트가 확인하게 해줘요.

호스트는 비대화형 Bash로 에이전트를 실행해요. 실행 시 영구 환경 설정을 로드하려면 BASH_ENV를 절대 경로로 설정하고 그 파일을 이미지에 포함하세요. Bash는 로그인 프로필이나 .bashrc 대신 이 파일을 읽어요.

전체 계약은 업스트림 sbx@1 정의를 보세요.

더 알아보기 (Learn more)

관련 문서와 심화 내용은 원문을 참고해 주세요.