nontainer 0.1.0__tar.gz

nontainer-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [released]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
+
+    - name: Install build dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+
+    - name: Build package
+      run: python -m build
+
+    - name: Check package
+      run: twine check dist/*
+
+    - name: Upload to PyPI
+      env:
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+      run: twine upload dist/*

nontainer-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,43 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[dev,apps,agno,mcp]"
+
+    - name: Install Playwright browser
+      run: python -m playwright install --with-deps chromium
+
+    - name: Run tests
+      run: |
+        pytest tests/ -v
+
+    - name: Run linter
+      run: |
+        ruff check nontainer/
+
+    - name: Check formatting
+      run: |
+        ruff format --check nontainer/

nontainer-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/

nontainer-0.1.0/CHANGELOG.md

@@ -0,0 +1,223 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-07-15
+
+### Added
+- **`AppsConfig.script_hosts` + `apps_primer`: the script allowlist is
+  one declaration.** The hosts browser scripts may load from used to
+  live in four hand-synced places — test_app's interception, the served
+  CSP, the agent-facing notes, curl's error message — kept honest only
+  by a test. All four now derive from `AppsConfig.script_hosts`
+  (default unchanged: `DEFAULT_SCRIPT_HOSTS`), so an embedder adding a
+  private registry host (e.g. a self-hosted esm.sh over an internal
+  npm registry) changes one tuple and the walls, the verifier, and the
+  agent's instructions stay in agreement. `apps_primer` appends
+  embedder guidance to the apps notes — the place to teach a private
+  component lib's known-good import block. `build_router(csp=...)`
+  now defaults to deriving from the config (`build_csp`); pass a string
+  to override or `""` to disable. Removed: `test_app`'s per-call
+  `cdn_allowlist` parameter (set it on the config instead). Agents predictably
+  write into `/ui` themselves (`fig.write_json('/ui/x.json')`,
+  savefig) instead of assigning objects to `ui = {...}` — and those
+  files displayed nowhere. `run_python` now diffs the `/ui` listing
+  around the call and appends files the code created to the
+  `[ui artifacts: ...]` note (deduped against materialized values),
+  extending the existing path-pointer near-miss forgiveness.
+- **The walls label their doors.** Three predictable agent collisions
+  now redirect instead of dead-ending:
+  a 404 on `/api/<name>.py` says endpoints are module names without
+  the extension (and suggests the real path when it exists) — agents
+  reliably mirror the filename into `fetch()` and then debug the
+  backend; blocked imports of `subprocess`/`requests`/`urllib.request`/
+  `httpx`/`socket` get a `[hint: ...]` in both run_python observations
+  and api.log pointing at the terminal's curl; and `urllib.parse` is
+  granted in the STDLIB preset (pure string functions only — `quote`,
+  `urlencode`, `parse_qs`, `urlparse`, ... — the network side of
+  urllib stays out). The apps primer also states the no-`.py`-in-URL
+  rule explicitly.
+- **The 8MB `ui` artifact cap explains itself.** An oversize value used
+  to silently degrade to a truncated `repr` `.txt` — a 280k-point
+  plotly map showed up as a wall of text with no hint why. Now the
+  tool result carries a `[ui note: ...]` diagnosis (size vs cap, and
+  for plotly the actual usual culprit: per-point customdata/hover
+  strings — coordinates are cheap, WebGL traces render 100k+ points
+  fine) so the agent self-corrects, and the `.txt` artifact shows the
+  same message to the human where the figure would have been.
+  `materialize_ui` now returns `(artifacts, problems)`. The tool
+  description also teaches the cap + lean-spec guidance up front.
+- **`python3` terminal alias.** The reserved `python` bridge now also
+  answers to `python3` — the reflex spelling agents type first. Both
+  names are reserved against user command injection.
+- **`warnings` in the STDLIB preset.** `warn`, `filterwarnings`,
+  `simplefilter`, and `catch_warnings` are granted — agents reach for
+  `warnings.filterwarnings("ignore")` the moment pandas/sklearn start
+  emitting deprecation noise, and the module was imported by the
+  presets but never granted.
+- **Artifact channels: binary in, images and files out.** Three
+  pieces close the "artifacts are stranded in the workspace" gap:
+  a `view_image` tool in both adapters (the agent views a saved
+  plot/chart — returned as real image content for vision models;
+  png/jpeg/gif/webp, 10MB cap); MCP **resources** exposing every
+  workspace file as `workspace://{path}` (text as text, binary as
+  blob) with a `workspace://-/tree` index — the client-side window
+  for extracting what the agent produced; and a `--mount
+  POINT=DIR[:rw]` flag on the MCP CLI (read-only by default) — the
+  inbound channel for seeding real host files without base64 games.
+  `file_write` results additionally carry a ground-truth
+  `ResourceLink` to the written file (the link exists because the
+  write succeeded), and the MCP tool descriptions coach the agent to
+  mention `workspace://` URIs when it produces artifacts.
+- **Safe stdlib by default** — `PythonConfig(stdlib=True)` grants a
+  curated stdlib set (see `nontainer.presets.STDLIB`), so a plain
+  workspace's Python can `import math`/`json`/`csv`/... out of the box.
+- **Module-grant presets** — `nontainer.presets.dataframes()` (numpy +
+  pandas) and `plotting()` (matplotlib Agg-pinned + font cache warmed;
+  plotly optional). `ModuleGrant` gains `include`/`exclude`/`recursive`/
+  `name`; `PythonConfig.modules` flattens preset lists one level.
+- **Results pin their commit** — `TerminalResult`/`PythonResult`/
+  `EditOutcome` carry `checkpoint` (the commit the call produced, or
+  `None`); `write_file`/`put` return a `WriteOutcome`; `ws.head` /
+  `ws.dirty` pin the state a read-only call observed.
+- **Async host facades** — `ws.aterminal` / `ws.arun_python` run the
+  sync execution in a thread so event-loop hosts (FastAPI, etc.) stay
+  responsive; the agent surface is unchanged.
+- **Shared browser for `test_app`** — one Chromium across all calls
+  (async Playwright on a dedicated loop-thread), a context per
+  concurrent test bounded by a semaphore (`configure_browser`), plus
+  `arun_test_app` and `shutdown_browser`. Memory scales with
+  concurrency, not sessions.
+- **`py.typed`** — the package now ships its PEP 561 marker.
+- **Tool primers** — `WorkspaceTools`/`build_server` accept
+  `terminal_primer` / `python_primer`: embedder guidance appended to the
+  respective tool's description (e.g. "`db` is a SQLite store — use it,
+  not `cache`, for shared state"). Strict 1-to-1 with the exposed tools;
+  a `python_primer` in terminal-only mode lands in the terminal tool's
+  `python` section (with a warning).
+
+- **Faithful `sys` in terminal `python`** — piped input reaches the code
+  as `sys.stdin` (`cat data | python script.py`), and `sys.argv` /
+  `input()` work, via sandtrap's synthetic safe `sys`. No `import`
+  quoting workarounds; dangerous `sys` internals stay unreachable.
+
+### Added
+- **Workspace extension surface: `exec_python` / `build_sandbox` /
+  `lock`.** A small, documented contract for embedders composing
+  execution features on top of the workspace: `exec_python(code, *,
+  inputs, sandbox, cache, stdin, argv)` is the raw execution path (no
+  checkpoint, no lock; `cache=` overrides the agent-visible cache —
+  the old private `_UNSET` sentinel is gone); `build_sandbox(*,
+  timeout, tick_limit, extra_classes, filesystem)` mints per-purpose
+  sandboxes sharing the frozen config, memoizing the built `Policy`
+  per parameter set so a fresh sandbox per request is cheap; `lock`
+  exposes the single-writer RLock for host/extension work that must
+  serialize with tool calls. The apps extra now talks exclusively to
+  this surface (no private attribute access — enforced by a test), so
+  it runs unchanged on any `WorkspaceProvider`; frozen serving's
+  per-request policy rebuild (a latency + DoS-amplification papercut
+  on the anonymous path) is fixed by the memo; mutable (authoring)
+  dispatch now serializes under the workspace's own lock, so test_app
+  route callbacks and screenshot writes can't race ordinary tool
+  calls.
+
+### Added
+- **`--apps` flag on the MCP CLI.** `python -m nontainer.adapters.mcp
+  --apps` enables the apps loop without writing an embed script: the
+  `curl` terminal builtin plus a `test_app` tool whose screenshots
+  return as MCP image content. Previously test_app over MCP required
+  calling `build_server(ws, apps=...)` from Python.
+
+### Changed
+- **Workspace enforces its single-writer invariant internally.**
+  Mutating public calls (`terminal`, `run_python`, `write_file`,
+  `edit_file`, `put`, `checkpoint`, `restore`, `rollback`, `discard`,
+  `fork`, `close`) hold an internal `RLock`, so a harness that threads
+  parallel tool calls onto one session serializes safely — each call
+  atomic + checkpointed — instead of corrupting staged state. Custom
+  harnesses no longer need to supply their own lock (the adapters keep
+  theirs as a fence for adapter-level work). Read-only accessors stay
+  lock-free; host-side escape hatches (`ws.fs` writes, `ws.cache`
+  mutation) bypass the lock and remain the caller's concurrency
+  problem. RLock so a `host_object` that calls back into the public
+  API serializes instead of deadlocking.
+- **stderr capture is per-execution, not a process-global redirect.**
+  `run_python` stderr now comes from sandtrap 0.2.4's ContextVar-routed
+  capture (`ExecResult.stderr`): concurrent executions — other sessions
+  in the same process, frozen app serving — no longer cross-contaminate
+  stderr or risk leaving `sys.stderr` pointing at a dead buffer. The
+  internal `capture_stderr` escape hatch is gone; served (frozen) app
+  handlers get stderr capture back. Sandboxed `sys.stderr` writes in
+  the terminal `python` builtin now surface as stderr instead of
+  leaking into pipeline stdout.
+- **Live app serving is now frozen (read-only) snapshots.** `build_router`
+  serves a Workspace pinned to a published commit: handlers read the VFS
+  and call `host_objects` but can't mutate it (write → 500). This makes
+  serving **concurrent** (fresh read-only sandbox per request, no
+  per-session lock, no staged buffer, no checkpointing) and lossless to
+  evict. Mutable app state belongs in an external store via
+  `host_objects`. Removed: per-session serialization, quiesce
+  checkpointing, `queue_depth`/`quiesce_seconds`. Added: `max_snapshots`,
+  `on_log` (handler logs route off the read-only VFS; default: the
+  `nontainer.apps` logger). `AppRuntime(..., frozen=True, log_sink=...)`.
+  The router is **stateless** — `resolve → dispatch`, no snapshot cache,
+  no residency/lifecycle (cache inside `resolve` if it's expensive; the
+  router doesn't close its result). Rate limiting is an edge concern;
+  `rate_limit_per_min`/`max_snapshots`/`queue_depth` are gone.
+
+### Fixed
+- **`test_app` accepts a stringified actions list.** Models routinely
+  send the nested list as a JSON string; the pydantic layer agno wraps
+  entrypoints in rejected it on the annotation before the existing
+  `coerce_actions` tolerance could run. The annotation is loosened so
+  coercion gets its chance.
+- **Agent-set response headers are matched case-insensitively.**
+  `normalize()` lowercases `Response.headers` keys on the way to the
+  wire, so the idiomatic `"Content-Type": "text/csv"` overrides the
+  inferred content type instead of being silently ignored, and an
+  agent-set `Content-Security-Policy` makes the served router defer
+  its default instead of emitting a duplicate header (browsers apply
+  the intersection). `WireResponse.headers` keys are now canonical
+  lowercase.
+- **`Request.require()` coerces symmetrically across sources.** JSON
+  has one number type, so `require("x", float)` accepts JSON `5` and
+  `require("n", int)` accepts `2.0` (non-integral floats still 400);
+  bools are never numbers (JSON `true` no longer passes an `int`
+  check); JSON strings coerce like query params; and query-param bools
+  parse `true/1/false/0` instead of Python's `bool("false") is True`.
+- **Screenshot cap no longer aborts the test.** A `test_app` action
+  hitting `max_screenshots` is a noted soft skip (`ok`, with a
+  "skipped: screenshot cap reached" note) instead of a hard failure
+  that discarded every later action — asserts after the cap now run
+  and count.
+- **Handler-log failures warn instead of going silently blind.**
+  `_log` still never breaks dispatch, but a broken/full fs (or a
+  raising `on_log` sink) now emits one `RuntimeWarning` per runtime —
+  previously every handler diagnostic vanished while the agent's
+  documented repair loop ("tail `/app/logs/api.log`") debugged blind.
+- **`test_app` false-PASS window closed (as far as heuristics can).**
+  `read` now settles before observing, so a fetch that *starts* after
+  the previous action's settle returned (debounce, `setTimeout`) is
+  waited for instead of read as stale DOM. And a settle that exits via
+  its cap (`settle_cap`, default 5s — now a `test_app` parameter)
+  attaches a stale-risk note to the action's result instead of
+  silently passing, pointing the agent at `{"assert": ...}` — the
+  retrying form no heuristic can replace, since nothing can wait for a
+  fetch that hasn't started yet.
+- **Browser shutdown no longer stalls interpreter exit.** The shared
+  test_app browser's atexit teardown deadlines dropped from 10s+5s to
+  3s+2s — a healthy Chromium closes in milliseconds, and a wedged one
+  isn't worth holding process exit for. `configure_browser` now
+  documents its process-global, first-caller-wins contract.
+- **App static serving path traversal** — `.`/`..` segments can no
+  longer escape `/app/`, and backend source under `/app/api/` is never
+  served as a static file.
+
+### Changed
+- Requires **sandtrap ≥ 0.2.4** (per-execution stderr capture;
+  recursive-registration filter propagation, dotted patterns,
+  synthetic `sys`/stdin) and **monkeyfs ≥ 0.1.5**
+  (`VirtualFS.invalidate()`).

nontainer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Ashenfelter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nontainer-0.1.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: nontainer
+Version: 0.1.0
+Summary: A fake little computer for your agent: versioned filesystem, shell, and sandboxed Python.
+Project-URL: Homepage, https://github.com/ashenfad/nontainer
+Project-URL: Documentation, https://github.com/ashenfad/nontainer#readme
+Project-URL: Bug Tracker, https://github.com/ashenfad/nontainer/issues
+Project-URL: Source, https://github.com/ashenfad/nontainer
+Author: ashenfad
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,sandbox,terminal,versioning,workspace
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: kvgit[disk]>=0.3.1
+Requires-Dist: monkeyfs>=0.1.5
+Requires-Dist: reprobate>=0.1.1
+Requires-Dist: sandtrap>=0.2.8
+Requires-Dist: termish>=0.1.8
+Provides-Extra: agentfs
+Requires-Dist: agentfs-sdk>=0.6; extra == 'agentfs'
+Provides-Extra: agno
+Requires-Dist: agno>=1.0; extra == 'agno'
+Provides-Extra: apps
+Requires-Dist: anyio>=4; extra == 'apps'
+Requires-Dist: playwright>=1.40; extra == 'apps'
+Requires-Dist: starlette>=0.37; extra == 'apps'
+Provides-Extra: dev
+Requires-Dist: httpx2; extra == 'dev'
+Requires-Dist: matplotlib; extra == 'dev'
+Requires-Dist: numpy; extra == 'dev'
+Requires-Dist: pandas; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# nontainer 📦
+
+A fake little computer for your agent: versioned filesystem, shell, and
+sandboxed Python -- as tools for any Python-based agent harness. No Docker,
+no cloud sandbox, no infra. `pip install nontainer`.
+
+> **Status: pre-alpha.** Usable and tested end to end; the API will still
+> move before 1.0.
+
+## The pitch
+
+You hand your agent a `terminal` and a `run_python` tool. Unlike a
+stateless sandbox call, these 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. It's a little computer the
+agent keeps *using* -- not a fresh box each call.
+
+And because that computer is a **versioned workspace**, you get the
+operations durable state makes possible: checkpoint every call, fork a
+session in O(1), roll back to any commit, audit the history. All in-process,
+`pip`-installable, running wherever Python runs.
+
+| | |
+|---|---|
+| **Terminal tool** | ~33 shell builtins (grep, sed, jq, tar, ...) over the virtual filesystem via [termish](https://github.com/ashenfad/termish). |
+| **Python tool** | Policy-gated sandboxed execution via [sandtrap](https://github.com/ashenfad/sandtrap); safe stdlib on by default, `open()`/`os`/`pathlib` routed to the workspace via [monkeyfs](https://github.com/ashenfad/monkeyfs). |
+| **In-process** | Agent code can call *your* whitelisted host objects -- the live model, the db pool -- under policy. No cloud sandbox can. |
+| **Pluggable substrate** | [kvgit](https://github.com/ashenfad/kvgit) (versioned), [AgentFS](https://github.com/tursodatabase/agentfs), or a plain directory -- same tools. |
+| **Thin adapters** | [agno](https://github.com/agno-agi/agno) toolkit and an MCP server over one core. |
+
+> **What the sandbox is (and isn't).** In-process, the Python sandbox
+> ([sandtrap](https://github.com/ashenfad/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. When you need a real boundary
+> (untrusted code, or serving to anonymous clients), escalate with
+> `isolation="process"` / `"kernel"`. Full framing in the
+> [design notes](docs/design.md).
+
+## The API in one glance
+
+```python
+from nontainer import workspace
+
+ws = workspace("user-42")            # versioned; a kvgit branch per session
+
+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.checkpoint                 # commit id this call produced; ws.restore(it) undoes it
+fork = ws.fork("what-if")    # O(1) branch; the original is untouched
+ws.rollback(steps=1)         # or time-travel by steps
+```
+
+Adapters are one import away:
+
+```python
+from nontainer.adapters.agno import WorkspaceTools   # agno Toolkit
+# or:  python -m nontainer.adapters.mcp --session s1  # MCP server (stdio)
+```
+
+## Substrates
+
+`WorkspaceProvider` is the pluggable seam -- one filesystem-and-KV protocol,
+**capability flags** instead of pretended equivalence:
+
+| Provider | versioned | `cheap_fork` | `sql_audit` |
+|---|---|---|---|
+| kvgit (default) | ✅ | ✅ O(1) | ❌ |
+| plain dir | ❌ | ❌ | ❌ |
+| AgentFS (spike) | ❌ | ❌ | ✅ |
+
+kvgit for fork/undo/audit, `dir` when agent code needs real files (C
+extensions, subprocesses), AgentFS for the one-file-artifact + SQL story --
+or bring your own provider. Full guidance in the [API reference](docs/api.md).
+
+## App handlers (the `[apps]` extra)
+
+Agents author full-stack apps: a Preact/HTM frontend plus **request
+handlers** -- serverless semantics, not resident servers. A file's path is
+its route (`/app/api/scores.py` → `/api/scores`), its exported `get`/`post`
+are the verbs. The agent builds and verifies entirely in-loop: a `curl`
+builtin hits the dispatcher from the terminal, and `test_app` runs the app
+headlessly through Playwright with the workspace as the origin -- no server,
+no Node. To share it, publish a **frozen snapshot**: `build_router` serves
+the app read-only and concurrently at `/apps/{token}/...`; mutable app state
+lives in an external store injected via `host_objects`, not the (frozen)
+workspace.
+
+Full design -- handler contract, execution model, test_app DSL,
+serving/threat model: [docs/apps.md](docs/apps.md).
+
+## 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](https://github.com/pydantic/mcp-run-python)** (Pydantic):
+  the incumbent local run-python (Pyodide-in-Deno). Stateless per call, no
+  workspace, needs Deno.
+- **[AgentFS](https://turso.tech/blog/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](https://www.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](https://github.com/ashenfad/kvgit),
+[monkeyfs](https://github.com/ashenfad/monkeyfs),
+[termish](https://github.com/ashenfad/termish), and
+[sandtrap](https://github.com/ashenfad/sandtrap) -- each independently
+useful, each zero/minimal-dep. [agex](https://github.com/ashenfad/agex) is
+the full agent framework over the same substrate; nontainer is the
+environment layer alone, offered to someone else's loop.
+
+## Documentation
+
+- [Quick Start](docs/quick-start.md) -- first workspace, sandbox config,
+  backends, adapters, the apps loop; runnable examples
+- [API Reference](docs/api.md) -- every class, method, and flag
+- [Design notes](docs/design.md) -- why it's shaped this way (execution
+  model, commit granularity, tool exposure) and what's still ahead
+- [Apps design](docs/apps.md) -- handler contract, execution model,
+  test_app, serving/threat model
+- [Examples](examples/) -- live agno agents: a data analyst
+  (`analyst.py`) and a build-and-verify web app (`webapp.py`)
+
+## Install
+
+```bash
+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)
+```
+
+## License
+
+MIT