@amond-ai/sandbox-local
v0.2.0
Published
A local-process backend for @amond-ai/sandbox — runs the command on this machine and journals it to disk, so a desktop app that was killed and relaunched can still find the turn it started
Maintainers
Readme
@amond-ai/sandbox-local
A local-process backend for @amond-ai/sandbox: the command runs on this
machine, in a directory named after the sandbox id.
import { createLocalProvider } from '@amond-ai/sandbox-local'
const provider = createLocalProvider({ root: `${Deno.env.get('HOME')}/.myapp/sandboxes` })
const session = provider.session(sandboxIdForRun(runId))It exists for the desktop case. e2b works from a desktop app, but every turn ships the user's workspace to a remote host, needs an account and an API key, and turns an offline-capable app into one that fails without network — which inverts the design of an app whose whole premise is local files. Docker gives real isolation and is the honest answer for a server, but it is a prerequisite the user has to install and keep running, and it does not help the offline case any more than a local process does.
This is not a sandbox
The name is the contract's, not a claim about this backend. There is no filesystem boundary,
no network policy and no resource limit. A command started through exec can read and write
anything the user can, reach the network, and use the whole machine.
What the backend does do is narrower, and worth stating exactly so nobody assumes the rest:
- paths passed to
readFile/writeFile/mkdir/existsand toexec'scwdare resolved inside the sandbox directory, and a leading/means the sandbox's root rather than the machine's — soreadFile('/etc/passwd')reads the sandbox's copy or nothing at all. That is a path mapping, so that callers written against container-absolute paths keep working; it does not follow symlinks, and it constrains nothing a running command does; - the sandbox directory the provider created is the only tree
destroy()will remove.
For the desktop case this is acceptable, because the code and the machine belong to the same person. On a server it is not a security boundary, and reaching for it as one is the mistake this section exists to prevent.
What it costs to run a turn
This backend installs nothing, and a turn needs the turn host on the machine itself. The
driver execs node /opt/turn-host/bridge.mjs, and exec passes a command's arguments through
as written — only cwd and the file operations map a leading / into the sandbox — so the
bundle and its Agent SDK have to be installed at that path, as
@amond-ai/harness-claude-code-bridge
describes for an image. The SDK brings its own claude binary. A command inherits the
orchestrator's own environment by default — that is how PATH finds node, and it is one more
way this is not a sandbox. Pass env to narrow it.
Where things live
<root>/
<sandboxId>/ the working directory, when the provider owns it
.state/
<sandboxId>/
.nonce what this sandbox's wrappers are recognised by
<processId>.out stdout, as the wrapper redirected it
<processId>.err stderr
<processId>.pid the command's own pid, for aiming a signal
<processId>.exit $?, written by the wrapper after it waits
<processId>.timeout present when the wrapper's own watchdog killed the command
<processId>.meta.json the process recordThe bookkeeping never lives inside the working directory, which is what lets the two be owned
separately — and what keeps anything shared between sandboxes (a bootstrap, a package store, a
bridge bundle) safe from a destroy(). Nothing removes <root> or <root>/.state.
| Option | Default | What it decides |
| --- | --- | --- |
| root | (required) | Where the provider puts the sandbox directories it owns. |
| stateRoot | <root>/.state | Where the journals and process records go. |
| resolveRoot | (unset) | Name the working directory yourself — and keep it; see below. |
| env | the orchestrator's own | The environment a command starts with. |
| host | the Node builtins | The host primitives, for a runtime that needs its own binding. |
| loopbackHost | 127.0.0.1 | The address portEndpoint answers with. |
Ownership, and what destroy() removes
By default a sandbox id resolves to <root>/<id>, the provider created it, and destroy()
removes it. Pass resolveRoot when the app already has a workspace layout:
createLocalProvider({ root, resolveRoot: id => workspacePathFor(id) })The provider then stops owning that directory. destroy() still ends the sandbox's processes
and still removes the provider's own state for it, and it does not delete a tree it was merely
pointed at. The decision is taken at resolution rather than argued about at deletion, so the
dangerous case cannot be reached by getting one line wrong.
Finding a process after the app was quit
A desktop app is killed and relaunched far more casually than a worker is evicted, and the
contract requires getProcess/listProcesses to answer about a sandbox this process may never
have started. Three things make that work, and each is a decision rather than a detail:
- The exit code is written by the shell, not by the parent. A host-side
'exit'listener is the obvious implementation and it is wrong in exactly this case: quit the app mid-turn and nothing is left to observe the exit, so a turn that finished perfectly comes back asSandboxNoExitRecordError. The wrapper records$?from inside the tree. - Liveness is verified, never inferred from the record. Pids are reused, so the pid alone
is not an answer. What identifies a process is the wrapper's own marker in its command line
— which carries a nonce minted once per sandbox and kept in its state directory, because
every other part of that marker is public and
destroy()signals the process group of whatever recovery claims; the kernel's start time is the fallback for a host that cannot report one. That ordering is deliberate —ps -o lstartresolves to a whole second on both supported platforms, so a pid recycled inside that second compares equal, and there is no portable finer clock (/procis Linux-only). A row whose command line is unreadable falls back to the time rather than to a verdict: truncated argv is not evidence of a stranger, and calling a live turn dead is the expensive mistake. macOSpsprints(bash)for a live wrapper whose arguments it momentarily failed to read, so that stand-in counts as unreadable, and recovery reads such a row again before passing over it. A process this check cannot confirm is never signalled.killreports the non-delivery and leaves the caller's bounded wait to escalate, asSandboxProcessHandle.killrequires. - A process is over when its group is empty, not when the wrapper exited. A command that detaches a child and returns leaves that child writing to the checkout, and a caller told "finished" starts a second one beside it.
A timeout on exec is enforced by the wrapper too, for the same reason as (1): a host-side
timer would quietly stop existing the moment the app was quit. It asks with SIGTERM, escalates
to SIGKILL after a grace period so a command that ignores the ask cannot outlast its deadline,
and — only on a timeout — ends what the command left running in the wrapper's process group.
Without that last step the deadline would bound nothing: sh -c 'sleep 300 & wait' answers
SIGTERM with exit 143 while its child keeps running, and a process group that is not empty is a
process this backend correctly reports as still alive.
The nonce authenticates against coincidence, not against a local attacker: it is in the
wrapper's command line, so anything on the machine that can run ps can read it and reproduce
it. That is the same bar the rest of this package holds — a command here runs unconfined with
the orchestrator's environment — and what it closes is the case that was actually reachable, a
process that reproduces the marker without trying to. Delete .nonce and recovery claims
nothing at all: an orphan that could once have been ended is lost, which is the cheaper of the
two mistakes available at that point. A process that still has its record is not called dead on
that evidence either: a row shaped like its own wrapper but carrying the wrong nonce reads as
unknown, so destroy() refuses rather than signalling it or deleting the state.
Upgrading from a release without the nonce. Wrappers that an earlier release spawned carry no nonce, so this release does not recognise them. A turn whose record survives the upgrade falls back to its kernel start time where one was pinned, and otherwise reads as unknown. It is neither killed nor cleaned up. A turn whose record is already gone cannot be recovered at all. Let running turns finish, or stop them, before you upgrade.
One limit worth knowing before you rely on recovery: a process found through the process table
rather than through its record carries the argv as the process table renders it, and ps
escapes a newline in an argument as \012. A multi-line prompt recovered that way is not
byte-identical to the one that was spawned. Carrying an encoded copy in the wrapper's own
command line would fix it and double the largest thing in that command line, against a 256KB
ARG_MAX on macOS — so it is a stated limit rather than a hidden one. It costs nothing in the
ordinary case: a process that still has its record is read from the record.
Ports are not per-sandbox
portEndpoint answers http://127.0.0.1:<port> — the port is on the machine that is asking,
so there is nothing to look up and no round trip to pay. There is also nothing to isolate: two
sandboxes that both bind 3000 collide, and the second fails to bind rather than getting its own
3000 the way a container would. A consumer running concurrent sandboxes has to allocate ports
itself.
Unlike the e2b backend, the scheme a caller asks for is the scheme it gets. e2b upgrades http
and ws because its ports are reached across the internet through a TLS edge and a plaintext
endpoint does not exist there; a loopback port has no edge, so upgrading could only hand back a
URL that provably cannot be dialed.
POSIX only
Process groups, signal numbers and ps all mean something specific here, and Windows has no
equivalent for any of the three. macOS and Linux are supported; the real-machine suite
(src/local.real.test.ts) skips itself elsewhere rather than pretending. The filesystem under
stateRoot must support hard links, because .nonce is published with link(2); on one that does
not (exFAT, some SMB and FUSE mounts) the first exec fails rather than running without a nonce.
src/node-host.ts is the only shipped module that imports a node: builtin, and it uses
specifiers rather than any one engine's API, so it runs on Node, Bun and Deno alike. Everything
else in the package is written against the structural LocalHost surface it satisfies — which
is what makes pid reuse, a lost record and an orphaned child testable at all, and what
closure.test.ts asserts on every run. The real-machine suite is the exception the qualifier
is for: src/local.real.test.ts imports node:fs/promises, node:os, node:path and
node:process to build the temp directories it drives a real /bin/sh in. It is a test, so
closure.test.ts never scans it — the claim above is about what a consumer installs.
