nontainer 📦
Versioned, forkable workspaces for code-using agents.
Give any Python agent loop a stateful terminal and Python tool over a workspace that commits files and cache together, forks in O(1), and checks out as a unit. Run locally — where agent code can work through whitelisted live host objects — or on a microVM while the workspace history stays in the state layer.
Think of it as a fake little computer with branchable history, packaged as a
library. No Docker, cloud sandbox, or service required for the local default:
pip install nontainer.
Status: alpha. Usable and tested end to end; the API will still move before 1.0.
The core
Nontainer keeps three concerns separate:
| Responsibility | |
|---|---|
WorkspaceProvider |
Where files and cache live, and which history operations are real. The default kvgit provider supplies cheap commits, forks, checkout, and history; other providers declare narrower capabilities rather than pretending equivalence. |
Executor |
Where terminal and Python code run and how they reach workspace state: locally through sandtrap and monkeyfs, or on a real machine through dud. |
| Adapters | How the two tools enter an existing agent loop: the core Python API, the shared Toolset any loop can call, an agno toolkit built on it, or an MCP server. A loop wraps each run in a turn (ws.turn(run_id)), which lands one commit stamped with how the run ended. |
The model-facing surface stays small: a terminal and a run_python tool.
Unlike stateless sandbox calls, both are stateful and bound to a session —
the shell's cd sticks, files one call writes the next call reads, and a
cache dict persists for the whole conversation. Because that state is a
versioned workspace, each state-changing call can be committed as one
unit: the host can fork a session in O(1), check out any commit, or audit
its history without teaching the agent a version control protocol.
What the sandbox is (and isn't). In-process, the Python sandbox (sandtrap) is a walled garden for cooperative LLM-generated code — it gates what agent code can reach (modules, host objects, the filesystem) to an allowlist you control (safe stdlib on by default, everything else opt-in), not a hardened boundary against code trying to escape. That's the right posture for your own agent's code. For crash containment and kernel-enforced defense-in-depth around cooperative code, use
isolation="process"/"kernel". For actively untrusted code, or execution exposed to anonymous clients, step off the local model and useDudExecutor()'s microVM backend (see the quick start). Full framing in the design notes.
What it looks like
from nontainer import store
st = store() # default ~/.nontainer
ws = st.open("user-42") # one session, one kvgit branch
ws.terminal("mkdir -p data && echo 'a,b\n1,2' > data/in.csv")
r = ws.run_python("""
import csv
rows = list(csv.reader(open('data/in.csv'))) # sees the shell's file
cache['n_rows'] = len(rows) # persists across the session
print(rows)
""")
r.commit # this call's commit; ws.checkout(it) restores it
ws.index.commit("baseline") # or compose one and name it yourself
child = ws.fork("what-if") # O(1) branch; the original is untouched
child.files.write("notes.md", "# findings\n")
child.index.commit("a thought")
ws.merge("what-if") # and bring its work back
child.close()
The sandbox config, the backends, the executor rungs, the adapters and the apps loop are all in the quick start.
Related work
- Cloud sandboxes (E2B, Daytona, Modal, Fly Sprites): real isolation, real infra. They have persistence; none have history, forking, or in-process host-object access.
- mcp-run-python (Pydantic): the incumbent local run-python (Pyodide-in-Deno). Stateless per call, no workspace, needs Deno.
- AgentFS (Turso): SQLite-backed agent FS + KV + SQL-queryable audit, snapshots by file copy. It comes at the problem from storage where nontainer comes from execution -- and nontainer runs on it as one of its backends.
- Val Town: agents-deploying-endpoints as a polished cloud product (TS). The handler design here is the self-hosted, session-scoped, Python, versioned take on the same instinct.
Part of the agex stack
nontainer composes kvgit, monkeyfs, termish, sandtrap, and reprobate -- each independently useful, each zero/minimal-dep -- and optionally dud when the little computer should be a real one. agex is the full agent framework over the same substrate; nontainer is the environment layer alone, offered to someone else's loop.
Documentation
Using it
- Quick Start -- first workspace, sandbox config, backends, picking an executor rung, adapters, the apps loop
- API Reference -- every class, method, and flag
- Delegation -- subagents as branches: ask, read the answer, decide what to merge
- Apps -- handler contract, execution model, test_app, serving and threat model
- agno sessions -- the conversation in the workspace, so rewind and fork cover memory too
What the agent sees
- ws-git -- its git over its own session: every verb, what it prints, what it refuses
- Unit tests --
ws-pytestandws-vitest: discovery, the flags, calling a handler with a fake, mocking at the fetch boundary
Extending it
- Extending -- the three seams (a new substrate, a new place code runs, the agent loop behind a delegation), and the harness contract with the scenarios that check it
Why it's shaped this way
- Design notes -- execution model, commit granularity, tool exposure, and what's still ahead
- Browser roadmap -- where browser-side serving and compute stand: what shipped, what is next, and the design behind both
- Curation -- agents learning from each other's sessions: traces as files, a wiki, skills that ship code, and a gate with no answer key
- Compaction -- keeping a long conversation inside the context window: older turns folded into one summary for the model, the full transcript kept; nontainer keeps the record of each fold, and each loop folds its own way
Seeing it run
- Tour -- the whole surface end to end, with no LLM in the loop
- Examples -- live agno agents: a data analyst (
analyst.py) and a build-and-verify web app (webapp.py)
Install
pip install nontainer # workspace + terminal + run_python
pip install nontainer[agno] # + agno Toolkit adapter
pip install nontainer[mcp] # + MCP server (python -m nontainer.adapters.mcp)
pip install nontainer[apps] # + handlers/curl, Playwright test_app, serving router
pip install nontainer[agentfs] # + AgentFS substrate (agentfs-sdk)
pip install nontainer[dud] # + real-machine / microVM execution (needs 3.11+)
pip install nontainer[postgres] # + Postgres for the store (Store(kv="postgresql://..."))
Development
uv sync --extra dev --extra apps --extra agno --extra mcp --extra dud
uv run pytest -q -n auto # one worker per core; drop -n for a single test
uv run ruff check nontainer tests && uv run ruff format --check nontainer tests
Include --extra dud on 3.11+: the DudExecutor tests guard themselves
with importorskip, so without it the whole real-machine suite skips
silently and the run is green for the wrong reason. (On 3.10 the extra
installs nothing — it carries a python_version >= "3.11" marker — and
those tests skip by design.)
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for nontainer 0.11.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| nontainer-0.11.4.tar.gz | 1.5 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| nontainer-0.11.4-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.2 MB
Release files / nontainer-0.11.4.tar.gz
| Download URL | nontainer-0.11.4.tar.gz |
|---|---|
| Size | 1.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0a445345308729712214aeaafaf5b054722d82f56d340fd6e4df1240a55b85d4
|
|
BLAKE2b-256 checksum How to use checksums |
8aa1fbea7c4a0ed3178fc7c3a0d812d61a8ec3d7e7c10ac32a62d623144f2ae4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.15
|
Release files / nontainer-0.11.4-py3-none-any.whl
| Download URL | nontainer-0.11.4-py3-none-any.whl |
|---|---|
| Size | 714.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3f544b0aa620e03bf004c49ee1bad3aa8f0eafc620a4c05422ea768b39176ea4
|
|
BLAKE2b-256 checksum How to use checksums |
2a74272c5fd07f95a8e088cc2987991cab125cd13c15e59d3890359655586ea8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.15
|
