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

RoutesToken scopeWho
Every /api/sandboxes/{id}/... route, and create, list, execs and stop in /api/orgs/{org}/sandboxessandboxVaries per route, see below
List hosts, host usage, get settings, get overflow, list providers and machinesorg:readMembers (overflow, providers and machines: owners)
Every other host, settings, secrets, overflow and provider routeorg:adminOwners

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://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:

FieldTypeMeaning
id, namestringHost id and name
onlinebooleanWhether its daemon is connected
tokenHintstringsfdd_… and the last 4 characters of its token
isolationgvisor, container or nullNull until the daemon first connects. container means no gVisor, for trusted code only
arch, cpus, memoryMb, diskGbstring or number or nullWhat the daemon reported. diskGb is the disk budget sandboxes reserve against
maxSandboxesnumber or nullOptional count cap
networkoutbound, none or nullWhat its sandboxes may reach
version, runscVersionstring or nulldrydockd version and first line of runsc --version
gvisorPlatform, gvisorPlatformReasonstring or nullThe 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
runningnumberLive sandboxes
reservedobjectvcpus, memoryMb, diskGb its live sandboxes reserve
usageobject or nullLast heartbeat: cpuPermille, loadCenti, memoryUsedMb, memoryTotalMb, diskUsedGb, diskTotalGb, pools, at
lastSeenAt, createdAtstring or nullISO timestamps
createdBystringDisplay name
autoUpgradebooleanThe daemon installs the release Sailfork announces. Default true
upgradestring or nullThe daemon's own words on its last upgrade, until it reconnects
allowedImages, egressarray or null, string or nullThe host's own policy. Null follows the organization's
schedulable, drainDeadlineboolean, string or nullFalse once cordoned or draining, and when a drain stops what still runs
privateEgressbooleanIts outbound sandboxes may reach private networks
enrolledbooleanIt connects with an enrolled key instead of its token
labelsstring arrayk=v labels from drydockd --label
poolbooleanIts daemon takes more than one tenant
limitsstring arrayWhat 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://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.

RouteEffect
cordonThe host takes no new sandboxes. What runs on it carries on, and requests only it could take wait in their queue
uncordonMakes it schedulable again and also ends a drain
drainCordons 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://sailfork.com/api/orgs/acme/compute/hosted

Sandboxes

Create a sandbox

POST /api/orgs/{org}/sandboxes

Members, scope sandbox. Every field is optional.

FieldTypeMeaning
imagestringDefault buildpack-deps:noble-scm
vcpus, memoryMbnumberDefault 2 and 2048
diskGbnumber1 to 1024, default 5
networkoutbound or noneoutbound when the host allows it
minutesnumberLifetime, 1 to 1440, default 60
hoststringA host name. Any online host with room otherwise
labelsstring arrayHost labels it needs, all of them, at most 16
envobjectEnvironment set for every command
repo, refstringPut owner/name code in /work, at a branch, tag or commit. The default branch when ref is absent
caissonstringA caisson id: its branch head plus uncommitted edits. Excludes repo (422)
waitSecondsnumber0 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
cachebooleanMount the host's dependency cache (with repo) or the caisson workspace volume (with caisson). false opts out
freshWorkspacebooleanWith caisson: discard its workspace volume first. 422 otherwise
stopdestroy, files or checkpointWhat a stop, the expiry and the minute limit keep. Default destroy. files archives keepPaths. checkpoint also saves memory and processes as a gVisor checkpoint
keepPathsstring arrayAbsolute paths, default ["/work"], at most 16, none of /, /proc, /sys, /dev
classguaranteed or borrowDefault 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://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:

StatusMeaning
201A host took it within about 2 seconds. It runs, or failed starting
202State queued with queuePosition, because every host is full. Follow events. A queued sandbox that has not started by its minutes fails
400, 422No 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
404Unknown host
429quota_exceeded: past the per-member or per-organization count. Queued sandboxes count
502code_failed: the host could not take the code
503no_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:

