Sandboxes · shells · files
Remote code execution, with the containment as the product.
It creates isolated workspaces, runs shells in them, reports what is running, and lets an assistant kill or wait on it. This service executes arbitrary commands for remote callers, so the sandbox is the feature, not polish.
POST /v1/environments {"name": "scratch"}
POST /v1/exec {"environment_id": "env_…", "command": "uname -a"}
GET /ready the active sandbox tier, and whether tokens verify
# tiers, strongest the host allows:
directory -> user -> namespaceHow it works
Environments survive restarts. Shells do not, and the API says so.
It authenticates against keyring. Read the security guide before deploying it.
Environments
Several per account and profile, bounded by quotas; a 409 names the limit. Each is a folder that survives a restart.
Shells and commands
Concurrent persistent shells per environment. Commands are framed with a random nonce so exit codes can be trusted, and exec with wait_ms returns fast results in one call.
A reaper
It closes idle shells, archives idle environments and prunes logs. With settings-api configured, each person's idle lifetimes are honoured.
The API
Workspaces, shells, processes and files.
The reference, with every error code, is docs/api.md.
Environments
Create, list, inspect, reset and delete isolated workspaces, with usage against their limits.
Run a command
One call that runs a command and waits up to wait_ms for it.
Persistent shells
Open several per environment, write to them, read their output, and wait on a command.
What is running
Live PIDs with state, memory and CPU; signals are checked for ownership.
The files API
List, read, search, write, exact edit, patch, mkdir, delete, copy and move, with ETag and If-Match.
Readiness
The active sandbox tier, and whether tokens verify; 503 until keyring's keys can be fetched.
Run it
Four commands.
You need Python 3.12 or newer and uv. make run listens on every interface; bind it to 127.0.0.1 on a shared network.
- Install.
make install - Point it at keyring.
cp .env.example .env - Serve it on :8008.
make run - Ask which sandbox tier is active.
curl localhost:8008/ready
Without a keyring to hand, uv run python scripts/dev_keyring.py serves a stand-in that mints tokens, and make smoke drives the whole API against it.
Read before deploying
Read this before deploying it.
What is this, in security terms?
Remote code execution as a product. The sandbox tiers, path containment and PID-ownership checks are the feature. Read the security guide before deploying it.
How strong is the sandbox?
As strong as the host allows, found by real probes rather than trusted configuration: directory, then user, then namespace. The active tier is reported on /ready, and ENVAPI_MIN_SANDBOX_TIER refuses to start below the one you require.
Can a command reach the network?
Only where the deployment allows it. With ENVAPI_ALLOW_NETWORK=false, asking for the network is refused.
What happens to credentials a command needs?
Keyring credentials are injected per command and redacted from its output.
Docs
Written for the person who has to run it.
Security
The threat model, and what each control is for.
Sandbox tiers
How each tier is detected and what it isolates.
The HTTP contract
Every route and error code.
Operations
Every setting, quota and the reaper.
Architecture
The layout, and why it is shaped that way.
Assistant tools
The operations as an assistant would be offered them.