sandboxio¶

One secure Python API for running AI-agent code in any sandbox. Swap Docker ↔ E2B with one line; no network by default; test your agent tools offline with the built-in fake.

Pre-alpha — nothing is released. The core, the contract suite, FakeBackend, the Docker and E2B adapters, the CLI and the integrations exist and pass their gates, but the public API is not stable and nothing is published to PyPI. What is stable enough to build against is the specification, which is normative and CI-enforced.

Run code in a sandbox¶

uv add "sandboxio[docker]"   # or "sandboxio[e2b]" — the core has no backend built in

import sandboxio

async with await sandboxio.create() as sb:
    res = await sb.run_code("print('hello')")
    print(res.stdout)

create() with no arguments is local Docker with egress denied, a mandatory timeout and modest resource caps. The backend is one string away:

import sandboxio

sb = await sandboxio.create("e2b://code-interpreter-v1")   # needs E2B_API_KEY
sb = await sandboxio.create("fake://")                     # tests; executes nothing

Where to go next¶

You want	Read
Install to a sandboxed run in five minutes	Quickstart
A task guide for your backend	Docker · E2B · Offline testing
To run untrusted code safely	Isolation tiers
The meaning of an `SBX_E` code you just hit	Error codes
The normative contract	Specification
Why a decision is the way it is	Decisions
Rules to paste into a coding assistant	AGENTS.md snippet

Coding assistants: llms.txt indexes these pages and llms-full.txt concatenates them for one-shot context loading.

About this documentation¶

Working documentation for sandboxio: a framework-agnostic Python sandbox abstraction library for AI-agent code and tool execution. One async API over Docker, E2B and Modal backends; ports/adapters; capability discovery; security-first defaults; native escape hatches.

Naming: the project is sandboxio; SBX is its short code, used for error codes (SBX_E1002), env vars (SBX_DEBUG), the pytest fixture (sbx_fake) and the CLI alias. Canonical usage is import sandboxio, unaliased. See ADR-0014.

Layout¶

Path	Contents	Normative?
`quickstart.md`	Tutorial: install to a sandboxed run in five minutes.	no
`how-to/`	Task guides: Docker, E2B, offline testing, audit and tracing, CI, operations.	no
`explanation/`	Why: isolation tiers, deny by default, error codes.	no
`errors/`	Reference: every error code, generated from the source.	yes
`reference/`	Reference: the paste-ready `AGENTS.md` snippet for downstream projects.	no
`llms.txt` / `llms-full.txt`	Index and full text for coding assistants; the full text is generated.	no
`adr/`	Architecture Decision Records. One file per decision, with context and consequences.	yes
`spec/`	The normative specification: domain model, ports, public API, errors, security policy, observability, configuration, adapter contract. RFC-2119 language.	yes
`build-order.md`	Sequenced implementation plan with per-step exit criteria.	yes
`open-questions.md`	Unresolved decisions. Each graduates into an ADR when settled.	no
`hazards.md`	What can kill the project, or its users, plus tripwires and responses.	no
`runbook.md`	How to operate the project: dev setup, CI gates, release, provider-churn response, security advisories.	yes

Reading order¶

User: quickstart.md → examples/ → the how-to/ page for your backend → explanation/isolation-tiers.md before running untrusted code.

New contributor: README.md → spec/ index → build-order.md → runbook.md.

Coding agent: spec/ is the contract. Where the spec is silent or marked OPEN, stop and ask — do not invent. adr/ explains why, which matters when a requirement looks arbitrary.

Deciding something: check open-questions.md first; if it is not there and it will outlive the PR, it needs an ADR.

Precedence¶

When two documents disagree: spec/ wins over adr/.

Both descend from an earlier planning set, which the ADRs' Context sections call the input set or the input design. It is not part of this repository and is superseded, not authoritative: it predates every decision recorded here, and several of its snippets were wrong.

Corrections to the original design¶

Listed because the corrections are load-bearing — each is a requirement that looks arbitrary until you know what it is fixing.

Topic	Error	Resolved by
Routing config	The routing config was not valid YAML — `-> isolated` trailing a flow mapping is a parser error. Verified with a parser, not by eye.	spec/07
Fake assertions	`assert ... is NetworkPolicy(egress="deny")` — `is` against a freshly constructed dataclass is always false. Use `==`.	spec/01
Streaming example	The example was `pip install -r requirements.txt`, which cannot run under the default deny-egress policy.	Q10
Error taxonomy	`TimeoutError` shadowed the builtin, which on our floor is what `asyncio` raises.	ADR-0017
Streaming signature	`stream() -> AsyncIterator[bytes]` with `**kw` — loses stderr and exit code, and leaks a kwargs black hole.	ADR-0019
Sync `create()`	Auto-detected `create()` returning a different type in sync context.	ADR-0002
Isolation tiers	Daytona listed at `CONTAINER` beside the word "verify" — an unearned isolation claim.	ADR-0018
Project name	The name `sbx` is unavailable on PyPI.	ADR-0014

Every configuration sample in spec/ is parse-tested in CI, precisely because the first one was not.

Published site¶

This directory is published at https://docs.sandboxio.dev by mkdocs.yml and .github/workflows/docs.yml (ADR-0029). This page is the site's landing page; docs/ is its root, so a relative link may not leave the directory — link the repository by URL instead, which scripts/check_doc_links.py enforces. Error-code URLs are API (ADR-0010): a page that moves leaves a redirect behind.

make site      # or: uv sync --group docs && uv run mkdocs serve

Licensing¶

Code is MIT (LICENSE). The prose in this directory is CC BY 4.0 (LICENSE-DOCS) — quote and adapt the spec, with credit. Code samples inside these documents are MIT, not CC BY: anything in a fenced block is code, everything else is prose (ADR-0026).

Core principles¶

Each is expanded in an ADR.

Thin core, no LCD. Never reduce the API to what every backend supports. One-backend features go behind Capability flags and .native. (ADR-0003)
Security is the headline, not an add-on. No-network default, mandatory timeouts, isolation-tier reporting, audit hooks — all in v0.1. (ADR-0005)
Tiny, auditable core. Near-zero base dependencies; backend SDKs behind extras, lazily imported. (ADR-0004)
Async-first, sync derived. (ADR-0002)
AI agents are first-class consumers — at runtime and at dev time.
Absorb provider churn publicly. Tracking and absorbing upstream breaking changes is the moat. Document every absorbed break. (runbook.md)