Sandbox clients

Sandbox clients (샌드박스 클라이언트)

이 페이지는 샌드박스 작업을 어디에서 실행할지 고를 때 참고하면 돼요. 대부분의 경우 SandboxAgent 정의는 그대로 두고, 샌드박스 클라이언트와 클라이언트별 옵션만 SandboxRunConfig에서 바꿔요.

출처: 문서

본문

Beta 기능: 샌드박스 에이전트는 베타 상태예요. 일반 공급 전에 API, 기본값, 지원되는 기능의 세부 사항이 바뀔 수 있고, 시간이 지나며 더 많은 고급 기능이 추가될 수 있어요.

결정 가이드

목표 시작할 것 이유
macOS 또는 Linux에서 신뢰된 로컬 개발 UnixLocalSandboxClient 추가 설치 없음. 명령이 로컬 호스트 프로세스로 실행됨.
기본 컨테이너 격리 DockerSandboxClient 특정 이미지로 Docker 안에서 작업을 실행함.
호스팅 실행 또는 프로덕션 스타일 격리 호스팅 샌드박스 클라이언트 워크스페이스 경계를 제공자가 관리하는 환경으로 옮김.

Unix-로컬 실행 제한: UnixLocalSandboxClient는 명령을 로컬 호스트 프로세스로 실행해요. Linux에서는 이 백엔드가 OS 수준 격리를 추가하지 않아요. 명령은 호스트 프로세스와 외부 격리가 허용하는 파일·네트워크 리소스에 접근할 수 있어요. 워크스페이스 디렉터리, HOME, 또는 cwd는 그 접근을 제한하지 않아요.

macOS에서는 이 백엔드가 sandbox-exec로 파일시스템 제한을 적용해요. 그 제한은 네트워크 격리나 컨테이너와 같은 경계를 제공하지 않아요.

Unix-로컬은 신뢰된 로컬 개발이나 외부 격리 환경 안에서 사용하세요. 신뢰할 수 없는 명령(신뢰할 수 없는 입력의 영향을 받는 명령 포함)에는 적절히 구성된 Docker나 호스팅 샌드박스를 고르거나 외부 격리를 제공하세요. 선택한 환경의 권한, 마운트, 자격 증명, 네트워크 접근을 워크로드에 맞춰 검토하세요.

로컬 클라이언트

대부분의 사용자는 이 두 샌드박스 클라이언트 중 하나로 시작해요:

클라이언트 설치 언제 고르나 예시
UnixLocalSandboxClient 없음 macOS 또는 Linux에서 신뢰된 로컬 개발, 또는 외부 격리 안에서의 실행. Unix-local 스타터
DockerSandboxClient openai-agents[docker] 컨테이너 격리나, 대상 환경을 로컬에서 재현할 특정 이미지를 원할 때. Docker 스타터

Unix-로컬은 컨테이너 없이 로컬 워크스페이스를 제공해요. 해당 백엔드가 제공하는 격리 경계나 다른 환경과 일치하는 이미지가 필요할 때는 Docker나 호스팅 제공자를 고르세요.

SandboxPathGrant.host_path는 Docker 전용이며 호스트 경로를 컨테이너 안의 다른 POSIX 경로로 매핑해요. Unix-로컬은 동일 경로 승인(same-path grants)만 지원해요. 자세한 내용은 Manifest 경로 승인을 참고하세요.

Unix-로컬 세션의 호스트 환경 상속 제한

기본적으로 UnixLocalSandboxClient는 모든 명령 환경을 완전한 호스트 프로세스 환경에서 시작해요. inherit_host_environment=False로 설정하면 보수적인 호스트 변수 허용 목록만 전달할 수 있어요:

from agents.sandbox.sandboxes.unix_local import UnixLocalSandboxClient

client = UnixLocalSandboxClient(
    inherit_host_environment=False,
    host_environment_allowlist={"PATH", "LANG", "SSL_CERT_FILE"},
)

inherit_host_environment=False이고 host_environment_allowlist가 생략되면 SDK는 PATH, LANG, LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, LC_NUMERIC, LC_TIME, TZ, TERM, TMPDIR, SSL_CERT_FILE, SSL_CERT_DIR, REQUESTS_CA_BUNDLE, NODE_EXTRA_CA_CERTS, UV_PYTHON, NO_COLOR, FORCE_COLOR, CI를 허용해요. 그 기본 허용 목록을 교체하려면 커스텀 컬렉션을 전달하세요. 커스텀 허용 목록은 inherit_host_environment=False를 요구해요.

