Sandbox Backends

Sandbox policy and sandbox backend are independent. Policy controls filesystem access, confinement, network access, allowed domains, and host execution. The backend is the launcher that applies that policy to newly spawned processes. /studio/sandbox displays both, but activating a backend does not rewrite policy. Backend changes are hot: existing processes remain owned by the launcher that created them, while processes spawned after a successful activation use the new launcher.

Built-in and contributed backends

Built-in auto selects the best available lightweight OS sandbox. Built-in vm is explicitly selected and is never provided by Power Pack. Docker and E2B are contributed by an enabled atom pack. Core protocol, daemon settings, and Studio do not contain Docker- or E2B-specific UI branches. Every backend is identified by its source-qualified reference:

type SandboxBackendRef =
  | { source: 'builtin'; kind: string }
  | { source: 'atom-pack'; packId: string; kind: string };

This keeps two packs that use the same kind isolated from one another.

Contributing a backend

A launcher declares a serializable descriptor and an optional settings schema:

const launcher: SandboxLauncher = {
  kind: 'cloud',
  descriptor: {
    name: 'Cloud sandbox',
    description: 'Runs tools in an isolated remote environment.',
    settings: {
      fields: [
        { id: 'region', type: 'string', label: 'Region', defaultValue: 'us-east' },
        { id: 'apiKey', type: 'secret', label: 'API key', required: true }
      ]
    }
  },
  configure: async (settings) => configureClient(settings),
  prepare: async () => prepareRuntime(),
  isAvailable: () => clientIsReady(),
  spawn: async (request) => spawnIsolated(request)
};

The available field types are string, number, boolean, select, and secret. Studio renders this schema generically. A launcher may also use Host Interaction for a setup flow that needs an immediate user response; see host-interactions.md. Descriptors cannot include frontend code, HTML, scripts, callbacks, or executable validation. Platform support and enforcement claims are data, not custom presentation instructions.

Settings and secrets

The host validates and stores settings under the backend’s source-qualified key. Disabling a pack leaves those settings intact so reinstalling the same stable pack identity can restore them. Secret fields are different from ordinary settings:

plaintext is stored directly in the owning sandbox backend setting;
read APIs return { configured: true }, never the value or reference target;
an empty secret input means no change;
replacement and removal are explicit actions;
resolved values are passed to configure() only inside the daemon.

E2B requires an API key supplied through its contributed secret field. Docker requires a working Docker-compatible runtime and may declare an image setting. These requirements belong to the contributed descriptors and launcher implementation, not to host UI logic.

Activation transaction

Activation is serialized and follows this order:

Validate candidate settings.
Resolve secrets inside the daemon.
Configure and prepare the candidate.
Probe availability.
Atomically swap the active launcher.
Persist the backend settings and active selection.
Dispose idle resources owned by the previous backend.

Candidate preparation happens while the old backend keeps serving. Validation, preparation, or availability failure leaves both runtime and persisted selection unchanged. Persistence failure swaps runtime back. Cleanup failure keeps the successful new activation, reports a warning, and retries cleanup asynchronously. Disabling or removing the pack that owns the active backend first activates built-in auto. If the safe fallback cannot be established, the pack operation is refused. No transition temporarily selects an unconfined launcher.

Compatibility

Backend discovery and activation use transport-neutral protocol objects. Studio is one presenter, not part of the backend contract. CLI, TUI, and ACP clients receive the same Host Interaction semantics and never need provider-specific UI code.

VM guest and host binaries

The VM backend needs four helper binaries of its own — the guest vsock exec agent, the seccomp observer, gvforwarder, and the Windows winvm-helper. They are not shipped inside the release: the daemon downloads whichever it needs into <vmDir>/bin on first use and verifies each against a pinned sha256. A digest that does not match its pin is refused, and the backend fails rather than running an unverified binary. Nothing needs provisioning up front. A machine that never selects the VM backend never fetches them. If you need them ahead of time — an offline host, or you are working on the binaries themselves — see packages/sandbox-vm.

VM pre-workload baselines

The built-in VM backend can cache a driver-native baseline after trusted guest boot and before the first workload. QEMU/KVM and Hyper-V implement the capability; vfkit reports it unavailable and cold boots. Restore is only a latency optimization: an invalid manifest, failed digest, epoch mismatch, active lease, or driver failure invalidates the candidate and cold boots once. Baselines are disabled by default. The VM backend settings expose baselineEnabled, baselineMaxInactiveArtifacts, and baselineMaxBytes. Legacy sandbox.vm.baseline settings normalize into those source-qualified backend settings. Cache directories are owner-only, identity- and toolchain-bound, digest-checked, leased, and LRU-bounded. They never contain credential values or credential-derived hashes.

Get Started

Monad Mesh: The Agent Team Runtime

Monad Agent Runtime: The First-Party Agent

Operate the Daemon

Trust and Policy

Reference

Sandbox Backends

Built-in and contributed backends

Contributing a backend

Settings and secrets

Activation transaction

Compatibility

VM guest and host binaries

VM pre-workload baselines

​Built-in and contributed backends

​Contributing a backend

​Settings and secrets

​Activation transaction

​Compatibility

​VM guest and host binaries

​VM pre-workload baselines

Built-in and contributed backends

Contributing a backend

Settings and secrets

Activation transaction

Compatibility

VM guest and host binaries

VM pre-workload baselines