Skip to content

Isolation tiers

"Sandbox" spans radically different guarantees, and every abstraction in this space presents them behind one word. sandboxio does not. Every backend and every sandbox reports an IsolationTier, it appears in reprs, audit events and spans, and you can require one.

What the tier measures

One property: resistance to kernel escape by an adversarial tenant. Not performance, not features, not cost. The rank orders that property only (ADR-0018).

Tier Mechanism Honest position
CONTAINER a Linux container sharing the host kernel (runc) — Docker's own description Not a security boundary against hostile code. For trusted, dev and CI code only. A kernel exploit is a host compromise.
GVISOR a user-space kernel interposed between the container and the host — Modal's own description Defence in depth, not hardware-VM equivalence. No v0.1 backend provides it; the tier is a property of the model, not of what shipped.
MICROVM a dedicated guest kernel in a hardware-virtualised VM (Firecracker) — E2B's own description The recommended floor for untrusted, multi-tenant code.
UNKNOWN the adapter has not verified its mechanism Satisfies no requirement. Creating on it warns once per backend.

Each mechanism above links the provider's own documentation, read on 2026-09-20 — the same three sources the repository README cites per backend. None of those pages carries its own revision date, so that is the date it was read, not a date the provider published; re-verification is a quarterly item. UNKNOWN carries no source because it is the absence of a claim.

Docker is CONTAINER. E2B is MICROVM. Modal is GVISOR and is planned for v0.1.1 (ADR-0025). The fake reports CONTAINER while isolating nothing, because it is for tests.

Why CONTAINER is still in the product

Because most agent code is not hostile, and local Docker is where development happens. The point is not to forbid it; the point is that code reviewed against local Docker and deployed against a cloud backend — or the reverse — should never silently change its security assumption. The tier makes the change visible.

Making it enforceable

import sandboxio
from sandboxio import IsolationTier

sb = await sandboxio.create("e2b://", require_isolation=IsolationTier.MICROVM)

require_isolation is checked before anything is provisioned. A weaker backend fails with ConfigurationError and nothing was created or billed. require_isolation=UNKNOWN is meaningless and raises. This one line is the most valuable security affordance in the API: it turns a silent downgrade into a failed deployment.

Why every tier carries a dated source

A tier is a claim about someone else's infrastructure. This project publishes one only with a dated link to the provider's own documentation, re-verified quarterly (ADR-0006, hazard H4) — which is why the table above and the per-backend table in the repository README both cite the provider, not us. A backend whose mechanism is not verified that way reports UNKNOWN rather than CONTAINER, because CONTAINER is itself a claim. A provider changing its isolation mechanism is a breaking change in this project's public data, not a footnote: it goes in the changelog and the churn log.