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 codeMeaning
0The command succeeded
3With --affected, no test was affected, so none ran
124--timeout killed the command
otherThe 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.

FlagMeaning
--cmd <line>The command line, run by /bin/sh -c, instead of putting it after --
--env KEY=VALUEAn 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
--saveWhen the command exits 0, save what it changed in /work back to the caisson. Ignored files stay out.
--save-on-failureWith --save, also save after a non-zero exit. A command that timed out never saves.
--affectedRun only the tests the caisson's changes reach
--fresh-workspaceDiscard the caisson's workspace volume on the host, so /work starts empty. Use it when a build is stuck on a bad one.
--dry-runSay 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.

StackImage
Pythonpython:3.12-slim
Nodenode:22
Rustrust:1
Gogolang: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

FlagDefaultMeaning
--cpus2CPUs
--memory2048Memory in MB
--disk5Disk the sandbox reserves on its host, in GB
--networkoutbound, when the host allows itoutbound or none. none has no network at all.
--labelnoneA host label the sandbox needs, like gpu or region=eu. Repeat for more. A host must carry all of them.
--onanyRun on this host, by name
--envnoneAn 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.

--stopWhat a stop keeps
destroyNothing. This is the default.
filesThe paths you list with --keep (default /work, at most 16 paths, absolute)
checkpointThe 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.

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

CommandWhat it does
sandbox host list --org acmeHosts 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 20Cordons 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 off keeps sandboxes, CI included, off hosts that run plain containers instead of gVisor.
  • --min-runsc-version sets the oldest gVisor a host may run.
  • --private-egress off keeps sandboxes off hosts whose sandboxes may reach private networks.
  • --lost-grace-minutes sets how long a sandbox whose host went away keeps its place before it fails (default 30).
  • --upgrade-window 6,0@22+6 limits when hosts restart into a new drydockd: days 0 (Sunday) to 6, then @ the UTC hour and + the number of hours. --pinned-version caps the release hosts upgrade to.
  • --allow-borrow allows or refuses borrow sandboxes.

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.

ControlWhat it does
Allow plain-container hostsOff keeps sandboxes off hosts that run plain containers instead of gVisor. Same as --container-isolation.
Allow hosts that reach private networksOff keeps sandboxes off hosts started with --allow-private-egress. Same as --private-egress.
Allow borrowed roomOff refuses borrow sandboxes with borrow_not_allowed. Same as --allow-borrow.
Oldest gVisor allowedA 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 afterA sandbox whose host stops answering keeps its place this many minutes, 0 to 1,440, then fails. Blank means 30.
Upgrade any timeOff 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 drydockdThe 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 troubleEmails 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 seeMeaning
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.

Loading Sailfork