Sandboxes and Drydock
Run commands and test a caisson's code on your own Linux machines or on Sailfork's hosted compute, with no clone.
What Drydock and sandboxes are
A Drydock host is a Linux machine with Docker that you or your organization runs. A sandbox is an isolated container on one of those hosts, running under gVisor. You use sandboxes to run commands, to test a caisson's code without cloning it, and your CI jobs run on them too.
Sandboxes run on hosts you register, which Sailfork does not charge for. With hosted compute turned on they run on Sailfork's hosts too, billed per second. A host dials out to Sailfork over a websocket, so it needs no inbound port and works behind NAT.
Hosts and sandboxes belong to an organization, or to you for your personal repositories. Everywhere this page says --org acme, your own handle (--org fenil) means your personal hosts.
Set up a host
An organization owner registers the host and gets a token. The token is shown once, so copy it before you leave the screen. Then you install on a Linux machine that has Docker.
# an organization owner registers a host and prints its token once
sailfork sandbox host add build-1 --org acme
# on the Linux machine with Docker and systemd
curl -fsSL https://sailfork.com/install/drydock | sh
sudo drydockd install --server https://sailfork.com --token <token>
# confirm the host is online
sailfork sandbox host list --org acme The installer adds gVisor (runsc) to Docker when it is missing and runs drydockd as a systemd service. In the web app, Settings, Drydock hosts shows the same two install lines, and an organization's own page is under its settings, Drydock hosts.
A host name is 1 to 64 letters, digits, ., _ or -, and an organization can register up to 50 hosts.
Run a command in a sandbox
Create a sandbox, run commands in it, and delete it when you are done.
sailfork sandbox create --org acme
sailfork sandbox exec <id> -- python3 --version
sailfork sandbox delete <id> create prints the sandbox id. exec streams the output and exits with the command's own exit code. One argument runs as a shell command line, and several arguments run as a program and its arguments. sandbox list shows your organization's sandboxes (--all adds stopped and failed ones), and sandbox view <id> shows one.
A sandbox stops by itself after 60 minutes unless you pass --minutes (1 to 1440). sandbox extend <id> <minutes> moves the stop time to that many minutes from now. exec kills a command after 120 seconds by default, and --timeout <secs> raises that to at most 3600. A command killed by the timeout exits 124.
Move files with sandbox put <id> <local> <remote> (a local file of at most 16 MiB, --mode in octal, missing folders created) and sandbox cat <id> <path>. Other exec flags are --cwd, --env KEY=VALUE (repeat for more) and --stdin-file.
To run a repository's code, start the sandbox with -R and optionally --ref. The code lands in /work, where exec runs by default.
sailfork sandbox create -R acme/app --ref main --image node:22
sailfork sandbox exec <id> -- npm test Run sailfork sandbox --help for the rest.
Test a caisson
caisson test runs a command on the caisson's code, its base plus uncommitted edits, in a throwaway sandbox. It destroys the sandbox afterward.
sailfork caisson test c-z4nwicj7 --org acme -- cargo test The command exits with the command's own exit code, so a failing test is a non-zero exit and not a CLI error. When --timeout kills the command, the exit code is 124.
| Exit code | Meaning |
|---|---|
| 0 | The command succeeded |
| 3 | With --affected, no test was affected, so none ran |
| 124 | --timeout killed the command |
| other | The command's own exit code |
To run more than one command, keep the sandbox and run again in it.
sailfork caisson test c-z4nwicj7 --org acme --keep -- make build
sailfork caisson test c-z4nwicj7 --org acme --sandbox <sandbox-id> -- make check --keep leaves the sandbox running and prints its id on stderr. --sandbox <id> runs in that sandbox, and it stays running. Before each run, /work is synced to the caisson. Files you deleted are removed and build output stays. A sandbox you start yourself with sailfork sandbox create --caisson <id> syncs the same way before each exec. A sandbox of another caisson is refused.
| Flag | Meaning |
|---|---|
--cmd <line> | The command line, run by /bin/sh -c, instead of putting it after -- |
--env KEY=VALUE | An environment variable for the command. Repeat for more. |
--minutes <n> | Minutes until the new sandbox stops anyway, 1 to 1440 (default 60) |
--on <host> | Run on this host, by name |
--save | When the command exits 0, save what it changed in /work back to the caisson. Ignored files stay out. |
--save-on-failure | With --save, also save after a non-zero exit. A command that timed out never saves. |
--affected | Run only the tests the caisson's changes reach |
--fresh-workspace | Discard the caisson's workspace volume on the host, so /work starts empty. Use it when a build is stuck on a bad one. |
--dry-run | Say what would run and start nothing |
Images
The default image is buildpack-deps:noble-scm (Ubuntu 24.04). It has git, curl, wget and python3 without pip. It has no node, compilers, Go, Rust or Java, and its apt index is empty, so run apt-get update before apt-get install -y.
Pass --image to pick one for your stack. Both sandbox create and caisson test take it.
| Stack | Image |
|---|---|
| Python | python:3.12-slim |
| Node | node:22 |
| Rust | rust:1 |
| Go | golang:1.23 |
sailfork caisson test c-z4nwicj7 --org acme --image python:3.12-slim -- 'pip install pytest && python -m pytest -q' Quote a shell chain as one string, or your own shell splits it. An image needs /bin/sh and coreutils or busybox.
An organization can restrict the images its members may use, and so can each host. A sandbox with another image is refused, and the message names the rule.
Resources and network
| Flag | Default | Meaning |
|---|---|---|
--cpus | 2 | CPUs |
--memory | 2048 | Memory in MB |
--disk | 5 | Disk the sandbox reserves on its host, in GB |
--network | outbound, when the host allows it | outbound or none. none has no network at all. |
--label | none | A host label the sandbox needs, like gpu or region=eu. Repeat for more. A host must carry all of them. |
--on | any | Run on this host, by name |
--env | none | An environment variable for every command. Repeat for more. |
A host places a sandbox only where its CPUs, memory and disk have room. If one process in a sandbox runs out of memory, it exits with 137. The sandbox stays up and the next command runs.
outbound reaches the internet, but not private networks, cloud metadata addresses or the host itself, and mail ports 25, 465 and 587 are blocked. An organization can set none for every member, and a host can set its own rule. A host that cannot install its firewall rules refuses to start, unless its owner starts it with --allow-private-egress.
--class borrow runs in room that other sandboxes reserve but do not use, at a low CPU weight, and it is evicted and queued again when they need the room back. The default guaranteed reserves its room. An organization owner can turn borrow off.
Waiting for room
sandbox create, sandbox start and caisson test wait for room when every host is full, and for a host that is reconnecting after a server update. --wait <secs> sets how long: the default is 60 and the most is 600. --wait 0 fails at once.
Note
If the wait runs out, the sandbox stays queued and its id is printed. It starts when a host has room, and fails if it has not started by its --minutes.
Queues are first in, first out per repository (per member for sandboxes with no code), fair across them. A smaller later request can start first when that does not delay the one in front.
When a command exits with 127 on the default image, the CLI prints a hint. The command is missing from that image, so pass --image or install it with apt.
Keep, stop and resume
By default a stop or the expiry destroys the sandbox. --stop changes what is kept.
--stop | What a stop keeps |
|---|---|
destroy | Nothing. This is the default. |
files | The paths you list with --keep (default /work, at most 16 paths, absolute) |
checkpoint | The files, plus memory and processes. Open connections do not survive, and it resumes only on a host running the same gVisor release, else the files restore alone. |
sailfork sandbox create -R acme/app --stop files
sailfork sandbox stop <id>
sailfork sandbox start <id> sandbox stop <id> --mode ... overrides the mode for that stop. sandbox start <id> queues the sandbox like a new one. sandbox delete <id> destroys it, kept files and checkpoints included. Both stop and delete take --dry-run, and --yes when there is no terminal to ask on.
Dependency cache
A sandbox started with -R or --caisson keeps pip, npm, yarn, pnpm, bun, uv, Cargo and Go downloads between runs, so the second pip install or go build on that repository is faster. Each host keeps one cache per repository and image family, and a sandbox started by someone who can only read the repository gets a cache of its own, so code run by readers never reaches the cache that writers use. A sandbox with no code, and CI jobs, use none.
sailfork sandbox create -R acme/app --no-cache --no-cache skips the host's cache for that sandbox. Use it when you suspect a stale download.
Separately, every host serves a read-through cache of public packages from crates.io, npm, rustup, PyPI and the Rust and Python file hosts to its outbound sandboxes. Nothing to set up.
Preview links
sailfork sandbox expose <id> <port> opens a link that serves a TCP port of a running sandbox in a browser, for you or a reviewer. The link works for 60 minutes by default (--minutes, 1 to 480), never past the sandbox's own end. Anyone who has the link can open it, so share it with care. sandbox previews <id> lists the links and whether they still work, and sandbox unexpose <id> <preview> stops one at once.
A sandbox with --network none cannot expose a port, and a sandbox has at most 3 open links.
Sandbox secrets
An organization owner can give sandboxes a credential without passing it as plain environment text.
printf '%s' "$DEPLOY_KEY" | sailfork sandbox secret set DEPLOY_KEY --org acme --value - --grant acme/app
sailfork sandbox secret list --org acme A sandbox started with -R or --caisson of a granted repository gets the secret as an environment variable of that name, and command output shows *** for the value. The values are never shown again. --grant replaces the grants, and with no --value it changes only the grants of an existing secret. sandbox secret rm <name> deletes one.
Manage hosts
| Command | What it does |
|---|---|
sandbox host list --org acme | Hosts with their state, isolation, size and what runs on them |
sandbox host cordon <name> | Stops placing new sandboxes on a host. What runs there carries on, and a request that only that host could take waits. |
sandbox host uncordon <name> | Takes new sandboxes again, and ends a drain |
sandbox host drain <name> --deadline 20 | Cordons the host, and at the deadline (minutes, 0 to 1440, default 30) stops its sandboxes and starts its CI jobs over on another host |
sandbox host upgrade <name> | Upgrades drydockd once its plain calls end. --auto on or --auto off sets whether it upgrades itself. |
sandbox host delete <name> | Removes the host. Its daemon exits and its live sandboxes fail. |
Host commands need an organization owner. sailfork sandbox settings view --org acme shows the organization's rules, and sandbox settings set changes them:
--container-isolation offkeeps sandboxes, CI included, off hosts that run plain containers instead of gVisor.--min-runsc-versionsets the oldest gVisor a host may run.--private-egress offkeeps sandboxes off hosts whose sandboxes may reach private networks.--lost-grace-minutessets how long a sandbox whose host went away keeps its place before it fails (default 30).--upgrade-window 6,0@22+6limits when hosts restart into a newdrydockd: days 0 (Sunday) to 6, then@the UTC hour and+the number of hours.--pinned-versioncaps the release hosts upgrade to.--allow-borrowallows or refusesborrowsandboxes.
If no host is free, Sailfork can start machines in your own AWS or Hetzner account. sandbox cloud add connects an account and sandbox overflow set --ci immediately --agent 60 says when queued CI jobs and agent sandboxes may use it. Run sailfork sandbox cloud --help and sailfork sandbox overflow --help for the details.
Host controls in the web app
Settings, Drydock hosts is the web version of the host commands, for the organization or for you. Members see the state of each host and the rules. Only an organization owner can change them. The server enforces every control below. An organization's own page is under its settings, Drydock hosts.
Each host row has Cordon and Drain, Uncordon (or Stop draining), a switch for upgrading that host automatically, Upgrade to a newer drydockd when one is out, and Remove. They match sandbox host cordon, drain, uncordon, upgrade and delete. Show history on a host row charts its CPU, memory and disk for the last hour or day, from one sample a minute kept for a day.
Stop what runs on a host
Drain asks Stop what runs on the host after, and offers Now, 15 minutes, 1 hour, 4 hours or 24 hours. The host takes no new sandboxes straight away. At the deadline, what still runs stops and its CI jobs start over on another host. Stop draining puts the host back in service, and what still runs keeps running. The CLI takes any number of minutes from 0 to 1,440 with --deadline.
Stop sandboxes in bulk
On an organization's Sandboxes page, an owner selects live or queued sandboxes and chooses Stop N. A dialog lists each one with who started it, how long it has run and whether a command is running. Confirming stops them now and removes their files, and a running command is cut off. A bulk stop takes at most 200 sandboxes. CI sandboxes are left out, and a sandbox that already ended is skipped with its reason. Each stop goes in the audit log under your name.
Host policy
Settings, Drydock hosts, Host policy sets what a host must offer before any sandbox, CI included, runs on it. Save host policy applies the changes. While you edit, the page lists the connected hosts the draft would skip, and warns when no host would pass.
| Control | What it does |
|---|---|
| Allow plain-container hosts | Off keeps sandboxes off hosts that run plain containers instead of gVisor. Same as --container-isolation. |
| Allow hosts that reach private networks | Off keeps sandboxes off hosts started with --allow-private-egress. Same as --private-egress. |
| Allow borrowed room | Off refuses borrow sandboxes with borrow_not_allowed. Same as --allow-borrow. |
| Oldest gVisor allowed | A gVisor host older than this release, such as release-20240311.0, takes no sandboxes. A host that does not report its version is skipped too. Blank allows any version. |
| Fail an unreachable sandbox after | A sandbox whose host stops answering keeps its place this many minutes, 0 to 1,440, then fails. Blank means 30. |
| Upgrade any time | Off limits automatic host upgrades to a window: the days, a start hour in UTC and 1 to 168 hours. A window may run past midnight. The page shows the start in your time zone. |
| Hold hosts at drydockd | The newest drydockd release hosts upgrade to, such as 0.2.11. Blank follows Sailfork's latest. A pin older than the release holds hosts there, and Upgrade to offers only up to the pin. |
| Email owners about host trouble | Emails the organization's owners when one of its own hosts goes offline or is too full to bake, and again when it recovers. On by default. Pooled hosts stay with the site operator. |
The upgrade window applies to a host that upgrades itself. The Upgrade to button on a host does not wait for it. Hosts of one organization upgrade a tenth at a time, and at least one.
Settings, Drydock hosts, Images and network sets Allowed images and Network for every member sandbox. Allowed images takes up to 50 patterns, one per line, with letters, digits and . / : _ @ -. * matches within a path segment (node:*) and ** across segments (ghcr.io/acme/**). Blank allows any image the host accepts. Network is the host's own setting or No network, which keeps member sandboxes offline even on a host that allows outbound traffic.
A host can set its own Policy under its row, with the same two controls. The host's image list replaces the organization's for that host, and Follow the organization's image rule goes back to it. On a host another owner lends to your organization, a sandbox must pass both lists.
Cloud accounts
Cloud accounts, below Overflow, connect the AWS or Hetzner account where overflow machines start when no host has room. Keys are checked with the provider, sealed and never shown again. Removing an account with live machines stops them first. Overflow sets when queued CI jobs and agent sandboxes may use them, the same as sandbox overflow set.
Limits and errors
An organization owner can limit how many sandboxes members run at once (per member and per organization), the CPUs, memory and total minutes of one sandbox, the images and the network. Settings, Drydock hosts, Limits shows them, and CI sandboxes are never counted.
| What you see | Meaning |
|---|---|
quota_exceeded (429) | You are over a concurrency limit. It does not wait. Stop a sandbox or ask an owner to raise the limit. |
quota_exceeded (422) | The sandbox is bigger than a size limit, or extending it would pass the total minutes. |
no_host (503) | No host is online, and none has talked to Sailfork in the last 2 minutes. |
host_offline (503) | The host you named with --on is offline. |
host_not_allowed (422) | The organization's host rules refuse every host. |
image_not_allowed (422) | The image is outside the organization's or the host's image rules. |
egress_blocked (422) | You asked for outbound and the organization allows only none. |
borrow_not_allowed (422) | The organization has turned borrow off. |
not_running (409) | The sandbox is queued or still starting. Wait, then retry. |
stopped (409) | The sandbox has stopped. |
host_busy (429) | The sandbox already runs 8 calls, or its host 64. Retry after a second. |
An exec through the REST API keeps the first 1 MiB of each of stdout and stderr in its answer. The CLI streams, so it prints everything.
Access
Starting sandboxes and running commands needs a token with the sandbox scope, and registering hosts needs an organization owner. Token scopes lists every scope.
For agents, the drydock toolset in the MCP server starts sandboxes and runs commands, and caisson_test in the caissons toolset runs a caisson's tests. Install the CLI and follow the quickstart to sign in first.