FieldMeaning
statequeued, leased, starting, running, lost, stopping, kept, suspended, stopped or failed
queuePositionWhile queued: 1 is the next of its owner's sandboxes to start
host{ id, name }, or null once its host was removed
errorWhy it failed
expiresAt, stoppedAt, startedAtISO 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)
commandRunningA command is running in it now
idle{ seconds, limitSeconds } for a running sandbox with nothing in flight
stop, keepPathsWhat a stop keeps
class, reclaimsIts class and how many times it was evicted and queued again
noticeThe last thing worth telling you, such as a checkpoint restored as files only
usagecpuMilli, 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 }.

QueryMeaning
statelive (default) is queued, leased, starting, running, stopping or lost. all adds kept, suspended and ended ones
limit1 to 200, default 200
cursorThe nextCursor of the previous page. Null on the last page
caissonA 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://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.

EventMeaning
{ "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.

StatusMeaning
409not_running
502keep_failed: the host could not save
503keep_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:

FieldTypeMeaning
commandstringRun by /bin/sh -c. Send this or argv
argvstring arrayA program and its arguments
cwdstringDefault: the sandbox's workdir
envobjectOver the sandbox's env
timeoutSecondsnumberDefault 120, max 3600
stdinstringInput for the command
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
  -d '{"argv":["node","--version"]}' https://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.

StatusMeaning
409stopped, or not_running while the sandbox is queued or starting (also for files)
429host_busy with Retry-After: 1: the sandbox already runs 8 calls or its host 64 (also for files)
503host_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://sailfork.com/api/sandboxes/sbx_7f3k2m9q/files?path=/work/notes.txt&mode=644"

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.

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://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/"
}
StatusMeaning
409not_running, no_network, or preview_unsupported when the host's drydockd does not run previews
429The sandbox has 3 open previews, its organization (else owner) has 10, or its links served 2 GiB
503previews_off: the server has no preview domain
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.

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.

FieldTypeMeaning
maxPerMembernumber or nullLive sandboxes one member may run at once, 1 to 10000
maxPerOrgnumber or nullLive member sandboxes the organization runs at once, 1 to 10000
maxVcpusnumber or nullPer sandbox, 1 to 256
maxMemoryMbnumber or nullPer sandbox, 256 to 4194304
maxMinutesnumber or nullPer sandbox in total, extensions included, 1 to 1440
allowedImagesstring array or nullImage 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
egressoutbound, none or nullnone 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
minRunscVersionstring or nullOldest gVisor a gVisor host may run, such as release-20240311.0
allowContainerIsolationboolean or nullfalse keeps sandboxes off plain-container hosts
allowPrivateEgressboolean or nullfalse keeps sandboxes off hosts whose sandboxes reach private networks
lostGraceMinutesnumber or nullA lost sandbox fails after this, 0 to 1440, default 30
upgradeWindowobject or nullWhen 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
pinnedVersionstring or nullNewest drydockd release hosts upgrade to. Null follows Sailfork's
allowBorrowboolean or nullfalse 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://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.

FieldRules
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
value1 byte to 32 KiB, no NUL. Optional for an existing secret, to change only its grants. 422 for a new one without it
reposowner/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://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.

FieldTypeMeaning
agent, ciobjectWhen that kind of work may overflow: { "mode": "never" | "immediately" | "after", "afterSeconds": 30 }. afterSeconds is 0 to 86400, otherwise 422
pinSecretJobsbooleanWork given sandbox secrets stays on your own hosts
updatedAtstring or nullNull 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://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.

FieldTypeMeaning
credentialsobjectAWS: { "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
regionstringAWS region such as us-east-1, or Hetzner location such as fsn1
instanceTypesstring array1 to 20 from the kind's catalog
maxHostsnumber1 to 50
idleMinutesnumber1 to 1440, default 10
spotbooleanAWS only: CI machines as one-time spot instances
imagestringAWS: an AMI id or resolve:ssm:..., default Canonical's Ubuntu 24.04. Hetzner: an image, default ubuntu-24.04
subnetId, securityGroupIdsstring, string arrayAWS only, at most 5 security groups
networks, firewallsnumber arraysHetzner 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://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.

Loading Sailfork