# 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](https://status.sailfork.com/docs/sandboxes). 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](https://status.sailfork.com/docs/api#authentication), [token scopes](https://status.sailfork.com/docs/api#token-scopes), [errors](https://status.sailfork.com/docs/api#errors) and [paging](https://status.sailfork.com/docs/api#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

```http
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.

```sh
curl -H "Authorization: Bearer $SAILFORK_TOKEN" https://status.sailfork.com/api/orgs/acme/drydock/hosts
```

```json
{
  "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

```http
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.

```sh
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

```http
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

```http
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

```http
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

```http
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

```http
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

```http
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](https://status.sailfork.com/docs/billing#hosted-compute) for the price.

```http
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.

```sh
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

```http
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](https://status.sailfork.com/docs/caissons) 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 |

```sh
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
```

```json
{
  "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](#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](#sandbox-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

```http
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

```http
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

```http
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

```http
GET /api/sandboxes/{id}
```

Its creator and the organization's owners. Returns the sandbox. `404` for others.

```sh
curl -H "Authorization: Bearer $SAILFORK_TOKEN" https://status.sailfork.com/api/sandboxes/sbx_7f3k2m9q
```

### Sandbox activity

```http
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

```http
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](#start-a-kept-sandbox) runs it again |
| `{ "type": "notice", "message": "..." }` | Something worth telling the caller |
| `{ "type": "failed", "error": "..." }`, `{ "type": "stopped" }` | The end |

### Extend a sandbox

```http
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

```http
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

```http
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

```http
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

```http
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 |

```sh
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
```

```json
{
  "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](#sandbox-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

```http
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

```http
DELETE /api/sandboxes/{id}/execs/{exec}
```

Creator. Kills a running durable command now. Returns `204`, or `404` once it ended.

### Read a file

```http
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

```http
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`.

```sh
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

```http
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.

```sh
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
```

```json
{
  "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

```http
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

```http
DELETE /api/sandboxes/{id}/previews/{preview}
```

Creator. Returns `204`. The link stops working at once. `404` when unknown.

## Sandbox settings

### Read and replace settings

```http
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.

```sh
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

```http
GET /api/orgs/{org}/drydock/secrets
```

Returns `{ secrets }` by name. Each entry is `{ name, repos, updatedAt }`.

### Set a secret

```http
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.

```sh
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
```

```json
{ "name": "NPM_TOKEN", "repos": ["acme/api"], "updatedAt": "2026-11-10T18:10:00Z" }
```

### Delete a secret

```http
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

```http
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 |

```sh
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

```http
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

```http
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.

```sh
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

```http
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

```http
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`.

---

Every docs page: https://status.sailfork.com/llms.txt
