Sandboxes matrix
Every supported sandbox backend at a glance — what it gives you, the example, and the one-liner to enable it.
A sandbox is where shell commands and tool calls execute. It's chosen at init({ sandbox }) and is independent of which SDK entrypoint you import from and which runtime you select.
| Sandbox | What it gives you | Enable with | Example |
|---|---|---|---|
virtual (default) | In-memory FS + bash subset (grep, glob, read, cat, mkdir, rm, echo) via just-bash. No host shell access. | injected by default; init({ sandbox: 'virtual' }) to be explicit | examples/hello-world/ |
local | Host filesystem and host shell at the session's working directory. | init({ sandbox: 'local' }) | examples/with-local-shell/ |
docker | Per-session Docker container; reads/writes scoped to the container. | init({ sandbox: { backend: 'docker', image: 'node:22' } }) | examples/with-docker/ |
cloudflare | Cloudflare Sandbox container binding for Workers. Edge-native. | init({ sandbox: await getCloudflareSandbox(env.SANDBOX, sessionId) }) (from @fabric-harness/cloudflare) | examples/with-cloudflare-sandbox/ |
Temporal-driven local | Runs through Temporal workflows for replay-determinism, restartability, approvals. | import { agent } from '@fabric-harness/sdk/strict' + init({ runtime: 'temporal', sandbox: 'local', compaction: { enabled: false } }) | examples/with-temporal/ |
| Azure Foundry Hosted | Azure-managed agent runtime; Key Vault secrets, Foundry observability. | AzureOpenAIModelProvider + fabric-harness build --target foundry-hosted-agent | examples/with-azure/ |
| Daytona | Daytona-managed remote dev sandbox. Per-task ephemeral box. | init({ sandbox: daytonaSandbox(remote, { cleanup: true }) }) (from @fabric-harness/connectors) | examples/with-daytona/ |
| E2B | E2B remote sandbox; native pause/resume. | init({ sandbox: e2bSandbox(remote, { cleanup: true }) }) (from @fabric-harness/connectors) | recipe connectors/sandbox--e2b.md |
| Modal | Modal serverless sandbox; per-request GPU. | init({ sandbox: modalSandbox(remote, { cleanup: true }) }) (from @fabric-harness/connectors) | examples/with-modal/ |
| Vercel Sandbox | Vercel's ephemeral container compute (Amazon Linux 2023, Node 24/22, python3.13). Native pause/extend. | init({ sandbox: vercelSandbox(remote, { cleanup: true }) }) (from @fabric-harness/connectors/vercel) | recipe connectors/sandbox--vercel.md |
| Kubernetes / AKS | Kubernetes pod via kubernetesSandbox(pod, …) (or aksSandbox from @fabric-harness/azure). | init({ sandbox: kubernetesSandbox(pod, { cleanup: true }) }) (from @fabric-harness/connectors/k8s) | examples/with-kubernetes/ |
| Databricks SQL | SQL Warehouse exec-only sandbox. | init({ sandbox: databricksSqlSandbox(client) }) (from @fabric-harness/databricks/sql-sandbox) | n/a |
empty | No filesystem, no shell — pure model + tool-call work. | init({ sandbox: 'empty' }) | n/a |
Maturity.
virtual,local,docker,emptyare stable.daytona,e2b,modal,cloudflare,kubernetes/aks,databricks-sqlare experimental — covered by tests but mock-only in CI; live integrations rotate. Seedocs/capability-matrix.mdfor the source of truth.
Cross-process refs. Remote backends (E2B, Daytona, Modal, Kubernetes) can be re-attached from another process with
session.sandboxRef({ portable: true })+attachSandbox(serialized)onceregisterStandardSandboxRefDecoders({...})is called in the receiving process. See@fabric-harness/connectors/sandbox-refs.
Picking a sandbox
- One-shot webhook / edge worker —
virtual(cheap, fast, no host) orcloudflare(Workers). - CI job, dev box —
local. - Coding agent / untrusted shell work —
docker,daytona, ormodal. - Long-running, restartable — Temporal-driven
local(use/strict). - Compliance / Azure tenant — Azure Foundry Hosted Agent.
Capability axes
Every sandbox declares a SandboxCapabilities shape so agents can adapt:
sandbox.capabilities // { exec, network, filesystem, snapshot, ... }Use this when an agent legitimately needs to know whether shell exec is available before issuing a command.
See also
- Sandboxes overview — the conceptual model.
- Sandbox connectors — building your own
RemoteSandboxApi. - Capability matrix — current first-class vs designed-for status.