Skip to content
oma

Features / Agent Sandbox

Run your agents in any sandbox

Every tool call executes inside a sandbox, never on the platform host. One SandboxExecutor interface, ten adapters — pick a provider per environment; the agent's code never changes.

Why it matters

  • Your infrastructure: containers, a Kubernetes cluster, or a machine you already own — never a locked-in vendor sandbox.
  • No credential leakage: vault secrets are injected by an outbound proxy, never handed to the sandbox process.
  • Same agent, any provider: switch sandbox_provider on an environment without touching the agent config.

How it works

1. Pick a provider

An environment's config.sandbox_provider selects the adapter — packages, networking, and container image are all part of the same environment record.

2. Credentials stay out

Vault credentials are never mounted or exported into the sandbox. An outbound proxy matches HTTPS requests leaving the sandbox and injects the right Authorization header at the network edge.

3. Same agent everywhere

Tools, skills, and harness logic are provider-agnostic. Swap Cloudflare Containers for Kubernetes or a bridged laptop and the agent's behavior is unchanged.

Sandbox providers

Cloudflare Containers

default

Zero setup on the Cloudflare deployment.

Kubernetes

self-host

Pod-per-sandbox on your own cluster.

k8s-remote

cloudflare

In-cluster gateway over plain HTTP.

NVIDIA OpenShell

cloudflare

Default-deny egress, Landlock FS.

BoxRun

cloudflare

Remote boxlite control plane, no SDK.

Your machine

bridge relay

`oma bridge daemon` — fastest inner loop.

Browser VM

bridge relay

A WASM VM in your own tab — zero server compute.

Docker Compose

self-host

Containers on any Docker host.

E2B

self-host

Firecracker micro-VMs, bring your key.

Daytona

self-host

Managed cloud dev environments.

LiteBox

self-host

Native micro-VM binding.

Dynamic Workers

cloudflare

JS eval in a fresh V8 isolate — no shell or disk.

See it in the Console

Sandbox Runtimes page — every backend behind one interface
Every backend on one Sandbox Runtimes page — health, capacity, capabilities.
Adding a sandbox runtime in the OMA Console
Add a runtime — your own machine joins over an outbound-only WebSocket.
The Sandbox concept — supported providers next to the live runtimes page
One session → one sandbox: bash, files, and browsers run inside; the provider is set by the environment.

Configure it in one field

An environment is a reusable record: sandbox provider, package managers, and networking policy in one place.

{
  "name": "data-science",
  "config": {
    "sandbox_provider": "k8s-remote",
    "packages": {
      "pip": ["numpy", "pandas", "matplotlib", "scikit-learn"],
      "apt": ["ffmpeg"]
    },
    "networking": {
      "type": "limited",
      "allowed_hosts": ["api.github.com", "registry.npmjs.org"],
      "allow_mcp_servers": true,
      "allow_package_managers": true
    }
  }
}

Connecting a private cluster end-to-end (Helm charts, bridge daemon vs HTTP gateway, pod diagram) is covered on Private Kubernetes.

FAQ

Which sandbox providers work on the Cloudflare deployment?

Cloudflare Containers work out of the box. BoxRun, k8s-remote, OpenShell, and subprocess (via the bridge relay) also work on Cloudflare — each talks to a remote control plane over plain fetch, since a Worker can't spawn processes or speak gRPC. Browser VM relays sandbox ops to a WASM Linux VM running in your own browser tab — zero server compute, opened with one click from the Console. Daytona and E2B are outbound-HTTP-only in principle but not yet wired into the Worker bundle. LiteBox, raw Kubernetes, and Docker Compose need Node builtins or a Docker socket, so they only run on the self-hosted Node runtime.

Do credentials ever reach the sandbox?

No. Vault credentials are injected by an outbound proxy that intercepts HTTPS requests leaving the sandbox and attaches the right Authorization header at the network edge. The sandbox process, the harness, and the model never see a plaintext token.

Can a sub-agent get its own isolated sandbox?

By default a delegated sub-agent thread shares the parent session's sandbox and /workspace. A callable_agents entry can set environment_id to a different environment to give that sub-agent a dedicated sandbox for the call, torn down afterward. It starts from an empty workspace and vault credential injection still works, but memory-store mounts and usage metering aren't wired for it yet.

What happens to the sandbox when a session is paused?

Pausing snapshots /workspace and destroys the container — you stop paying for an idle sandbox. Resuming reprovisions the container and restores the latest snapshot. Sending a new message to a paused session resumes it implicitly on first use.

How do I pick a sandbox provider for an environment?

Set config.sandbox_provider on the environment (defaults to Cloudflare Containers if omitted). Every agent that references that environment runs its tools in that sandbox — no code changes to the agent itself.