샌드박스 클라이언트
이 페이지를 사용해 샌드박스 작업을 어디에서 실행할지 선택하세요. 대부분의 경우 SandboxAgent 정의는 그대로 유지되고, 샌드박스 클라이언트와 클라이언트별 옵션만 SandboxRunConfig에서 변경됩니다
베타 기능
샌드박스 에이전트는 베타입니다. 정식 출시 전에 API 세부 사항, 기본값, 지원 기능이 변경될 수 있으며, 시간이 지나면서 더 고급 기능이 추가될 예정입니다
선택 가이드
| 목표 | 시작 항목 | 이유 |
|---|---|---|
| macOS 또는 Linux에서 가장 빠른 로컬 반복 | UnixLocalSandboxClient |
추가 설치 없이 간단한 로컬 파일시스템 개발이 가능합니다 |
| 기본 컨테이너 격리 | DockerSandboxClient |
특정 이미지로 Docker 내부에서 작업을 실행합니다 |
| 호스티드 실행 또는 프로덕션 수준 격리 | 호스티드 샌드박스 클라이언트 | 작업 공간 경계를 제공업체가 관리하는 환경으로 이동합니다 |
로컬 클라이언트
대부분의 사용자에게는 다음 두 샌드박스 클라이언트 중 하나로 시작하는 것을 권장합니다
| 클라이언트 | 설치 | 선택 시점 | 예시 |
|---|---|---|---|
UnixLocalSandboxClient |
없음 | macOS 또는 Linux에서 가장 빠른 로컬 반복이 필요할 때. 로컬 개발의 기본 선택지로 적합합니다 | Unix-local 시작 예제 |
DockerSandboxClient |
openai-agents[docker] |
컨테이너 격리 또는 로컬 동등성을 위한 특정 이미지가 필요할 때 | Docker 시작 예제 |
Unix-local은 로컬 파일시스템을 대상으로 개발을 시작하는 가장 쉬운 방법입니다. 더 강한 환경 격리나 프로덕션 수준 동등성이 필요해지면 Docker 또는 호스티드 제공업체로 이동하세요
Unix-local에서 Docker로 전환할 때는 에이전트 정의는 그대로 두고 run config만 변경하세요
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를 참고하세요
마운트 및 원격 스토리지
마운트 항목은 노출할 스토리지를 설명하고, 마운트 전략은 샌드박스 백엔드가 해당 스토리지를 연결하는 방식을 설명합니다. 내장 마운트 항목과 범용 전략은 agents.sandbox.entries에서 가져오세요. 호스티드 제공업체 전략은 agents.extensions.sandbox 또는 제공업체별 확장 패키지에서 사용할 수 있습니다
일반적인 마운트 옵션:
mount_path: 샌드박스에서 스토리지가 표시되는 위치입니다. 상대 경로는 매니페스트 루트 아래에서 해석되고, 절대 경로는 그대로 사용됩니다read_only: 기본값은True입니다. 샌드박스가 마운트된 스토리지에 다시 써야 할 때만False로 설정하세요mount_strategy: 필수입니다. 마운트 항목과 샌드박스 백엔드 모두에 맞는 전략을 사용하세요
마운트는 임시 워크스페이스 항목으로 처리됩니다. 스냅샷 및 영속화 흐름에서는 마운트된 원격 스토리지를 저장된 워크스페이스로 복사하는 대신, 마운트 경로를 분리하거나 건너뜁니다
범용 로컬/컨테이너 전략:
| 전략 또는 패턴 | 사용 시점 | 참고 |
|---|---|---|
InContainerMountStrategy(pattern=RcloneMountPattern(...)) |
샌드박스 이미지에서 rclone을 실행할 수 있을 때 |
S3, GCS, R2, Azure Blob을 지원합니다. 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은 rclone을 지원하며, S3와 GCS는 mountpoint도 지원합니다 |
지원되는 호스티드 플랫폼
호스티드 환경이 필요할 때도 동일한 SandboxAgent 정의를 대체로 그대로 사용할 수 있으며, 보통 SandboxRunConfig에서 샌드박스 클라이언트만 변경하면 됩니다
이 저장소 체크아웃이 아니라 배포된 SDK를 사용 중이라면, 해당 패키지 extra를 통해 샌드박스 클라이언트 의존성을 설치하세요
제공업체별 설정 참고 사항과 저장소에 포함된 확장 예제 링크는 examples/sandbox/extensions/README.md를 참고하세요
| 클라이언트 | 설치 | 예시 |
|---|---|---|
BlaxelSandboxClient |
openai-agents[blaxel] |
Blaxel 실행기 |
CloudflareSandboxClient |
openai-agents[cloudflare] |
Cloudflare 실행기 |
DaytonaSandboxClient |
openai-agents[daytona] |
Daytona 실행기 |
E2BSandboxClient |
openai-agents[e2b] |
E2B 실행기 |
ModalSandboxClient |
openai-agents[modal] |
Modal 실행기 |
RunloopSandboxClient |
openai-agents[runloop] |
Runloop 실행기 |
VercelSandboxClient |
openai-agents[vercel] |
Vercel 실행기 |
호스티드 샌드박스 클라이언트는 제공업체별 마운트 전략을 제공합니다. 스토리지 제공업체에 가장 적합한 백엔드와 마운트 전략을 선택하세요
| 백엔드 | 마운트 참고 |
|---|---|
| Docker | InContainerMountStrategy, DockerVolumeMountStrategy 같은 로컬 전략으로 S3Mount, GCSMount, R2Mount, AzureBlobMount, S3FilesMount를 지원합니다 |
ModalSandboxClient |
S3Mount, R2Mount, HMAC 인증 GCSMount에서 ModalCloudBucketMountStrategy를 사용해 Modal 클라우드 버킷 마운트를 지원합니다. 인라인 자격 증명 또는 이름이 지정된 Modal Secret을 사용할 수 있습니다 |
CloudflareSandboxClient |
S3Mount, R2Mount, HMAC 인증 GCSMount에서 CloudflareBucketMountStrategy를 사용해 Cloudflare 버킷 마운트를 지원합니다 |
BlaxelSandboxClient |
S3Mount, R2Mount, GCSMount에서 BlaxelCloudBucketMountStrategy를 사용해 클라우드 버킷 마운트를 지원합니다. 또한 agents.extensions.sandbox.blaxel의 BlaxelDriveMount 및 BlaxelDriveMountStrategy로 영속 Blaxel Drive도 지원합니다 |
DaytonaSandboxClient |
DaytonaCloudBucketMountStrategy로 클라우드 버킷 마운트를 지원합니다. S3Mount, GCSMount, R2Mount, AzureBlobMount와 함께 사용하세요 |
E2BSandboxClient |
E2BCloudBucketMountStrategy로 클라우드 버킷 마운트를 지원합니다. S3Mount, GCSMount, R2Mount, AzureBlobMount와 함께 사용하세요 |
RunloopSandboxClient |
RunloopCloudBucketMountStrategy로 클라우드 버킷 마운트를 지원합니다. S3Mount, GCSMount, R2Mount, AzureBlobMount와 함께 사용하세요 |
VercelSandboxClient |
현재 호스티드 전용 마운트 전략이 노출되어 있지 않습니다. 대신 매니페스트 파일, 저장소, 기타 워크스페이스 입력을 사용하세요 |
아래 표는 각 백엔드가 직접 마운트할 수 있는 원격 스토리지 항목을 요약합니다
| 백엔드 | AWS S3 | Cloudflare R2 | GCS | Azure Blob Storage | S3 Files |
|---|---|---|---|---|---|
| Docker | ✓ | ✓ | ✓ | ✓ | ✓ |
ModalSandboxClient |
✓ | ✓ | ✓ | - | - |
CloudflareSandboxClient |
✓ | ✓ | ✓ | - | - |
BlaxelSandboxClient |
✓ | ✓ | ✓ | - | - |
DaytonaSandboxClient |
✓ | ✓ | ✓ | ✓ | - |
E2BSandboxClient |
✓ | ✓ | ✓ | ✓ | - |
RunloopSandboxClient |
✓ | ✓ | ✓ | ✓ | - |
VercelSandboxClient |
- | - | - | - | - |
실행 가능한 추가 예제는 로컬, 코딩, 메모리, 핸드오프, 에이전트 조합 패턴에 대해 examples/sandbox/를, 호스티드 샌드박스 클라이언트에 대해서는 examples/sandbox/extensions/를 확인하세요