Skip to content
Workbox
Get started

One host. Many boxes. Each its own world.

Spin up isolated Linux sandboxes on any modern host. No hypervisor, no container runtime.
Get startedArchitecture

Five layers make one box.

  1. 05

    Agent processes

    PID 2 and below

    The runner and every session, in private namespaces.

  2. 04

    Run directory

    /run/workbox

    Where runner.sock lives. The host token never does.

  3. 03

    Runtime

    /opt/workbox · read-only

    Node and wb, checksummed, mounted read-only.

  4. 02

    Private overlay

    sandboxes/<id>/upper

    The one writable layer, invisible to the host mount table.

  5. 01

    Shared rootfs

    rootfs/<name> · read-only

    Built once, shared read-only by every box.

Hard limits from the first instruction.

2GiB
Memory
0swap
Swap
2cores
CPU
4,096pids
Processes

Every state, on the record.

REQUESTED
PROVISIONING
BOOTSTRAPPING
READY
DRAINING
DELETING
DELETED

from PROVISIONING, BOOTSTRAPPING, READY, DRAINING or DELETING

QUARANTINED
01 / 07

REQUESTED — Stored, with a time and a reason.

Live health

  • HEALTHY

    Channel up, network in place.

  • SUSPECT

    Alive, not whole.

  • UNKNOWN

    Not yet observed.

  • ABSENT

    The cgroup is empty.

Every boot is verified.

  1. Host

    Says hello with the host token.

    01runner.hello · role host + token

    Runner

    Checks its digest. One control peer.

  2. Host

    Consumes the nonce. A replay quarantines.

    02boot nonce

    Runner

    Hands over the single-use nonce.

  3. Host

    Starts the proxy, slirp4netns and nftables.

    03BOOTSTRAPPING

  4. Host

    Sends runner.go.

    04runner.go

    Runner

    Runs its self-checks.

  5. Host

    Compares them with the launch.

    05self-checks

    Runner

    Reports uid map, capabilities, seccomp.

  6. Host

    Match: READY. Mismatch: QUARANTINED.

    06READY or QUARANTINED

  7. Host

    Polls cgroup health from then on.

    07health poll

Nothing runs until the box proves who it is.

Output that outlives the connection.

Disconnect, reconnect, and pick up exactly where you left off.

ReplayDetachedInteractive PTY

8 MiB

ring spool

seq 13–40

Restart the daemon. The boxes stay up.

attached
Still running. Reconnected.
suspect
Alive, not whole.
absent
Gone. Never relaunched.
quarantined
Boot not proven.
operator — reconcile on demand
# admin scope
$ curl -sS -X POST http://127.0.0.1:8790/v1/reconcile \
    -H "Authorization: Bearer $WORKBOX_TOKEN"

Everything in one place.

/var/lib/workbox

/sys/fs/cgroup/workbox/<id> · one cgroup per sandbox

sandboxes/<id>/

One sandbox

upper, work, merged, run, launch.log and host-token.

Eight packages. Zero build steps.

protocol

in every box

NDJSON framing and schemas.

core

The engine.

runner

in every box

The in-box supervisor.

wb

in every box

The agent’s command.

server

REST and WebSocket.

sdk

The JavaScript client.

mcp

The stdio MCP server.

cli

The operator CLI.

See what the agent sees.