Sandbox clients

Use this page to choose where sandbox work should run. In most cases, the SandboxAgent definition stays the same while the sandbox client and client-specific options change in SandboxRunConfig.

Beta feature

Sandbox agents are in beta. Expect details of the API, defaults, and supported capabilities to change before general availability, and expect more advanced features over time.

Decision guide

Goal	Start with	Why
Fastest local iteration on macOS or Linux	`UnixLocalSandboxClient`	No extra install, simple local filesystem development.
Basic container isolation	`DockerSandboxClient`	Runs work inside Docker with a specific image.
Hosted execution or production-style isolation	A hosted sandbox client	Moves the workspace boundary to a provider-managed environment.

Local clients

For most users, start with one of these two sandbox clients:

Client	Install	Choose it when	Example
`UnixLocalSandboxClient`	none	Fastest local iteration on macOS or Linux. Good default for local development.	Unix-local starter
`DockerSandboxClient`	`openai-agents[docker]`	You want container isolation or a specific image to reproduce a target environment locally.	Docker starter

Unix-local is the easiest way to start developing against a local filesystem. Move to Docker or a hosted provider when you need stronger environment isolation or production-style parity.

SandboxPathGrant.host_path is Docker-only and maps a host path to a different POSIX path inside the container. Unix-local supports only same-path grants. See Manifest path grants for details.

To switch from Unix-local to Docker, keep the agent definition the same and change only the 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"),
    ),
)

Use this when you want container isolation or want the sandbox image to match the image used in another environment. See examples/sandbox/docker/docker_runner.py.

Mounts and remote storage

Mount entries describe what storage to expose; mount strategies describe how a sandbox backend attaches that storage. Import the built-in mount entries and generic strategies from agents.sandbox.entries. Hosted-provider strategies are available from agents.extensions.sandbox or the provider-specific extension package.

Common mount options:

mount_path: where the storage appears in the sandbox. Relative paths are resolved under the manifest root; absolute paths are used as-is.
read_only: defaults to True. Set False only when the sandbox should write back to the mounted storage.
mount_strategy: required. Use a strategy that matches both the mount entry and the sandbox backend.

Mounts are treated as ephemeral workspace entries. Snapshot and persistence flows detach or skip mounted paths instead of copying mounted remote storage into the saved workspace.

Generic local/container strategies:

Strategy or pattern	Use it when	Notes
`InContainerMountStrategy(pattern=RcloneMountPattern(...))`	The sandbox image can run `rclone`.	Supports S3, GCS, R2, Azure Blob, and Box. `RcloneMountPattern` can run in `fuse` mode or `nfs` mode.
`InContainerMountStrategy(pattern=MountpointMountPattern(...))`	The image has `mount-s3` and you want Mountpoint-style S3 or S3-compatible access.	Supports `S3Mount` and `GCSMount`.
`InContainerMountStrategy(pattern=FuseMountPattern(...))`	The image has `blobfuse2` and FUSE support.	Supports `AzureBlobMount`.
`InContainerMountStrategy(pattern=S3FilesMountPattern(...))`	The image has `mount.s3files` and can reach an existing S3 Files mount target.	Supports `S3FilesMount`.
`DockerVolumeMountStrategy(driver=...)`	Docker should attach a volume-driver-backed mount before the container starts.	Docker-only. S3, GCS, R2, Azure Blob, and Box can be mounted through `rclone`; S3 and GCS can also be mounted through `mountpoint`.

Supported hosted platforms

When you need a hosted environment, the same SandboxAgent definition usually carries over and only the sandbox client changes in SandboxRunConfig.

If you are using the published SDK instead of this repository checkout, install sandbox-client dependencies through the matching package extra.

For provider-specific setup notes and links for the checked-in extension examples, see examples/sandbox/extensions/README.md.