Manifest.environment의 값은 호스트 필터링 후에 적용되며 상속된 값을 오버라이드해요. Unix-로컬 명령은 항상 워크스페이스 루트를 HOME으로 받아요. 상속 정책은 직렬화된 세션 상태가 아니라 현재 클라이언트에 속하므로, create(...)와 resume(...)는 그 작업을 수행하는 클라이언트의 정책을 적용해요.

이 옵션은 상속된 환경 변수만 필터링해요. OS 수준 격리를 추가하지 않아요. 위의 Unix-로컬 실행 제한이 여전히 적용돼요.

Unix-로컬에서 Docker로 전환하려면 에이전트 정의는 그대로 두고 실행 구성만 바꾸면 돼요:

from docker import from_env as docker_from_env

from agents.run import RunConfig
from agents.sandbox import SandboxRunConfig
from agents.sandbox.sandboxes.docker import DockerSandboxClient, DockerSandboxClientOptions

run_config = RunConfig(
    sandbox=SandboxRunConfig(
        client=DockerSandboxClient(docker_from_env()),
        options=DockerSandboxClientOptions(image="python:3.14-slim"),
    ),
)

컨테이너 격리를 원하거나 샌드박스 이미지가 다른 환경에서 쓰는 이미지와 일치하기를 원할 때 이렇게 하세요. examples/sandbox/docker/docker_runner.py 참고.

Docker 네트워킹 비활성화

Docker 샌드박스가 네트워크에 접근하면 안 될 때 network_mode="none"을 설정하세요:

options = DockerSandboxClientOptions(
    image="python:3.14-slim",
    network_mode="none",
)

지원되는 유일한 명시적 네트워크 모드는 "none"이에요. Docker의 기본 동작을 유지하려면 network_mode를 생략하세요. 네트워크가 비활성화된 샌드박스는 포트를 노출할 수 없으므로, network_mode="none"과 비어 있지 않은 exposed_ports 튜플을 결합하면 옵션 검증에서 실패해요. 이 설정은 샌드박스 세션 상태에 저장되고, SDK가 그 상태를 재개하면서 교체 컨테이너를 만들어야 하면 다시 적용돼요.

Docker 컨테이너 라벨링

애플리케이션이 샌드박스 세션용으로 생성한 Docker 컨테이너를 식별하거나 관리해야 할 때 labels을 설정하세요:

options = DockerSandboxClientOptions(
    image="python:3.14-slim",
    labels={
        "com.example.owner": "agents-sdk",
        "com.example.environment": "development",
    },
)

SDK는 컨테이너를 만들 때 이 키-값 쌍을 Docker에 전달하고 DockerSandboxSessionState에 저장해요. 재개된 세션이 기존 컨테이너에 다시 연결할 때 SDK는 모든 지속된 라벨이 여전히 기대값을 갖는지 검증하고, 라벨이 일치하지 않으면 ValueError를 발생시켜요. SDK가 저장된 상태에서 교체 컨테이너를 만들 때는 지속된 라벨을 다시 적용해요.

마운트와 원격 저장소

마운트 항목(entry)은 노출할 저장소를 설명하고, 마운트 전략(strategy)은 샌드박스 백엔드가 그 저장소를 어떻게 붙이는지 설명해요. 내장 마운트 항목과 일반 전략은 agents.sandbox.entries에서 가져오면 돼요. 호스팅 제공자 전략은 agents.extensions.sandbox 또는 제공자 특정 확장 패키지에서 사용할 수 있어요.

일반적인 마운트 옵션:

  • mount_path: 저장소가 샌드박스 안에 나타나는 위치. 상대 경로는 manifest 루트 아래에서 해석되고, 절대 경로는 그대로 사용돼요.
  • read_only: 기본 True. 샌드박스가 마운트된 저장소에 다시 써야 할 때만 False로 설정하세요.
  • mount_strategy: 필수. 마운트 항목과 샌드박스 백엔드에 모두 맞는 전략을 사용하세요.

마운트는 임시(ephemeral) 워크스페이스 항목으로 취급돼요. 스냅샷과 지속(persistence) 흐름은 마운트된 원격 저장소를 저장된 워크스페이스에 복사하는 대신 마운트된 경로를 분리하거나 건너뛰어요.

일반 로컬/컨테이너 전략:

