feat: hibernate idle sessions, and a runtime built for coding agents (#76)

* feat: hibernate idle sessions instead of closing them

At the ceiling, sandboxd closed the least recently used idle session:
its container went, and so did its token, its event log and the
caller's ability to come back to it. Eviction now gives up only the
sandbox. The record stays, `GET /sessions` reports it as
`state: "hibernated"`, and the next request wakes it where it left off.

That splits one number into two, which is the point. `max_sessions`
now bounds resident sandboxes -- the RAM number -- while the new
`max_open_sessions` bounds sessions that exist at all, resident and
hibernated together, which is a disk number and properly much larger.
On a 4 GB host that is ten resident against a couple of hundred open.

Also here:

- `memswap_limit` on DockerSandbox, SandboxRuntime and SandboxdConfig.
  Swap stays pinned to `mem_limit` by default, which is right when
  swap is a disk; raising it is for hosts backed by zram, where the
  pages stay in RAM compressed and the alternative is an OOM kill.
- scripts/bench_density.py, which measures on the host being sized
  what no blog post can: marginal MemAvailable per session, per
  container management overhead, time to first command, and wake
  latency from hibernation.
- The reasoning, in docs/plans/sandbox-density-on-small-hosts.md,
  including a correction to the earlier runtime-alternatives note:
  microVMs buy isolation, not density, and lose badly under a hard
  memory ceiling.

Three things this uncovered on the way. `sweep_workspaces` would have
deleted a hibernated session's workspace, since its keep-set came from
the manager alone. `SessionManager.release` returns False for a session
it does not hold, so `on_release` never fires and `close_session` has
to drop the records itself. And a purge of a hibernated session left
its persisted container behind, there being no sandbox object to stop.

* feat: a runtime built for coding agents, and two bugs it exposed

Measured rather than reasoned about, on Docker 29.2.1. Running the
sandbox the way an agent uses it turned up two things that were broken
before any tuning, both hitting the tool a coding agent reaches for
most.

Every orphaned process was a permanent zombie. Containers run
`sleep infinity` as PID 1, and `sleep` never calls `wait()`, so a
backgrounded server or anything the command timeout killed was
reparented to it and stayed. Measured: ten orphans, ten zombies, and
the process table growing 4 -> 13. They accumulate against
`pids_limit` until every command in the session fails to fork. Docker's
`init` reaps them for 488 kB.

git refused to work in the workspace. `workspace_root` bind-mounts a
host directory the container does not own, so every git command failed
with "detected dubious ownership" -- status, diff, log, commit alike --
and past that a commit failed again with "Author identity unknown". An
agent asked to save its work could not. Configured now through
`GIT_CONFIG_*` on the container rather than in an image, which is what
makes it reach the ready-made runtimes that build nothing of their own.

The runtime itself, `coding`, is 99.7 MB and eleven seconds to build.
`git` is 33.1 MB of that and unavoidable; ripgrep, fd, jq, less and
procps come to 4.3 MB between them, which is not a saving worth making
-- without `rg` an agent falls back to `grep -r` and floods its own
context, and without `procps` it has no way to see or stop the server
it just started. `build-essential` is refused at 94 MB to compile
wheels manylinux already ships built, and the base stays Debian slim
because on musl a package without a musllinux wheel builds from source.

`uv` is there because an agent installs packages inside somebody's
turn: 8485 ms -> 1169 ms for pandas. The surprise was at the ceiling --
uncapped, uv is OOM-killed by a 128 MB limit that pip survives, because
its parallelism is memory. Capped at two it fits, and is still 6.6x
faster than pip.

Also here: `polyglot` gets npm 10, since Debian ships a current Node
with an npm a major version behind; and `default_runtime` now takes the
first entry in `runtimes` rather than the literal alias "python", which
had forced every custom allowlist to contain that key.

Reasoning and the full measurements in docs/plans/coding-agent-runtime.md.

Author: DEENUU1

CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **`SandboxdConfig.default_runtime` defaults to the first entry in `runtimes`** rather than to the literal alias `"python"`. The old default meant every custom allowlist had to contain a key named `python` or the config refused to construct, which is a coupling nothing asked for. The shipped allowlist lists `coding` first, so that is what a default service now hands out; naming an alias explicitly still wins, and naming one that is not allowed is still refused.
+
+### Fixed
+
+- **An agent can use git in its sandbox.** Every git command in a bind-mounted workspace failed with `detected dubious ownership`, because the directory belongs to whoever the service runs as and the container does not — measured on `status`, `diff`, `log` and `commit` alike. Past that, a commit failed again with `Author identity unknown`. Both are now configured through `GIT_CONFIG_*` on the container, which is what makes it reach the ready-made runtimes (`bun`, `deno`, `go`, `rust`) that build no image of their own.
+- **A long-lived session no longer runs out of processes.** Containers run `sleep infinity` as PID 1, and `sleep` never calls `wait()` — so every process an agent orphans, a backgrounded server or anything the command timeout kills, was reparented to it and stayed a zombie for the life of the container. Measured: ten orphans, ten permanent zombies, accumulating against `pids_limit` (512) until every command in the session failed to fork. Containers now start with Docker's `init`, which costs 488 kB and reaps them.
+
+### Added
+
+- **An evicted session is hibernated rather than closed.** At the ceiling, `sandboxd` used to close the least recently used idle session: its container went, and so did its token, its event log and the caller's ability to come back to it. It now gives up only the sandbox. The record stays, `GET /sessions` reports it as `state: "hibernated"`, and the next request wakes it where it left off — measured at 0.09 s for a persisted container. Nothing a client holds stops being valid.
+- **`SandboxdConfig.max_open_sessions`**, which is the point of the above. `max_sessions` now means *resident* sandboxes — the number the host's RAM has to hold — while `max_open_sessions` bounds the sessions that exist at all, resident and hibernated together, which is a disk number and properly much larger. On a 4 GB host that is ten resident against a couple of hundred open. At the open ceiling the longest-asleep session is closed for good; with every open session in use, the caller gets `429`. A hibernated session is ended by `idle_timeout` like any other.
+- **`memswap_limit` on `DockerSandbox`, `SandboxRuntime` and `SandboxdConfig`.** Swap is still pinned to `mem_limit` by default, because a container swapping to a disk starves every other one on the host. That is the wrong trade where swap is `zram`: the pages stay in RAM compressed at roughly 3:1, and the alternative to a little swapping is an OOM kill mid-command. Set it above `mem_limit` there and nowhere else.
+- **A `coding` runtime, and it is the shipped default.** Python with git, ripgrep, fd, jq, less, procps and `uv` — 99.7 MB, eleven seconds to build, measured. `git` is 33.1 MB of that and unavoidable; the five tools an agent looks at a codebase with come to 4.3 MB between them. `build-essential` is deliberately absent at 94 MB to compile wheels manylinux already ships built. It is the first entry in `DEFAULT_RUNTIMES`, with `python` and `node` staying beside it as ready-made fallbacks for a host that cannot reach a Debian mirror.
+- **Every sandbox starts with a working environment**, applied at the container so it reaches images we did not build: `PYTHONUNBUFFERED` so a command killed by the timeout still returns what it printed, `NO_COLOR` and `PAGER=cat` so escape sequences do not fill the model's context, `LANG=C.UTF-8` because `node:20-slim` ships no locale, and `UV_CONCURRENT_DOWNLOADS=2` — uv's parallelism is memory, and uncapped it is OOM-killed by a 128 MB ceiling that pip survives, where capped it fits and stays 6.6× faster than pip. A runtime overrides any of it through its own `env_vars`.
+- **`polyglot` now carries npm 10.** Debian 13 ships a current Node (20.19.2 against `node:20-slim`'s 20.20.2) but an npm a major version behind, so the generalist runtime quietly behaved differently from the dedicated Node ones.
+- **`scripts/bench_density.py`**, which measures on the host being sized what no blog post can: marginal `MemAvailable` per session, per-container management overhead, time to first command, and wake latency from hibernation. Reasoning behind it in [`docs/plans/sandbox-density-on-small-hosts.md`](docs/plans/sandbox-density-on-small-hosts.md).
+
 ## [0.2.18] - 2026-08-01
 
 ### Added

docs/concepts/docker.md

@@ -64,6 +64,8 @@ sandbox = DockerSandbox(runtime=runtime)
 
 | Runtime | Image | What it adds |
 |---|---|---|
+| `coding` | built on python:3.12-slim | git, ripgrep, fd, jq, less, procps, uv |
+| `polyglot` | built on python:3.12-slim | Python and Node together, curl, git, numpy, duckdb, polars, httpx |
 | `python-minimal` | python:3.12-slim | standard library only |
 | `python-datascience` | built on python:3.12-slim | pandas, numpy, matplotlib, scikit-learn, seaborn |
 | `python-analytics` | built on python:3.12-slim | duckdb, polars, pyarrow |
@@ -82,6 +84,37 @@ A runtime naming an `image` starts as fast as a pull. One naming a `base_image`
 plus `packages` builds an image on first use and hits the cache afterwards, which
 is worth it when installing them per session would dominate.
 
+**`coding` is the one to reach for when the agent's job is code.** Measured at
+99.7 MB and eleven seconds to build: `git` is 33.1 MB of that and unavoidable,
+while `ripgrep`, `fd`, `jq`, `less` and `procps` come to 4.3 MB between them.
+`uv` is there because an agent installs packages inside its own turn — measured
+5–7× faster than pip on the same package set. What is deliberately absent is
+`build-essential`: 94 MB to compile wheels that manylinux already ships built.
+
+### What every sandbox gets, whatever its runtime
+
+Some settings are applied to the container rather than baked into an image, so
+they reach the ready-made runtimes too — `bun`, `deno`, `go` and `rust` build
+nothing, so a Dockerfile could never have carried them. A runtime overrides any
+of it through its own `env_vars`.
+
+- **git is configured through `GIT_CONFIG_*`.** Without it, every git command in
+  a bind-mounted workspace fails with `detected dubious ownership` — the
+  directory belongs to whoever the service runs as, and the container does not —
+  and a commit fails again with `Author identity unknown`. Both measured.
+- **An init process reaps orphans.** `sleep infinity` as PID 1 never calls
+  `wait()`, so a backgrounded server or anything the command timeout kills stays
+  a zombie for the life of the container. Measured: ten orphans left ten
+  permanent zombies, accumulating against `pids_limit` until the session could
+  not fork. The reaper costs 488 kB.
+- **Output stays readable**: `PYTHONUNBUFFERED` so a command killed by the
+  timeout still returns what it printed rather than an empty string, and
+  `NO_COLOR` / `PAGER=cat` so escape sequences do not fill the model's context.
+- **`uv` is capped at two concurrent downloads.** Its parallelism is memory:
+  measured installing pandas, uncapped uv is OOM-killed by a 128 MB ceiling that
+  pip survives. Capped it fits, and is still 6.6× faster than pip.
+- **`LANG=C.UTF-8`**, because `node:20-slim` ships no locale at all.
+
 ## SessionManager for Multi-User
 
 For web apps where each user needs isolated execution:

docs/concepts/remote.md

@@ -232,13 +232,18 @@ SandboxdConfig(
     token=token,
     runtimes=SUGGESTED_RUNTIMES,
     prewarm=True,  # build and pull the allowlist at startup, not on a request
-    persist_containers=True,  # a reaped session restarts instead of rebuilding
+    persist_containers=True,  # a woken session restarts instead of rebuilding
     tmpfs_size="64m",  # scratch writes stay in RAM, off the overlay
     cpu_shares=1024,  # weight rather than a hard cap, so idle cores get used
     cpus=None,
 )
 ```
 
+None of them moves the ceiling as far as separating resident sessions from open
+ones does — see [A working set, not a hard cap](#a-working-set-not-a-hard-cap),
+which is where the order-of-magnitude is. These four are what make each resident
+session cheap once that split is in place.
+
 **`prewarm`** pulls and builds the whole allowlist in the background as the
 service starts, sequentially so several builds do not fight over one small host.
 Without it the first session on a built runtime pays for the image — measured at
@@ -275,6 +280,45 @@ of the runtime, so every edit mints a new one and would otherwise leave a few
 hundred megabytes behind for good — an image still backing a running container is
 left alone.
 
+### What the host is worth, before any of the above
+
+Three changes outside this library, in descending order of megabytes recovered.
+None of them needs a code change here.
+
+**`crun` as the daemon's default runtime.** `runc` is Go, with a garbage
+collector and a supervising process per container; `crun` is the same interface
+in C. Reported at roughly twice the container-lifecycle speed and 30–40% less
+per-container overhead, which at a hundred sessions is a gigabyte the sandboxes
+get instead:
+
+```json
+{ "default-runtime": "crun", "runtimes": { "crun": { "path": "/usr/bin/crun" } } }
+```
+
+This is a different question from `oci_runtime`, which selects an *isolation
+model* per runtime alias. `crun` is a faster `runc`, not a different boundary, so
+it belongs in the daemon's own config where it applies to everything.
+
+**`zram`, and then `memswap_limit`.** A sandbox is denied swap by default —
+`memswap_limit` is pinned to `mem_limit` — because a container swapping to a disk
+starves every other one on the host. That reasoning does not hold when swap is
+`zram`: the pages stay in RAM compressed, idle Python heaps at roughly 3:1, and
+the alternative to a little swapping is an OOM kill mid-command. On a host with
+`zram` configured, and only there:
+
+```python
+SandboxdConfig(token=token, mem_limit="384m", memswap_limit="512m")
+```
+
+**One base image across the allowlist.** Read-only pages are shared between
+containers only when the layer is literally the same file. Runtimes built from
+one `python:3.12-slim` share the interpreter and the standard library; runtimes
+built from different bases share nothing. `SUGGESTED_RUNTIMES` is arranged this
+way — every Python entry on `python:3.12-slim`, every Node one on `node:20-slim`
+— and a custom allowlist is worth checking against the same rule. It is also the
+reason containers beat microVMs badly on a small host: a microVM caches those
+pages once per guest, so a hundred of them hold a hundred copies.
+
 ### The library matters more than the tuning
 
 Measured on one 188 MB CSV, the same `GROUP BY` in each:
@@ -362,33 +406,57 @@ sessions nobody is using: an agent is turned away while a hundred containers sit
 idle holding slots.
 
 `evict_idle_after` changes that. At the ceiling, the least recently used session
-idle for at least that long is closed to make room:
+idle for at least that long is **hibernated** to make room:
 
 ```python
 SandboxdConfig(
     token=token,
-    max_sessions=100,  # live sandboxes — the working set
+    max_sessions=10,  # resident sandboxes — what the RAM has to hold
+    max_open_sessions=200,  # sessions that exist — what the disk has to hold
     evict_idle_after=120,  # idle two minutes? your slot can be reused
     workspace_root="/var/lib/sandboxd",
     persist_containers=True,
 )
 ```
 
-With a workspace on disk, eviction costs the evicted session nothing but its
-container: its next request re-attaches, finds its files, and pays a container
-start — measured at 0.09 s for a persisted one. So the number of sessions that
-may *exist* becomes unbounded while the number *running at once* stays at 100.
+Hibernating is not closing. The container, the process supervising it and the
+memory both hold are given up; the session's token, its runtime, its event log
+and its files stay. Its next request wakes it, finds its work, and pays a
+container start — measured at 0.09 s for a persisted one. Nothing the client
+holds stops being valid, so it never has to learn that any of this happened.
+
+That splits one number into two, which is the point:
+
+- **`max_sessions`** bounds *resident* sandboxes. This is the RAM number: it
+  times the largest runtime ceiling is the worst case the host must survive.
+- **`max_open_sessions`** bounds sessions that *exist*, resident and hibernated
+  together. This is the disk number, and it is properly much larger. At the
+  ceiling the session that has been asleep longest is closed for good; with every
+  open session resident, the caller gets `429`.
+
+On a small host that gap is the whole design. Ten resident sessions at 384 MB is
+a machine that fits in 4 GB; two hundred open ones is what it can advertise.
+
+A hibernated session shows in `GET /sessions` with `state: "hibernated"` and
+`alive: false`, and as **asleep** in the dashboard. `idle_timeout` still ends it:
+a session asleep longer than that is closed on the next sweep, since one nobody
+came back to is one nobody is coming back to.
 
 Two deliberate limits on it:
 
 - **A busy session is never evicted.** Only sessions idle for at least
   `evict_idle_after` are candidates, because killing an agent's work to serve
   somebody else's first request is worse than making them wait. With every
   session genuinely busy the caller still gets `429` — backpressure is the honest
-  answer there, not an unbounded queue.
-- **It requires `workspace_root`.** Evicting a session whose files live only in
-  its container would discard them silently, so the configuration refuses rather
-  than making that trade quietly.
+  answer there, not an unbounded queue. Waking is subject to the same rule: a
+  hibernated session whose slot cannot be freed is answered `429` rather than
+  taking one from somebody working.
+- **It requires `workspace_root`.** Hibernating a session whose files live only
+  in its container would discard them silently, so the configuration refuses
+  rather than making that trade quietly.
+- **What does not survive is process state.** A hibernated session's background
+  processes — a dev server left running through the console toolset — are stopped
+  with the container. Files survive; a long-lived process does not.
 
 `max_sessions=None` removes the ceiling entirely, for hosts where something else
 does the bounding.
@@ -504,12 +572,15 @@ all needs to know why.
 
 ## Capacity and reaping
 
-- `max_sessions` caps concurrency; beyond it, opening a session answers `429`
-  rather than starting unbounded containers. `max_sessions_per_tenant` applies the
-  same ceiling per `tenant` label.
+- `max_sessions` caps *resident* sandboxes; beyond it, opening a session either
+  hibernates an idle one or answers `429` rather than starting unbounded
+  containers. `max_open_sessions` caps how many sessions exist at all, resident
+  and hibernated together. `max_sessions_per_tenant` applies a ceiling per
+  `tenant` label.
 - `idle_timeout` reaps sessions that have gone quiet, and the reaping is visible
   to the service's own bookkeeping — a reaped session's token and event log are
-  released with it.
+  released with it. It applies to hibernated sessions too, which the sweep ends
+  once they have been asleep that long.
 - `execute_timeout` clamps every command, so one client cannot occupy a worker
   indefinitely.
 - `workspace_ttl` sweeps workspaces no session has opened for that long, on the