Client	Install	Example
`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

Hosted sandbox clients expose provider-specific mount strategies. Choose the backend and mount strategy that best fit your storage provider:

Backend	Mount notes
Docker	Supports `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`, and `S3FilesMount` with local strategies such as `InContainerMountStrategy` and `DockerVolumeMountStrategy`.
`ModalSandboxClient`	Supports cloud bucket mounts by using `ModalCloudBucketMountStrategy` with `S3Mount`, `R2Mount`, and HMAC-authenticated `GCSMount`. You can use inline credentials or a named Modal Secret.
`CloudflareSandboxClient`	Supports bucket mounts by using `CloudflareBucketMountStrategy` with `S3Mount`, `R2Mount`, and HMAC-authenticated `GCSMount`.
`BlaxelSandboxClient`	Supports cloud bucket mounts by pairing `BlaxelCloudBucketMountStrategy` with an `S3Mount`, `R2Mount`, or `GCSMount` entry. Also supports persistent Blaxel Drives with `BlaxelDriveMount` and `BlaxelDriveMountStrategy`, both available from `agents.extensions.sandbox.blaxel`.
`DaytonaSandboxClient`	Supports mounting cloud storage through `rclone` by using `DaytonaCloudBucketMountStrategy`; use it with `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, and `BoxMount`.
`E2BSandboxClient`	Supports mounting cloud storage through `rclone` by using `E2BCloudBucketMountStrategy`; use it with `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, and `BoxMount`.
`RunloopSandboxClient`	Supports mounting cloud storage through `rclone` by using `RunloopCloudBucketMountStrategy`; use it with `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, and `BoxMount`.
`VercelSandboxClient`	Supports create-time-only S3 and S3-compatible bucket mounts by pairing `VercelCloudBucketMountStrategy` with an `S3Mount` entry; mounted sessions cannot be resumed, and inline credentials require `allow_s3_credential_exposure=True`.

The mount tables describe which storage types each backend can execute. A check mark does not bypass the credential boundary for a mount helper that runs inside a model-controlled sandbox, and it does not mean that every strategy can operate without credentials. The Agents SDK accepts an in-container mount without an acknowledgement only when the selected helper can operate without protected authority. It rejects a mount that requires protected authority before starting the sandbox or mount helper unless trusted application code explicitly acknowledges the exposure for the exact mount path.

Credentialless rclone mounts are limited to S3, GCS, R2, and Azure Blob. An in-container Box mount requires a non-interactive authentication source and the acknowledgement that matches that source. FuseMountPattern requires broad acknowledgement because blobfuse2 discovers ambient Azure authority, even when no inline credential is configured. S3FilesMountPattern likewise requires broad acknowledgement because mount.s3files uses ambient IAM authority. These requirements also apply when Docker is the backend; the check marks below indicate that Docker can execute the mount after the applicable authority boundary is satisfied.

For a mount entry named "data", retain the copied Manifest returned by the acknowledgement that matches the configured authority:

# Mount-scoped values such as inline access keys.
manifest = manifest.with_in_container_mount_credential_exposure_acknowledged("data")

# Broader authority such as managed or workload identity and external credential files.
manifest = manifest.with_in_container_mount_broad_credential_exposure_acknowledged("data")

Pass every exact mount path that needs the acknowledgement. A mount that uses both authority classes requires both acknowledgements. The acknowledgements are runtime-only, are not serialized, and permit the helper to receive credentials without confining credential use to the mounted path. Prefer an external or provider-native strategy when available, and otherwise use sandbox-scoped, short-lived, least-privilege credentials.

VercelSandboxClientOptions(allow_s3_credential_exposure=True) remains a compatibility option for create-time Vercel S3 mounts with inline mount-scoped credentials. It does not authorize broad credential authority.

The table below summarizes which remote storage entries each backend can mount directly.

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

For more runnable examples, browse examples/sandbox/ for local, coding, memory, handoff, and agent-composition patterns, and examples/sandbox/extensions/ for hosted sandbox clients.