전략 또는 패턴 언제 쓰나 참고
InContainerMountStrategy(pattern=RcloneMountPattern(...)) 샌드박스 이미지가 rclone을 실행할 수 있음. S3, GCS, R2, Azure Blob, Box 지원. RcloneMountPattern은 fuse 모드 또는 nfs 모드로 실행할 수 있음.
InContainerMountStrategy(pattern=MountpointMountPattern(...)) 이미지에 mount-s3가 있고 Mountpoint 스타일 S3 또는 S3 호환 접근을 원함. S3Mount와 GCSMount 지원.
InContainerMountStrategy(pattern=FuseMountPattern(...)) 이미지에 blobfuse2와 FUSE 지원이 있음. AzureBlobMount 지원.
InContainerMountStrategy(pattern=S3FilesMountPattern(...)) 이미지에 mount.s3files가 있고 기존 S3 Files 마운트 대상에 도달할 수 있음. S3FilesMount 지원.
DockerVolumeMountStrategy(driver=...) Docker가 컨테이너 시작 전에 볼륨-드라이버 기반 마운트를 붙여야 함. Docker 전용. S3, GCS, R2, Azure Blob, Box는 rclone으로 마운트할 수 있고, S3와 GCS는 mountpoint로도 마운트할 수 있음.

지원되는 호스팅 플랫폼

호스팅 환경이 필요할 때도 같은 SandboxAgent 정의를 그대로 가져올 수 있고, SandboxRunConfig에서 샌드박스 클라이언트만 바꾸면 돼요.

이 저장소 체크아웃 대신 게시된 SDK를 사용한다면 일치하는 패키지 extra로 샌드박스 클라이언트 의존성을 설치하세요.

체크인된 확장 예시에 대한 제공자별 설정 참고 사항과 링크는 examples/sandbox/extensions/README.md를 참고하세요.

클라이언트 설치 예시
BlaxelSandboxClient openai-agents[blaxel] Blaxel runner
CloudflareSandboxClient openai-agents[cloudflare] Cloudflare runner
DaytonaSandboxClient openai-agents[daytona] Daytona runner
E2BSandboxClient openai-agents[e2b] E2B runner
ModalSandboxClient openai-agents[modal] Modal runner
RunloopSandboxClient openai-agents[runloop] Runloop runner
VercelSandboxClient openai-agents[vercel] Vercel runner

Modal 샌드박스 크기

ModalSandboxClientOptions.cpu와 ModalSandboxClientOptions.memory로 새 Modal 샌드박스에 리소스를 요청해요. 단일 값은 그 만큼을 요청해요. 두 항목 (request, limit) 튜플은 첫 번째 항목을 요청으로, 두 번째 항목을 한도로 사용해요. 메모리 값은 MiB 단위예요.

from agents.extensions.sandbox import ModalSandboxClientOptions

options = ModalSandboxClientOptions(
    app_name="agents-sandbox",
    cpu=(1.0, 4.0),
    memory=(2048, 8192),
)

cpu, memory 또는 둘 다를 None으로 두면 생략된 각 리소스에 Modal 기본값을 사용해요. 선택된 값은 샌드박스 세션 상태에 보존되므로 교체 샌드박스가 같은 리소스 구성을 사용해요.

호스팅 샌드박스 클라이언트는 제공자별 마운트 전략을 노출해요. 저장소 제공자에 가장 잘 맞는 백엔드와 마운트 전략을 고르세요:

백엔드 마운트 참고
Docker InContainerMountStrategy, DockerVolumeMountStrategy 같은 로컬 전략으로 S3Mount, GCSMount, R2Mount, AzureBlobMount, BoxMount, S3FilesMount 지원.
ModalSandboxClient ModalCloudBucketMountStrategy를 S3Mount, R2Mount, HMAC 인증 GCSMount와 함께 사용해 클라우드 버킷 마운트 지원. 인라인 자격 증명 또는 명명된 Modal Secret 사용 가능.
CloudflareSandboxClient CloudflareBucketMountStrategy를 S3Mount, R2Mount, HMAC 인증 GCSMount와 함께 사용해 버킷 마운트 지원.
BlaxelSandboxClient BlaxelCloudBucketMountStrategy를 S3Mount, R2Mount, GCSMount 항목과 짝지어 클라우드 버킷 마운트 지원. agents.extensions.sandbox.blaxel에서 사용 가능한 BlaxelDriveMount, BlaxelDriveMountStrategy로 지속적 Blaxel Drive도 지원.
DaytonaSandboxClient DaytonaCloudBucketMountStrategy로 rclone을 통해 클라우드 저장소 마운트 지원. S3Mount, GCSMount, R2Mount, AzureBlobMount, BoxMount와 함께 사용.
E2BSandboxClient E2BCloudBucketMountStrategy로 rclone을 통해 클라우드 저장소 마운트 지원. S3Mount, GCSMount, R2Mount, AzureBlobMount, BoxMount와 함께 사용.
RunloopSandboxClient RunloopCloudBucketMountStrategy로 rclone을 통해 클라우드 저장소 마운트 지원. S3Mount, GCSMount, R2Mount, AzureBlobMount, BoxMount와 함께 사용.
VercelSandboxClient VercelCloudBucketMountStrategy를 S3Mount 항목과 짝지어 생성-시점 전용 S3 및 S3 호환 버킷 마운트 지원. 마운트된 세션은 재개할 수 없고, 인라인 자격 증명은 allow_s3_credential_exposure=True가 필요함.

