Sandboxes API
Register Drydock hosts, start sandboxes, run commands, move files, open preview links and manage sandbox settings, secrets and cloud overflow over REST.
This page covers the routes behind sandboxes and Drydock. A Drydock host is a machine your organization runs. A sandbox is an isolated container on one of those hosts. For tokens, error shape and paging, see authentication, token scopes, errors and paging.
Access rules
| Routes | Token scope | Who |
|---|---|---|
Every /api/sandboxes/{id}/... route, and create, list, execs and stop in /api/orgs/{org}/sandboxes | sandbox | Varies per route, see below |
| List hosts, host usage, get settings, get overflow, list providers and machines | org:read | Members (overflow, providers and machines: owners) |
| Every other host, settings, secrets, overflow and provider route | org:admin | Owners |
Organization owners can act on every sandbox in the organization. A creator can act on their own. Sandbox ids are opaque strings.
The daemon channel is not documented here: GET /api/drydock/connect, POST /api/drydock/enroll, POST /api/drydock/relay/{host} and GET /api/drydock/release are used by drydockd, and /api/admin/... routes are for site administrators.
Hosts
List hosts
GET /api/orgs/{org}/drydock/hosts Members. Returns { hosts, release, target }, oldest host first. release is the drydockd version hosts upgrade to. target is what an upgrade installs, which is release capped at the organization's pinnedVersion. Both are null before any release exists.
curl -H "Authorization: Bearer $SAILFORK_TOKEN" https://status.sailfork.com/api/orgs/acme/drydock/hosts {
"hosts": [
{
"id": "b1c2d3e4-0000-4000-8000-000000000001",
"name": "build-1",
"online": true,
"tokenHint": "sfdd_…a1b2",
"isolation": "gvisor",
"arch": "x86_64",
"cpus": 16,
"memoryMb": 65536,
"diskGb": 800,
"maxSandboxes": null,
"network": "outbound",
"version": "0.14.2",
"running": 3,
"schedulable": true,
"autoUpgrade": true,
"labels": ["pool=ci"],
"reserved": { "vcpus": 6, "memoryMb": 12288, "diskGb": 15 }
}
],
"release": "0.14.2",
"target": "0.14.2"
} The response is trimmed here. Fields on each host:
| Field | Type | Meaning |
|---|---|---|
id, name | string | Host id and name |
online | boolean | Whether its daemon is connected |
tokenHint | string | sfdd_… and the last 4 characters of its token |
isolation | gvisor, container or null | Null until the daemon first connects. container means no gVisor, for trusted code only |
arch, cpus, memoryMb, diskGb | string or number or null | What the daemon reported. diskGb is the disk budget sandboxes reserve against |
maxSandboxes | number or null | Optional count cap |
network | outbound, none or null | What its sandboxes may reach |
version, runscVersion | string or null | drydockd version and first line of runsc --version |
gvisorPlatform, gvisorPlatformReason | string or null | The gVisor platform the host runs (kvm, or systrap, the slower default for process starts and file walks) and why, such as no /dev/kvm. Null from a daemon that predates it |
running | number | Live sandboxes |
reserved | object | vcpus, memoryMb, diskGb its live sandboxes reserve |
usage | object or null | Last heartbeat: cpuPermille, loadCenti, memoryUsedMb, memoryTotalMb, diskUsedGb, diskTotalGb, pools, at |
lastSeenAt, createdAt | string or null | ISO timestamps |
createdBy | string | Display name |
autoUpgrade | boolean | The daemon installs the release Sailfork announces. Default true |
upgrade | string or null | The daemon's own words on its last upgrade, until it reconnects |
allowedImages, egress | array or null, string or null | The host's own policy. Null follows the organization's |
schedulable, drainDeadline | boolean, string or null | False once cordoned or draining, and when a drain stops what still runs |
privateEgress | boolean | Its outbound sandboxes may reach private networks |
enrolled | boolean | It connects with an enrolled key instead of its token |
labels | string array | k=v labels from drydockd --label |
pool | boolean | Its daemon takes more than one tenant |
limits | string array | What it found it can enforce, such as limit-disk or limit-cores |
Add a host
POST /api/orgs/{org}/drydock/hosts Owners. Body: { "name": "build-1" }. The name is 1 to 64 characters of A-Z, a-z, 0-9, ., _ and -, and unique in the organization. An organization has at most 50 hosts. Returns 201 with { host, token }. The sfdd_... token is shown once.
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
-d '{"name":"build-1"}' https://status.sailfork.com/api/orgs/acme/drydock/hosts A duplicate name is 409. The change is audit logged.
Remove a host
DELETE /api/orgs/{org}/drydock/hosts/{id} Owners. Returns 204. The daemon is disconnected and exits, and the host's live sandboxes fail.
Update a host
PATCH /api/orgs/{org}/drydock/hosts/{id} Owners. Body: { "autoUpgrade": true }. Returns the host. With auto-upgrade on, a daemon older than the release is told to upgrade once the release's rollout reaches it, inside the organization's upgradeWindow, never past its pinnedVersion, and with at most a tenth (at least one) of the organization's hosts upgrading at once. Turning it off withdraws an upgrade the daemon has not started installing.
Upgrade a host now
POST /api/orgs/{org}/drydock/hosts/{id}/upgrade Owners. No body. Returns 202 with { "version": "0.14.2" }, the release the host was told to install. The release is capped at pinnedVersion whatever auto-upgrade says. The daemon checks the download's sha256 and restarts once no plain call is in flight. Sandboxes and durable execs survive the restart. The host's upgrade field reports progress. 409 when the host is offline or already runs the release.
Host usage
GET /api/orgs/{org}/drydock/hosts/{id}/usage?hours=1 Members. Returns { samples }, oldest first, one sample a minute from the daemon's heartbeats. Each sample has at, cpuPermille, loadCenti, memoryUsedMb and diskUsedGb. hours is 1 to 24 and defaults to 1, otherwise 422. Samples are kept for a day. Daemons from before resource reporting return an empty list.
Cordon, uncordon and drain
POST /api/orgs/{org}/drydock/hosts/{id}/cordon
POST /api/orgs/{org}/drydock/hosts/{id}/uncordon
POST /api/orgs/{org}/drydock/hosts/{id}/drain Owners. All three return the host.
| Route | Effect |
|---|---|
cordon | The host takes no new sandboxes. What runs on it carries on, and requests only it could take wait in their queue |
uncordon | Makes it schedulable again and also ends a drain |
drain | Cordons it. Body { "deadlineMinutes": 30 }, 0 to 1440. At the deadline its sandboxes stop and its CI jobs go back to start over on another host, with no attempt counted |
Set a host's policy
PUT /api/orgs/{org}/drydock/hosts/{id}/policy Owners. Body: { "allowedImages": ["node:*"], "egress": "none" }. Replaces both fields. An omitted or null field follows the organization's setting again. Returns the host. 404 for a host of another organization. A host's own policy replaces the organization's for sandboxes placed on it. Placement skips a host whose policy refuses a request, and answers 422 when none accepts.
Hosted compute
Whether an organization, or you for your own repositories, runs on Sailfork's hosts. See Hosted compute for the price.
GET /api/orgs/{org}/compute/hosted
PUT /api/orgs/{org}/compute/hosted
DELETE /api/orgs/{org}/compute/hosted
GET /api/settings/compute/hosted
PUT /api/settings/compute/hosted
DELETE /api/settings/compute/hosted Owners. GET returns { enabled, refusal, suspended, suspendedReason, maxVcpus, monthlyCapCents, monthCents, millicentsPerUnitHour }. refusal says why it cannot be turned on yet. PUT turns it on, or changes the caps when it is on. Body: { "maxVcpus": 64, "monthlyCapCents": 5000 }. maxVcpus is 1 to 256 and keeps its value when omitted, 64 on first use. monthlyCapCents is 1 to 100000000, and omitting it removes the cap. PUT answers 409 with the reason when billing has not started, the plan is Free or its subscription is not active, or the account is unverified or suspended. DELETE turns it off, and answers 409 while Sailfork has the account suspended. Running sandboxes carry on. The org routes need org:admin to change and org:read to read, and /api/settings/compute/hosted needs user. Changes to an organization are audit logged.
curl -X PUT -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
-d '{"maxVcpus":32,"monthlyCapCents":5000}' https://status.sailfork.com/api/orgs/acme/compute/hosted Sandboxes
Create a sandbox
POST /api/orgs/{org}/sandboxes Members, scope sandbox. Every field is optional.
| Field | Type | Meaning |
|---|---|---|
image | string | Default buildpack-deps:noble-scm |
vcpus, memoryMb | number | Default 2 and 2048 |
diskGb | number | 1 to 1024, default 5 |
network | outbound or none | outbound when the host allows it |
minutes | number | Lifetime, 1 to 1440, default 60 |
host | string | A host name. Any online host with room otherwise |
labels | string array | Host labels it needs, all of them, at most 16 |
env | object | Environment set for every command |
repo, ref | string | Put owner/name code in /work, at a branch, tag or commit. The default branch when ref is absent |
caisson | string | A caisson id: its branch head plus uncommitted edits. Excludes repo (422) |
waitSeconds | number | 0 fails at once when no host has room. Otherwise it only sets how long clients wait on a queued sandbox's events, default 60, max 600 |
cache | boolean | Mount the host's dependency cache (with repo) or the caisson workspace volume (with caisson). false opts out |
freshWorkspace | boolean | With caisson: discard its workspace volume first. 422 otherwise |
stop | destroy, files or checkpoint | What a stop, the expiry and the minute limit keep. Default destroy. files archives keepPaths. checkpoint also saves memory and processes as a gVisor checkpoint |
keepPaths | string array | Absolute paths, default ["/work"], at most 16, none of /, /proc, /sys, /dev |
class | guaranteed or borrow | Default guaranteed. A borrow sandbox runs in reserved but unused room at a low CPU weight and is queued again when guaranteed work needs it back |
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
-d '{"image":"node:22","repo":"acme/api","minutes":30}' \
https://status.sailfork.com/api/orgs/acme/sandboxes {
"id": "sbx_7f3k2m9q",
"org": "acme",
"host": { "id": "b1c2d3e4-0000-4000-8000-000000000001", "name": "build-1" },
"image": "node:22",
"vcpus": 2,
"memoryMb": 2048,
"diskGb": 5,
"network": "outbound",
"state": "running",
"error": null,
"createdBy": "Fenil Sonani",
"createdByHandle": "fenil",
"createdAt": "2026-11-10T18:02:11Z",
"expiresAt": "2026-11-10T18:32:11Z",
"stoppedAt": null,
"workdir": "/work",
"source": "acme/api@4be1f0c",
"commandRunning": false,
"stop": "destroy",
"class": "guaranteed",
"reclaims": 0
} A code tree over 16 MiB compressed, 128 MiB unpacked or 50,000 files is 413. The caller must be able to read the repository, otherwise 404.
Status codes:
| Status | Meaning |
|---|---|
201 | A host took it within about 2 seconds. It runs, or failed starting |
202 | State queued with queuePosition, because every host is full. Follow events. A queued sandbox that has not started by its minutes fails |
400, 422 | No online host could ever take it (image, size, labels, network or policy). 422 with host_not_allowed when the organization's host policy refuses every host. borrow_not_allowed when allowBorrow is false. quota_exceeded, image_not_allowed and egress_blocked come from settings |
404 | Unknown host |
429 | quota_exceeded: past the per-member or per-organization count. Queued sandboxes count |
502 | code_failed: the host could not take the code |
503 | no_host: no host is online and none talked in the last 2 minutes, or waitSeconds is 0 and no host has room. host_offline: the named host is offline |
Sandbox object
The fields you will read most:
| Field | Meaning |
|---|---|
state | queued, leased, starting, running, lost, stopping, kept, suspended, stopped or failed |
queuePosition | While queued: 1 is the next of its owner's sandboxes to start |
host | { id, name }, or null once its host was removed |
error | Why it failed |
expiresAt, stoppedAt, startedAt | ISO timestamps. It is stopped at expiresAt |
workdir, source, origin | /work when started with code, that code as owner/name@<sha> or caisson <id>, and the same made readable (repo, caisson, pull, ref, commit) |
commandRunning | A command is running in it now |
idle | { seconds, limitSeconds } for a running sandbox with nothing in flight |
stop, keepPaths | What a stop keeps |
class, reclaims | Its class and how many times it was evicted and queued again |
notice | The last thing worth telling you, such as a checkpoint restored as files only |
usage | cpuMilli, memoryMb, diskMb, at, while running and once its host reported |
A lost sandbox's host went away. It keeps its place, runs again if the host returns, and fails after the organization's lostGraceMinutes. CI sandboxes fail instead.
List sandboxes
GET /api/orgs/{org}/sandboxes?state=live&limit=50&cursor=&caisson= Scope sandbox. Members see their own sandboxes and owners see all of them, newest first. Returns { sandboxes, nextCursor }.
| Query | Meaning |
|---|---|
state | live (default) is queued, leased, starting, running, stopping or lost. all adds kept, suspended and ended ones |
limit | 1 to 200, default 200 |
cursor | The nextCursor of the previous page. Null on the last page |
caisson | A caisson id: only sandboxes started with that caisson's code |
A bad limit or cursor is 422.
List commands run in the organization
GET /api/orgs/{org}/sandboxes/execs?limit=50&cursor= Owners only, scope sandbox. The audit log of every command run in the organization's sandboxes, newest first. 403 for members, 404 for others. limit is 1 to 200, default 50. Returns { execs, nextCursor }. Each record has id, sandboxId, startedById, startedByHandle, startedByName, argv (at most 32 arguments, each cut to 200 characters), argvTruncated, startedAt, exitCode (null while it runs), durationMs and timedOut.
Stop many sandboxes
POST /api/orgs/{org}/sandboxes/stop Owners only, scope sandbox. Body: { "ids": ["sbx_7f3k2m9q", "sbx_1a2b3c4d"] }, 1 to 200 ids. Stops each live sandbox of the organization. Returns { stopped, skipped }, where each skipped entry is { id, reason }. Every stop is audit logged.
Get a sandbox
GET /api/sandboxes/{id} Its creator and the organization's owners. Returns the sandbox. 404 for others.
curl -H "Authorization: Bearer $SAILFORK_TOKEN" https://status.sailfork.com/api/sandboxes/sbx_7f3k2m9q Sandbox activity
GET /api/sandboxes/{id}/activity Its creator and the organization's owners. Returns { events, commands }. events are life events, oldest first, each with at, kind (queued, started, evicted, extended, stopped or failed), text and by when a person did it. commands are the latest 50 command records.
Follow events
GET /api/sandboxes/{id}/events Its creator and owners. Returns application/x-ndjson, one JSON event per line: the current state first, then each change, repeated every 15 seconds. The stream ends after stopped, failed, kept or suspended.
| Event | Meaning |
|---|---|
{ "type": "queued", "position": 2 } | Waiting for room |
{ "type": "leased" } | A host took it and is starting it |
{ "type": "running", "sandbox": {...} } | It runs |
{ "type": "lost" } | Its host went away. running follows if it returns in time |
{ "type": "reclaimed", "position": 1 } | A borrow sandbox was evicted and queued again at the front |
{ "type": "stopping" } | Its files or checkpoint are being saved |
{ "type": "kept" }, { "type": "suspended" } | Stopped with files or a checkpoint saved. Start runs it again |
{ "type": "notice", "message": "..." } | Something worth telling the caller |
{ "type": "failed", "error": "..." }, { "type": "stopped" } | The end |
Extend a sandbox
PATCH /api/sandboxes/{id} Creator. Body: { "minutes": 60 }, 1 to 1440. It now stops that many minutes from now. A queued sandbox stops that many minutes after it starts. Returns the sandbox. 409 once stopped. The organization's maxMinutes counts the minutes already run, so an extension past it is 422 with quota_exceeded.
Delete a sandbox
DELETE /api/sandboxes/{id} Creator or owners. Returns 204 once the sandbox is stopped. The host removes its container in the background. Deleting a stopped sandbox changes nothing. It always destroys: a kept or suspended sandbox becomes stopped and its archive is deleted.
Stop a sandbox
POST /api/sandboxes/{id}/stop Creator or owners. Optional body: { "mode": "files" }, where mode is destroy, files or checkpoint. When absent it uses the stop set at create. A files or checkpoint stop moves the sandbox to stopping while the host archives, then to kept or suspended. Returns the sandbox.
| Status | Meaning |
|---|---|
409 | not_running |
502 | keep_failed: the host could not save |
503 | keep_unavailable: the host cannot keep files or checkpoint, or storage is not configured |
Start a kept sandbox
POST /api/sandboxes/{id}/start Creator or owners. Queues a kept or suspended sandbox again. Any host restores the files. A checkpoint resumes on a host running the same gVisor release. Otherwise the files restore alone and notice says so. Open TCP connections do not survive a checkpoint. Returns 202 with the sandbox while it is queued again, or 200 once it runs. 409 with not_kept for any other state.
Run commands and move files
Run a command
POST /api/sandboxes/{id}/exec Creator. Body:
| Field | Type | Meaning |
|---|---|---|
command | string | Run by /bin/sh -c. Send this or argv |
argv | string array | A program and its arguments |
cwd | string | Default: the sandbox's workdir |
env | object | Over the sandbox's env |
timeoutSeconds | number | Default 120, max 3600 |
stdin | string | Input for the command |
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
-d '{"argv":["node","--version"]}' https://status.sailfork.com/api/sandboxes/sbx_7f3k2m9q/exec {
"exitCode": 0,
"timedOut": false,
"stdout": "v22.11.0\n",
"stderr": "",
"stdoutTruncated": false,
"stderrTruncated": false,
"durationMs": 84
} Each stream keeps its first 1 MiB. exitCode is 124 after a timeout. The response carries a Sailfork-Exec: <exec id> header. Send Accept: application/x-ndjson to stream instead. Each line is { "stdout": "..." }, { "stderr": "..." }, then one last { "exit": { exitCode, timedOut, durationMs } } or { "error": "..." }. Secret values granted through secrets are replaced with *** in the output.
On a host with exec handles the command runs detached. When the host's link drops, the call reattaches from the output it already returned, with no gap or repeat. A client that hangs up kills the command: at once for a plain call, after 60 seconds for a streamed one unless it follows the command again.
A sandbox started from a caisson first syncs /work to the caisson's current tree when it changed. Files the caisson dropped are deleted and files commands made are kept. 502 with code_failed when it cannot.
| Status | Meaning |
|---|---|
409 | stopped, or not_running while the sandbox is queued or starting (also for files) |
429 | host_busy with Retry-After: 1: the sandbox already runs 8 calls or its host 64 (also for files) |
503 | host_offline, also while the sandbox is lost |
Follow a command again
GET /api/sandboxes/{id}/execs/{exec}/stream?stdoutOffset=0&stderrOffset=0 Creator. Returns application/x-ndjson lines in the same shape as a streamed exec, from those byte offsets of the output. Use it when your stream broke while the command kept running, for example when the server restarted. Following within 60 seconds of a break keeps the command alive; hanging up again starts another 60 seconds. 404 for an exec without a durable record. The exec id comes from the Sailfork-Exec header.
Stop a command
DELETE /api/sandboxes/{id}/execs/{exec} Creator. Kills a running durable command now. Returns 204, or 404 once it ended.
Read a file
GET /api/sandboxes/{id}/files?path=/work/out.log Creator. path is absolute. Returns the file's bytes. 404 when missing, 413 over 16 MiB.
Write a file
PUT /api/sandboxes/{id}/files?path=/work/notes.txt&mode=644 Creator. The request body is the file's bytes, up to 16 MiB. Parent directories are created. mode is the file mode. Returns 204.
curl -X PUT -H "Authorization: Bearer $SAILFORK_TOKEN" --data-binary @notes.txt \
"https://status.sailfork.com/api/sandboxes/sbx_7f3k2m9q/files?path=/work/notes.txt&mode=644" Preview links
A preview link serves one port of a running sandbox over plain HTTP to anyone who has the URL. Visitors first see an interstitial that says the page is unverified, with a report form. Links forward one request at a time, up to 1 MiB in and 8 MiB out, with no websockets. A link ends when it expires, when its sandbox leaves running, or after the sandbox's links served 2 GiB together.
Create a preview link
POST /api/sandboxes/{id}/previews Creator. Body: { "port": 3000, "minutes": 60 }. minutes is optional, 1 to 480, default 60, and never runs past the sandbox. Returns 201 with the preview. The url is shown only in this response.
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
-d '{"port":3000}' https://status.sailfork.com/api/sandboxes/sbx_7f3k2m9q/previews {
"id": "prv_9d8c7b6a",
"sandboxId": "sbx_7f3k2m9q",
"port": 3000,
"state": "open",
"expiresAt": "2026-11-10T19:05:00Z",
"createdAt": "2026-11-10T18:05:00Z",
"bytes": 0,
"url": "https://k3j9x2m7q1.preview.example.com/"
} | Status | Meaning |
|---|---|
409 | not_running, no_network, or preview_unsupported when the host's drydockd does not run previews |
429 | The sandbox has 3 open previews, its organization (else owner) has 10, or its links served 2 GiB |
503 | previews_off: the server has no preview domain |
List preview links
GET /api/sandboxes/{id}/previews Creator. Returns { previews }, newest first, at most 50, without url. state is open, expired, stopped or sandbox_stopped. Only open links work.
Stop a preview link
DELETE /api/sandboxes/{id}/previews/{preview} Creator. Returns 204. The link stops working at once. 404 when unknown.
Sandbox settings
Read and replace settings
GET /api/orgs/{org}/drydock/settings
PUT /api/orgs/{org}/drydock/settings GET is for members (org:read) and PUT for owners (org:admin). PUT replaces every field, and an omitted field means no limit. A value out of range or an unknown field is 422. Both return the settings.
| Field | Type | Meaning |
|---|---|---|
maxPerMember | number or null | Live sandboxes one member may run at once, 1 to 10000 |
maxPerOrg | number or null | Live member sandboxes the organization runs at once, 1 to 10000 |
maxVcpus | number or null | Per sandbox, 1 to 256 |
maxMemoryMb | number or null | Per sandbox, 256 to 4194304 |
maxMinutes | number or null | Per sandbox in total, extensions included, 1 to 1440 |
allowedImages | string array or null | Image patterns, * within a path segment and ** across, such as node:* or ghcr.io/acme/**. Null or empty allows any image the host accepts. At most 50 patterns of 255 characters |
egress | outbound, none or null | none keeps members' sandboxes off the network. A create that asks for outbound is 422 with egress_blocked, and one that names no network gets none |
minRunscVersion | string or null | Oldest gVisor a gVisor host may run, such as release-20240311.0 |
allowContainerIsolation | boolean or null | false keeps sandboxes off plain-container hosts |
allowPrivateEgress | boolean or null | false keeps sandboxes off hosts whose sandboxes reach private networks |
lostGraceMinutes | number or null | A lost sandbox fails after this, 0 to 1440, default 30 |
upgradeWindow | object or null | When hosts may restart into a new drydockd, in UTC: { days, startHour, durationHours } with days 0 (Sunday) to 6, startHour 0 to 23, durationHours 1 to 168. It may run past midnight. Null is any time |
pinnedVersion | string or null | Newest drydockd release hosts upgrade to. Null follows Sailfork's |
allowBorrow | boolean or null | false refuses borrow sandboxes with borrow_not_allowed |
Quotas apply to sandboxes members start. CI sandboxes are never counted or limited. A create past a size limit is 422 with quota_exceeded before it is placed. Past a concurrency limit it is 429 and never waits for room. The host rules (minRunscVersion, allowContainerIsolation, allowPrivateEgress) apply to every sandbox, CI included. The change is audit logged.
curl -X PUT -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
-d '{"maxPerMember":5,"maxMinutes":240,"allowedImages":["node:*"],"egress":"outbound"}' \
https://status.sailfork.com/api/orgs/acme/drydock/settings Sandbox secrets
Secrets are credentials a sandbox needs without passing them as plain env. They are sealed and never returned. Owners set a secret and grant it to repositories of the organization. A sandbox started with repo or caisson of a granted repository gets the secret as an environment variable of its name. All three routes need org:admin and are for owners. 503 when the server has no secret key.
List secrets
GET /api/orgs/{org}/drydock/secrets Returns { secrets } by name. Each entry is { name, repos, updatedAt }.
Set a secret
PUT /api/orgs/{org}/drydock/secrets/{name} Body: { "value": "...", "repos": ["acme/api"] }. Returns the secret entry.
| Field | Rules |
|---|---|
name (path) | Like an env var: [A-Za-z_][A-Za-z0-9_]*, at most 128 characters, not PATH or HOME, no SAILFORK_, GITHUB_ or LD_ prefix |
value | 1 byte to 32 KiB, no NUL. Optional for an existing secret, to change only its grants. 422 for a new one without it |
repos | owner/name of repositories the organization owns, at most 200, otherwise 422 |
An organization has at most 100 secrets. Exec output has each granted value replaced with ***, also across chunk boundaries. A caller's own env of the same name wins and is not masked. Changing a grant does not touch running sandboxes.
curl -X PUT -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
-d '{"value":"s3cr3t","repos":["acme/api"]}' \
https://status.sailfork.com/api/orgs/acme/drydock/secrets/NPM_TOKEN { "name": "NPM_TOKEN", "repos": ["acme/api"], "updatedAt": "2026-11-10T18:10:00Z" } Delete a secret
DELETE /api/orgs/{org}/drydock/secrets/{name} Returns 204. 404 when unknown. Deleting a repository removes its grants.
Cloud overflow
When your own hosts are full, Sailfork can start virtual machines in your own AWS or Hetzner account with credentials your owners connect. Each machine installs Docker and drydockd, enrolls as a host named cloud-<kind>-<id>, and takes work like any host. Its labels are pool=cloud, provider=<kind> and market=spot or on-demand. An autoscaler launches the smallest allowed type that fits queued work no host can take, never past maxHosts. It terminates a machine that was idle for idleMinutes, one stuck starting for 10 minutes, and one its provider reports gone or stopped. Spot (AWS only) is used for CI work only.
Every route in this section is for owners: 403 for members, 404 for others. GET needs org:read and the rest need org:admin. Every change is audit logged.
Overflow rules
GET /api/orgs/{org}/drydock/overflow
PUT /api/orgs/{org}/drydock/overflow Both return the rules. PUT takes the same fields without updatedAt.
| Field | Type | Meaning |
|---|---|---|
agent, ci | object | When that kind of work may overflow: { "mode": "never" | "immediately" | "after", "afterSeconds": 30 }. afterSeconds is 0 to 86400, otherwise 422 |
pinSecretJobs | boolean | Work given sandbox secrets stays on your own hosts |
updatedAt | string or null | Null until set. Defaults are after 30 seconds for both kinds and pinSecretJobs true |
curl -X PUT -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
-d '{"agent":{"mode":"after","afterSeconds":60},"ci":{"mode":"immediately","afterSeconds":0},"pinSecretJobs":true}' \
https://status.sailfork.com/api/orgs/acme/drydock/overflow List cloud providers
GET /api/orgs/{org}/drydock/cloud/providers Returns { providers }, oldest first. Credentials are never returned. Each provider has id, kind (aws or hetzner), credentialHint, roleArn, region, instanceTypes, maxHosts, idleMinutes, spot, image, subnetId, securityGroupIds, networks, firewalls, liveMachines (starting, running, draining or terminating), createdBy, createdAt and updatedAt.
Add a cloud provider
POST /api/orgs/{org}/drydock/cloud/providers Returns 201 with the provider.
| Field | Type | Meaning |
|---|---|---|
credentials | object | AWS: { "kind": "aws", "accessKeyId", "secretAccessKey", "roleArn"?, "externalId"? } (roleArn is assumed through STS with the keys). Hetzner: { "kind": "hetzner", "token" }, a read and write project API token |
region | string | AWS region such as us-east-1, or Hetzner location such as fsn1 |
instanceTypes | string array | 1 to 20 from the kind's catalog |
maxHosts | number | 1 to 50 |
idleMinutes | number | 1 to 1440, default 10 |
spot | boolean | AWS only: CI machines as one-time spot instances |
image | string | AWS: an AMI id or resolve:ssm:..., default Canonical's Ubuntu 24.04. Hetzner: an image, default ubuntu-24.04 |
subnetId, securityGroupIds | string, string array | AWS only, at most 5 security groups |
networks, firewalls | number arrays | Hetzner only, at most 5 each |
The catalog is AWS t3.medium to 2xlarge, m7i and c7i large to 12xlarge, m7g and c7g medium to 4xlarge (arm), and Hetzner cx23 to cx53, cpx22 to cpx62, ccx13 to ccx53, cax11 to cax41 (arm). Work that names no architecture gets x86. An organization has at most 10 providers.
Sailfork validates the body, then runs a cheap read with the credentials (AWS DescribeInstances, Hetzner GET /v1/locations). It answers 422 with the <kind> credentials did not work: ... when that fails. A field out of range is also 422. 503 when the server has no secret key.
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
-d '{"credentials":{"kind":"hetzner","token":"<project token>"},"region":"fsn1","instanceTypes":["cpx41"],"maxHosts":4}' \
https://status.sailfork.com/api/orgs/acme/drydock/cloud/providers Remove a cloud provider
DELETE /api/orgs/{org}/drydock/cloud/providers/{id} Returns 204. It terminates the provider's live machines first and fails their sandboxes. When one cannot be terminated, it answers 503 naming it and keeps everything. 404 when unknown.
List cloud machines
GET /api/orgs/{org}/drydock/cloud/machines Returns { machines }, newest first, at most 200. Terminated and failed machines are listed for a day. Each machine has id, providerId, kind, hostId and hostName (while it has a host), providerInstanceId, instanceType, spot, state, error, sandboxes, startedAt, lastLeasedAt and terminatedAt. state is starting, running, draining (over a lowered maxHosts, terminated once its sandboxes finish), terminating, terminated or failed.