마운트 표는 각 백엔드가 어떤 저장소 타입을 실행할 수 있는지 설명해요. 체크 표시가 모델 제어 샌드박스 안에서 실행되는 마운트 헬퍼의 자격 증명 경계를 우회하는 것은 아니며, 모든 전략이 자격 증명 없이 동작할 수 있다는 뜻도 아니에요. Agents SDK는 선택된 헬퍼가 보호된 권한(authority) 없이 동작할 수 있을 때만 승인(acknowledgement) 없이 인-컨테이너 마운트를 받아들여요. 보호된 권한이 필요한 마운트는 신뢰된 애플리케이션 코드가 정확한 마운트 경로에 대한 노출을 명시적으로 승인하지 않는 한, 샌드박스나 마운트 헬퍼를 시작하기 전에 거부해요.

자격 증명 없는 rclone 마운트는 S3, GCS, R2, Azure Blob으로 제한돼요. 인-컨테이너 Box 마운트는 비대화형 인증 소스와 그 소스와 일치하는 승인이 필요해요. FuseMountPattern은 blobfuse2가 인라인 자격 증명이 구성되지 않았더라도 주변(ambient) Azure 권한을 발견하므로 광범위한 승인이 필요해요. S3FilesMountPattern도 mount.s3files가 주변 IAM 권한을 사용하므로 광범위한 승인이 필요해요. 이 요구사항은 Docker가 백엔드일 때도 적용돼요. 아래 체크 표시는 적용 가능한 권한 경계가 충족된 후 Docker가 마운트를 실행할 수 있음을 나타내요.

"data"라는 마운트 항목에 대해, 구성된 권한과 일치하는 승인이 반환한 복사된 Manifest를 유지하세요:

# 마운트 범위 값(예: 인라인 액세스 키).
manifest = manifest.with_in_container_mount_credential_exposure_acknowledged("data")

# 관리 또는 워크로드 ID, 외부 자격 증명 파일 같은 더 넓은 권한.
manifest = manifest.with_in_container_mount_broad_credential_exposure_acknowledged("data")

승인이 필요한 정확한 마운트 경로를 모두 전달하세요. 두 권한 클래스를 모두 사용하는 마운트는 두 승인 모두 필요해요. 승인은 런타임 전용이며 직렬화되지 않고, 자격 증명 사용을 마운트된 경로에 한정하지 않고 헬퍼가 자격 증명을 받을 수 있게 해줘요. 가능하면 외부 또는 제공자 네이티브 전략을 선호하고, 그렇지 않으면 샌드박스 범위, 단기, 최소 권한 자격 증명을 사용하세요.

VercelSandboxClientOptions(allow_s3_credential_exposure=True)는 인라인 마운트 범위 자격 증명으로 생성-시점 Vercel S3 마운트를 위한 호환성 옵션으로 남아 있어요. 광범위한 자격 증명 권한을 승인하지 않아요.

아래 표는 각 백엔드가 직접 마운트할 수 있는 원격 저장소 항목을 요약해요.

백엔드 AWS S3 Cloudflare R2 GCS Azure Blob Storage Box S3 Files
Docker ✓ ✓ ✓ ✓ ✓ ✓
ModalSandboxClient ✓ ✓ ✓ - - -
CloudflareSandboxClient ✓ ✓ ✓ - - -
BlaxelSandboxClient ✓ ✓ ✓ - - -
DaytonaSandboxClient ✓ ✓ ✓ ✓ ✓ -
E2BSandboxClient ✓ ✓ ✓ ✓ ✓ -
RunloopSandboxClient ✓ ✓ ✓ ✓ ✓ -
VercelSandboxClient ✓ - - - - -

더 많은 실행 가능한 예시는 examples/sandbox/에서 로컬, 코딩, 메모리, handoff, 에이전트 합성 패턴을, examples/sandbox/extensions/에서 호스팅 샌드박스 클라이언트를 살펴보세요.

더 알아보기 (Learn more)