# CI and sandbox commands

Inspect, rerun and dispatch CI runs, run code in sandboxes on your Drydock machines, and read metered usage.

The guides are [CI](https://status.sailfork.com/docs/ci) and [Sandboxes and Drydock](https://status.sailfork.com/docs/sandboxes).

## sailfork ci

Inspect and control CI runs. Also `sailfork run`.

### sailfork ci list

List recent runs. Also `ci runs`, `ci ls`. Read-only.

```sh
sailfork ci list [flags]
```

| Flag | What it does |
| --- | --- |
| `--limit <LIMIT>` | Most runs to print. Default `30`. |
| `--branch <BRANCH>` | Only runs on this branch. |
| `--workflow <WORKFLOW>` | Only runs of this workflow. |
| `--status <STATUS>` | Only runs in this state. One of `pass`, `fail`, `running`. |
| `--pr <NUMBER>` | Only runs for this pull request: the ones it started and pushes of its head commit. |

Examples:

```sh
sailfork ci list
sailfork ci list --branch main --status fail --limit 5
sailfork ci list --json=id,state,branch,subject
sailfork ci list --pr 12
```

### sailfork ci view

Show a run with its jobs and steps. Also `ci show`. Read-only.

```sh
sailfork ci view <ID> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Run id, from `ci list` |

| Flag | What it does |
| --- | --- |
| `--exit-status` | Exit 1 when the run failed. |

Examples:

```sh
sailfork ci view 481
sailfork ci view 481 --exit-status
sailfork ci view 481 --json --jq '.jobs[] | select(.state == "fail") | .name'
```

### sailfork ci watch

Wait for a run to finish, showing each job as it changes; exits 1 when the run failed. Read-only.

```sh
sailfork ci watch <ID> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Run id, from `ci list` |

| Flag | What it does |
| --- | --- |
| `--interval <SECS>` | Seconds between checks. Default `3`. |

Examples:

```sh
sailfork ci watch 481
sailfork ci watch 481 --interval 10 --json --jq .state
```

### sailfork ci logs

Print a run's logs. Read-only.

```sh
sailfork ci logs <ID> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Run id |

| Flag | What it does |
| --- | --- |
| `-f`, `--follow` | Keep printing until the run finishes. |
| `--job <JOB>` | Only this job (its id) |
| `--step <STEP>` | Only this step: its 0-based index or part of its name. |
| `--tail <N>` | Only the last N lines. |
| `--grep <TEXT>` | Only lines containing this text, ignoring case. |

Examples:

```sh
sailfork ci logs 481
sailfork ci logs 481 --job build --follow
sailfork ci logs 481 --job build --step test --tail 80
sailfork ci logs 481 --grep "error\[" --tail 40
sailfork ci logs 481 --follow --json --jq 'select(.stepName == "test") | .line'
```

### sailfork ci failures

Show only what failed in a run: each failed step's exit code, last log lines and error locations. Read-only.

```sh
sailfork ci failures [ID] [flags]
```

| Argument | What it is |
| --- | --- |
| `[ID]` | Run id (default: the newest failed run on the current branch) |

| Flag | What it does |
| --- | --- |
| `--pr <NUMBER>` | The newest failed run on this pull request's head branch. |
| `--branch <BRANCH>` | The newest failed run on this branch. |
| `--lines <N>` | Log lines to show from the end of each failed step (0 for only the error locations) Default `30`. |

Examples:

```sh
sailfork ci failures
sailfork ci failures 481 --lines 80
sailfork ci failures --pr 12
sailfork ci failures --branch main --lines 0
sailfork ci failures --json --jq '.failures[].errors[] | "\(.file):\(.line) \(.message)"'
```

### sailfork ci artifacts

List a run's artifacts, or download one as a zip with --download. Read-only.

```sh
sailfork ci artifacts <ID> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Run id, from `ci list` |

| Flag | What it does |
| --- | --- |
| `--download <NAME>` | Download this artifact as a zip. |
| `-o`, `--output <OUTPUT>` | Where to save the download ('-' for stdout; default <name>.zip) |
| `--force` | Overwrite the file if it exists. |

Examples:

```sh
sailfork ci artifacts 481
sailfork ci artifacts 481 --download dist
sailfork ci artifacts 481 --download dist --output build/dist.zip
sailfork ci artifacts 481 --json --jq '.artifacts[].name'
```

### sailfork ci caches delete

Delete one cache by id, or every matching cache with --all. Also `ci caches rm`. Changes something. Asks before it acts unless you pass `--yes`. Supports `--dry-run`.

```sh
sailfork ci caches delete [ID] [flags]
```

| Argument | What it is |
| --- | --- |
| `[ID]` | Cache id, from `ci caches` |

| Flag | What it does |
| --- | --- |
| `--all` | Delete every cache of the repository, narrowed by --key and --ref. |
| `--key <PREFIX>` | With --all: only caches whose key starts with this. |
| `--ref <REF>` | With --all: only caches saved on this branch or full ref. |
| `-y`, `--yes` | Confirm; required when there is no terminal to ask on. |
| `--dry-run` | Say what would happen and change nothing. |

### sailfork ci rerun

Run a workflow again. Changes something.

```sh
sailfork ci rerun <ID> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Run id |

| Flag | What it does |
| --- | --- |
| `--failed` | Rerun only the jobs that failed. |
| `--job <JOB>` | Rerun this job and the jobs that need it, keeping the passed jobs' results (repeat for several) Repeatable. |

Examples:

```sh
sailfork ci rerun 481
sailfork ci rerun 481 --failed
sailfork ci rerun 481 --job test
```

### sailfork ci run

Start a workflow that has a workflow_dispatch trigger, with its inputs. Changes something.

```sh
sailfork ci run <WORKFLOW> [flags]
```

| Argument | What it is |
| --- | --- |
| `<WORKFLOW>` | Workflow file name in .github/workflows, like deploy.yml (the extension may be left out) |

| Flag | What it does |
| --- | --- |
| `--ref <REF>` | Branch or tag to run on (default: the default branch) |
| `-f`, `--field <KEY=VALUE>` | An input as key=value (repeat for several) Repeatable. |

Examples:

```sh
sailfork ci run deploy.yml
sailfork ci run deploy --ref v1.4.0 -f environment=staging -f dry-run=true
```

### sailfork ci cancel

Cancel a running run; its unfinished jobs are lost. Changes something. Asks before it acts unless you pass `--yes`. Supports `--dry-run`.

```sh
sailfork ci cancel <ID> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Run id, from `ci list` |

| Flag | What it does |
| --- | --- |
| `-y`, `--yes` | Confirm; required when there is no terminal to ask on. |
| `--dry-run` | Say what would happen and change nothing. |

Examples:

```sh
sailfork ci cancel 481 --dry-run
sailfork ci cancel 481 --yes
```

### sailfork ci secret list

List the repository's secret names. Also `ci secret ls`. Read-only.

```sh
sailfork ci secret list
```

Examples:

```sh
sailfork ci secret list
```

### sailfork ci secret set

Set a secret from stdin (`--value -`); a value on the command line shows in `ps` and shell history. Changes something.

```sh
sailfork ci secret set <NAME> [flags]
```

| Argument | What it is |
| --- | --- |
| `<NAME>` | Secret name, as workflows read it |

| Flag | What it does |
| --- | --- |
| `--value <VALUE>` | The secret, or `-` to read it from stdin. Required. |
| `--environment <NAME>` | Give the secret only to jobs that declare this environment, on runs of the default branch; unset keeps the secret's current environment. |
| `--no-environment` | Remove the secret's environment, so every run of the repository gets it. |

### sailfork ci secret delete

Delete a secret. Also `ci secret rm`. Changes something. Asks before it acts unless you pass `--yes`. Supports `--dry-run`.

```sh
sailfork ci secret delete <NAME> [flags]
```

| Argument | What it is |
| --- | --- |
| `<NAME>` | Secret name |

| Flag | What it does |
| --- | --- |
| `-y`, `--yes` | Confirm; required when there is no terminal to ask on. |
| `--dry-run` | Say what would happen and change nothing. |

Examples:

```sh
sailfork ci secret delete DEPLOY_KEY --dry-run
sailfork ci secret delete DEPLOY_KEY --yes
```

## sailfork sandbox

Run code in isolated sandboxes on the organization's Drydock machines. Also `sailfork sb`.

### sailfork sandbox create

Start a sandbox and print its id. Changes something. Supports `--dry-run`.

```sh
sailfork sandbox create [flags]
```

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization handle (default: the owner of -R or the current clone) |
| `--image <IMAGE>` | Image (default buildpack-deps:noble-scm: git, curl, python3 without pip, apt index empty; try python:3.12-slim, node:22, rust:1, golang:1.23) |
| `--cpus <N>` | CPUs (default 2) |
| `--memory <MB>` | Memory in MB (default 2048) |
| `--disk <GB>` | Disk the sandbox reserves on its host, in GB (default 5) |
| `--label <LABEL>` | Host label the sandbox needs (`gpu`, `region=eu`); repeat for more, all must be present. Repeatable. |
| `--network <NETWORK>` | What the sandbox may reach (default outbound when the host allows it) One of `outbound`, `none`. |
| `--minutes <N>` | Minutes until it stops, 1 to 1440 (default 60) |
| `--on <HOST_NAME>` | Drydock host to run on, by name (default any online host with room) |
| `--wait <SECS>` | Seconds to wait for a queued sandbox to start, 0 to fail at once when no host has room (default 60, at most 600); after it the sandbox stays queued and its id is printed. |
| `--no-cache` | Skip the host's dependency cache (pip, npm, cargo, Go downloads) for this sandbox's repository. |
| `--fresh-workspace` | With --caisson: discard this caisson's workspace volume on the host so /work starts empty. |
| `--env <KEY=VALUE>` | Environment variable for every command; repeat for more. Repeatable. |
| `--ref <REF>` | Branch, tag or commit of -R/--repo, whose code goes in /work where `sandbox exec` runs by default (default: the repository's default branch) |
| `--sparse <FOLDER>` | Only this folder of -R/--repo goes in /work, with the files at the top of the tree and of its parent folders (git's sparse checkout); repeat for more. For a repository too large to send whole. Repeatable. |
| `--caisson <ID>` | Put this caisson's base plus its uncommitted edits in /work, synced again before each exec, so edited code can run; not with -R/--repo. |
| `--stop <STOP>` | What a stop (and the expiry) keeps: destroy (default), files (the --keep paths, restored by `sandbox start`) or checkpoint (files plus memory and processes; open connections do not survive, and it resumes only on a host running the same gVisor release, else the files restore alone) One of `destroy`, `files`, `checkpoint`. |
| `--keep <PATH>` | Absolute path a files or checkpoint stop keeps (default /work); repeat for more, at most 16. Repeatable. |
| `--class <CLASS>` | guaranteed (default) reserves its room; borrow runs in room others reserve but do not use, at a low CPU weight, and is evicted and queued again when they need it back. One of `guaranteed`, `borrow`. |
| `--dry-run` | Print the request that would start the sandbox and start nothing. |

Examples:

```sh
sailfork sandbox create
sailfork sandbox create --org acme --image node:22 --cpus 4 --memory 4096 --minutes 120
sailfork sandbox create --org acme --network none --env CI=1 --json --jq .id
sailfork sandbox create --repo acme/app --ref v1.2.0
sailfork sandbox create --org acme --caisson c-ab12cd
sailfork sandbox create --repo acme/app --dry-run
```

### sailfork sandbox list

List the organization's sandboxes. Also `sandbox ls`. Read-only.

```sh
sailfork sandbox list [flags]
```

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization handle (default: the owner of -R or the current clone) |
| `--all` | Include stopped and failed sandboxes. |
| `--kind <KIND>` | Which sandboxes: agent (the default: started by people and agents), ci (CI jobs'), bake (warm image bakes') or all. Owners only, except agent. One of `agent`, `ci`, `bake`, `all`. |

Examples:

```sh
sailfork sandbox list
sailfork sandbox list --org acme --all --json=id,state,expiresAt
```

### sailfork sandbox view

Show one sandbox. Also `sandbox show`. Read-only.

```sh
sailfork sandbox view <ID> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Sandbox id |

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization the sandbox belongs to; the command fails if the sandbox is in another one. |

Examples:

```sh
sailfork sandbox view sb_7k2m
```

### sailfork sandbox log

Show every command run in the organization's sandboxes: who, where, when, how it ended (owners only). Read-only.

```sh
sailfork sandbox log [flags]
```

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization handle (default: the owner of -R or the current clone) |
| `--limit <LIMIT>` | Most commands to print. Default `50`. |
| `--all` | Print every command, page after page. |
| `--cursor <CURSOR>` | Continue after the cursor a cut list printed. |

Examples:

```sh
sailfork sandbox log --org acme
sailfork sandbox log --org acme --all --json=startedByHandle,argv,exitCode
```

### sailfork sandbox exec

Run a command in a sandbox, streaming its output and exiting with its exit code. Changes something.

```sh
sailfork sandbox exec <ID> <COMMAND...> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Sandbox id |
| `<COMMAND...>` | One argument runs as a shell command line; several run as program and arguments |

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization the sandbox belongs to; the command fails if the sandbox is in another one. |
| `--cwd <CWD>` | Working directory in the sandbox (default: /work when the sandbox was started with code) |
| `--env <KEY=VALUE>` | Environment variable for this command; repeat for more. Repeatable. |
| `--timeout <SECS>` | Seconds before the command is killed (default 120, at most 3600) |
| `--stdin-file <PATH>` | Feed this local file to the command's standard input. |

Examples:

```sh
sailfork sandbox exec sb_7k2m -- npm test
sailfork sandbox exec sb_7k2m --cwd /work --env CI=1 -- "make build && make check"
sailfork sandbox exec sb_7k2m --json -- uname -a
```

### sailfork sandbox cat

Print a file from a sandbox. Read-only.

```sh
sailfork sandbox cat <ID> <PATH> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Sandbox id |
| `<PATH>` | Absolute path in the sandbox |

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization the sandbox belongs to; the command fails if the sandbox is in another one. |

Examples:

```sh
sailfork sandbox cat sb_7k2m /work/report.txt
```

### sailfork sandbox put

Upload a local file into a sandbox. Changes something.

```sh
sailfork sandbox put <ID> <LOCAL> <REMOTE> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Sandbox id |
| `<LOCAL>` | Local file to upload (at most 16 MiB) |
| `<REMOTE>` | Absolute path in the sandbox; missing folders are created |

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization the sandbox belongs to; the command fails if the sandbox is in another one. |
| `--mode <MODE>` | File mode in octal. Default `644`. |

Examples:

```sh
sailfork sandbox put sb_7k2m ./script.sh /work/script.sh --mode 755
```

### sailfork sandbox extend

Set a sandbox to stop this many minutes from now. Changes something.

```sh
sailfork sandbox extend <ID> <MINUTES> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Sandbox id |
| `<MINUTES>` | Minutes from now, 1 to 1440 |

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization the sandbox belongs to; the command fails if the sandbox is in another one. |

Examples:

```sh
sailfork sandbox extend sb_7k2m 90
```

### sailfork sandbox stop

Stop a sandbox now, keeping what it was created to keep (or --mode) for `sandbox start`. Changes something. Asks before it acts unless you pass `--yes`. Supports `--dry-run`.

```sh
sailfork sandbox stop <ID> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Sandbox id |

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization the sandbox belongs to; the command fails if the sandbox is in another one. |
| `--mode <MODE>` | What the stop keeps: destroy (nothing), files (the sandbox's keep paths) or checkpoint (files plus memory and processes; open connections do not survive, and it resumes only on a host running the same gVisor release). Default: the mode the sandbox was created with. One of `destroy`, `files`, `checkpoint`. |
| `-y`, `--yes` | Confirm; required when there is no terminal to ask on. |
| `--dry-run` | Say what would happen and change nothing. |

Examples:

```sh
sailfork sandbox stop sb_7k2m
sailfork sandbox stop sb_7k2m --dry-run
sailfork sandbox stop sb_7k2m --mode files
```

### sailfork sandbox delete

Destroy a sandbox now, kept files and checkpoints included. Also `sandbox rm`, `sandbox destroy`. Changes something. Asks before it acts unless you pass `--yes`. Supports `--dry-run`.

```sh
sailfork sandbox delete <ID> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Sandbox id |

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization the sandbox belongs to; the command fails if the sandbox is in another one. |
| `-y`, `--yes` | Confirm; required when there is no terminal to ask on. |
| `--dry-run` | Say what would happen and change nothing. |

Examples:

```sh
sailfork sandbox delete sb_7k2m --yes
```

### sailfork sandbox start

Run a kept or suspended sandbox again, queued like a new one. Changes something.

```sh
sailfork sandbox start <ID> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Sandbox id |

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization the sandbox belongs to; the command fails if the sandbox is in another one. |
| `--wait <SECS>` | Seconds to wait for room while it is queued (default 60, at most 600); after it the sandbox stays queued. |

Examples:

```sh
sailfork sandbox start sb_7k2m
```

### sailfork sandbox expose

Open a link that serves a port of a running sandbox in a browser, for you or a reviewer. Changes something.

```sh
sailfork sandbox expose <ID> <PORT> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Sandbox id |
| `<PORT>` | The TCP port the sandbox listens on, 1 to 65535 |

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization the sandbox belongs to; the command fails if the sandbox is in another one. |
| `--minutes <MINUTES>` | How long the link works, 1 to 480 (default 60; never past the sandbox's own end) |

### sailfork sandbox previews

List a sandbox's preview links and whether they still work. Read-only.

```sh
sailfork sandbox previews <ID> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Sandbox id |

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization the sandbox belongs to; the command fails if the sandbox is in another one. |

### sailfork sandbox unexpose

Stop a preview link now. Changes something.

```sh
sailfork sandbox unexpose <ID> <PREVIEW> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Sandbox id |
| `<PREVIEW>` | Preview id from `sandbox previews` |

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization the sandbox belongs to; the command fails if the sandbox is in another one. |

### sailfork sandbox host list

List the organization's hosts. Also `sandbox host hosts`, `sandbox host ls`. Read-only.

```sh
sailfork sandbox host list [flags]
```

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization handle (default: the owner of -R or the current clone) |

Examples:

```sh
sailfork sandbox host list --org acme
```

### sailfork sandbox host view

Show a host: its daemon, what its sandboxes reserve, and its disk: free space and what holds it. Read-only.

```sh
sailfork sandbox host view <NAME> [flags]
```

| Argument | What it is |
| --- | --- |
| `<NAME>` | Host name or id |

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization handle (default: the owner of -R or the current clone) |

Examples:

```sh
sailfork sandbox host view build-box-1 --org acme
```

### sailfork sandbox host add

Register a host and print the token its daemon installs with. Changes something.

```sh
sailfork sandbox host add <NAME> [flags]
```

| Argument | What it is |
| --- | --- |
| `<NAME>` | Host name: 1 to 64 of letters, digits, . _ - |

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization handle (default: the owner of -R or the current clone) |

Examples:

```sh
sailfork sandbox host add build-box-1 --org acme
```

### sailfork sandbox host delete

Remove a host; its daemon exits and its live sandboxes fail. Also `sandbox host rm`, `sandbox host remove`. Changes something. Asks before it acts unless you pass `--yes`. Supports `--dry-run`.

```sh
sailfork sandbox host delete <NAME> [flags]
```

| Argument | What it is |
| --- | --- |
| `<NAME>` | Host name or id |

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization handle (default: the owner of -R or the current clone) |
| `-y`, `--yes` | Confirm; required when there is no terminal to ask on. |
| `--dry-run` | Say what would happen and change nothing. |

Examples:

```sh
sailfork sandbox host delete build-box-1 --org acme --dry-run
sailfork sandbox host delete build-box-1 --org acme --yes
```

### sailfork sandbox host upgrade

Upgrade a host's drydockd to the latest release once its plain calls end, or with --auto, set whether it upgrades itself when a release reaches its rollout ring. Changes something.

```sh
sailfork sandbox host upgrade <NAME> [flags]
```

| Argument | What it is |
| --- | --- |
| `<NAME>` | Host name or id |

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization handle (default: the owner of -R or the current clone) |
| `--auto <SWITCH>` | Turn automatic upgrades on or off instead of upgrading now. One of `on`, `off`. |

Examples:

```sh
sailfork sandbox host upgrade build-box-1 --org acme
sailfork sandbox host upgrade build-box-1 --org acme --auto off
```

### sailfork sandbox host cordon

Stop placing new sandboxes on a host; what runs there carries on. Changes something.

```sh
sailfork sandbox host cordon <NAME> [flags]
```

| Argument | What it is |
| --- | --- |
| `<NAME>` | Host name or id |

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization handle (default: the owner of -R or the current clone) |

Examples:

```sh
sailfork sandbox host cordon build-box-1 --org acme
```

### sailfork sandbox host uncordon

Let a cordoned or draining host take new sandboxes again. Changes something.

```sh
sailfork sandbox host uncordon <NAME> [flags]
```

| Argument | What it is |
| --- | --- |
| `<NAME>` | Host name or id |

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization handle (default: the owner of -R or the current clone) |

Examples:

```sh
sailfork sandbox host uncordon build-box-1 --org acme
```

### sailfork sandbox host drain

Cordon a host and stop what still runs on it after a deadline: sandboxes stop, CI jobs start over elsewhere. Changes something.

```sh
sailfork sandbox host drain <NAME> [flags]
```

| Argument | What it is |
| --- | --- |
| `<NAME>` | Host name or id |

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization handle (default: the owner of -R or the current clone) |
| `--deadline <MINUTES>` | Minutes until what still runs on the host is stopped (0 to 1440) Default `30`. |

Examples:

```sh
sailfork sandbox host drain build-box-1 --org acme --deadline 20
```

### sailfork sandbox host policy

Set a host's own image and egress rules, which replace the organization's field by field. Changes something.

```sh
sailfork sandbox host policy <NAME> [flags]
```

| Argument | What it is |
| --- | --- |
| `<NAME>` | Host name or id |

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization handle (default: the owner of -R or the current clone) |
| `--allowed-images <PATTERNS>` | Image patterns sandboxes may use, comma separated (`*` within a path segment, `**` across), up to 50; "none" allows any image the host accepts (on a host: follows the organization) |
| `--egress <EGRESS>` | Network of members' sandboxes: none (off the network), outbound, or host (the host's own rule; on a host: follows the organization) One of `none`, `outbound`, `host`. |

### sailfork sandbox settings view

Show the organization's sandbox limits, host policy and upgrade rules. Also `sandbox settings show`. Read-only.

```sh
sailfork sandbox settings view [flags]
```

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization handle (default: the owner of -R or the current clone) |

Examples:

```sh
sailfork sandbox settings view --org acme
```

### sailfork sandbox settings set

Change the limits, image and egress rules, host policy, alerts and upgrade rules; what is not named keeps its value. Changes something.

```sh
sailfork sandbox settings set [flags]
```

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization handle (default: the owner of -R or the current clone) |
| `--min-runsc-version <VERSION>` | The oldest gVisor a gVisor host may run to take sandboxes, CI included, such as release-20240311.0; "none" clears it. |
| `--container-isolation <SWITCH>` | Whether hosts running plain containers (no gVisor) may take sandboxes, CI included. One of `on`, `off`. |
| `--private-egress <SWITCH>` | Whether hosts whose sandboxes may reach private networks may take sandboxes. One of `on`, `off`. |
| `--lost-grace-minutes <MINUTES>` | Minutes a sandbox whose host went away keeps its place before it fails (default 30) |
| `--pinned-version <VERSION>` | The newest drydockd release hosts upgrade to, such as 0.2.10; "none" follows Sailfork's. |
| `--upgrade-window <WINDOW>` | When hosts may restart into a new drydockd, in UTC: DAYS@HOUR+HOURS with days 0 (Sunday) to 6, such as 6,0@22+6 for Saturday and Sunday from 22:00 for 6 hours; "none" allows any time. |
| `--allow-borrow <BOOL>` | Whether members may start borrow-class sandboxes. One of `true`, `false`. |
| `--alerts <SWITCH>` | Whether the organization's owners get an email when one of its own hosts goes offline or is too full to bake, and again when it recovers. One of `on`, `off`. |
| `--queue-weight <WEIGHT>` | How much of the organization's hosts the repository (-R, else the current clone) gets against its others, 1 to 1000 (default 1); owners only. |
| `--max-per-member <N\|none>` | Live sandboxes one member may run at once. |
| `--max-per-org <N\|none>` | Live member sandboxes the organization runs at once. |
| `--max-vcpus <N\|none>` | vCPUs of one sandbox. |
| `--max-memory-mb <MB\|none>` | Memory of one sandbox, in MB. |
| `--max-minutes <MINUTES\|none>` | Minutes one sandbox may run in total, extensions included. |
| `--allowed-images <PATTERNS>` | Image patterns sandboxes may use, comma separated (`*` within a path segment, `**` across), up to 50; "none" allows any image the host accepts (on a host: follows the organization) |
| `--egress <EGRESS>` | Network of members' sandboxes: none (off the network), outbound, or host (the host's own rule; on a host: follows the organization) One of `none`, `outbound`, `host`. |

Examples:

```sh
sailfork sandbox settings set --org acme --container-isolation off --min-runsc-version release-20240311.0
sailfork sandbox settings set --org acme --upgrade-window 6,0@22+6 --pinned-version 0.2.10
sailfork sandbox settings set --org acme --lost-grace-minutes 60
```

### sailfork sandbox settings export

Print every organization and host setting as one JSON document with stable field names, to diff and review. Read-only.

```sh
sailfork sandbox settings export [flags]
```

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization handle (default: the owner of -R or the current clone) |

### sailfork sandbox secret list

List the organization's sandbox secrets and the repositories they are granted to (never the values). Also `sandbox secret ls`. Read-only.

```sh
sailfork sandbox secret list [flags]
```

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization handle (default: the owner of -R or the current clone) |

Examples:

```sh
sailfork sandbox secret list --org acme
```

### sailfork sandbox secret set

Set a secret from stdin (`--value -`) and the repositories whose sandboxes get it; without --value only the grants of an existing secret change. Changes something.

```sh
sailfork sandbox secret set <NAME> [flags]
```

| Argument | What it is |
| --- | --- |
| `<NAME>` | Secret name, the env var sandboxes see |

| Flag | What it does |
| --- | --- |
| `--value <VALUE>` | The secret, or `-` to read it from stdin; a value on the command line shows in `ps` and shell history. |
| `--grant <OWNER/NAME>` | Repositories (owner/name) of the organization whose sandboxes get it; repeat or comma separate. This list replaces the current grants. Repeatable. |
| `--org <HANDLE>` | Organization handle (default: the owner of -R or the current clone) |

Examples:

```sh
sailfork sandbox secret set DEPLOY_KEY --org acme --grant acme/app
```

### sailfork sandbox secret rm

Delete a secret. Also `sandbox secret delete`. Changes something. Asks before it acts unless you pass `--yes`. Supports `--dry-run`.

```sh
sailfork sandbox secret rm <NAME> [flags]
```

| Argument | What it is |
| --- | --- |
| `<NAME>` | Secret name |

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization handle (default: the owner of -R or the current clone) |
| `-y`, `--yes` | Confirm; required when there is no terminal to ask on. |
| `--dry-run` | Say what would happen and change nothing. |

Examples:

```sh
sailfork sandbox secret rm DEPLOY_KEY --org acme --dry-run
sailfork sandbox secret rm DEPLOY_KEY --org acme --yes
```

### sailfork sandbox cloud list

List the connected cloud accounts (never their credentials). Also `sandbox cloud ls`. Read-only.

```sh
sailfork sandbox cloud list [flags]
```

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization handle (default: the owner of -R or the current clone) |

Examples:

```sh
sailfork sandbox cloud list --org acme
```

### sailfork sandbox cloud add

Connect a cloud account; the secret (AWS secret access key or Hetzner API token) is read with `--secret -`. Changes something.

```sh
sailfork sandbox cloud add [flags]
```

| Flag | What it does |
| --- | --- |
| `--kind <KIND>` | The cloud the account is in. Required. One of `aws`, `hetzner`. |
| `--region <REGION>` | AWS region (us-east-1) or Hetzner location (fsn1) Required. |
| `--type <TYPE>` | Instance or server types machines may use, the smallest that fits is picked; repeat or comma separate. Required. Repeatable. |
| `--max-hosts <MAX_HOSTS>` | The most machines running at once, 1 to 50. Required. |
| `--idle-minutes <IDLE_MINUTES>` | Minutes a machine may sit without a sandbox before it is terminated (default 10) |
| `--secret <SECRET>` | The AWS secret access key or Hetzner API token, or `-` to read it from stdin; on the command line it shows in `ps` and shell history. Required. |
| `--access-key-id <ACCESS_KEY_ID>` | AWS access key id. |
| `--role-arn <ROLE_ARN>` | AWS role to assume with the keys. |
| `--external-id <EXTERNAL_ID>` | External id the AWS role's trust policy asks for. |
| `--spot` | AWS: start machines for CI work as spot instances. |
| `--image <IMAGE>` | AMI id or resolve:ssm: parameter (AWS), image name or id (Hetzner); default Ubuntu 24.04. |
| `--subnet <SUBNET>` | AWS subnet id. |
| `--security-group <ID>` | AWS security group id; repeat or comma separate. Repeatable. |
| `--network <ID>` | Hetzner network id; repeat or comma separate. Repeatable. |
| `--firewall <ID>` | Hetzner firewall id; repeat or comma separate. Repeatable. |
| `--org <HANDLE>` | Organization handle (default: the owner of -R or the current clone) |

### sailfork sandbox cloud rm

Disconnect a cloud account, terminating its machines first. Also `sandbox cloud delete`. Changes something. Asks before it acts unless you pass `--yes`. Supports `--dry-run`.

```sh
sailfork sandbox cloud rm <ID> [flags]
```

| Argument | What it is |
| --- | --- |
| `<ID>` | Cloud account id, from `sailfork sandbox cloud list` |

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization handle (default: the owner of -R or the current clone) |
| `-y`, `--yes` | Confirm; required when there is no terminal to ask on. |
| `--dry-run` | Say what would happen and change nothing. |

Examples:

```sh
sailfork sandbox cloud rm 3f2a9c1e-0d4b-4e8a-9b1f-6c7d8e9f0a1b --org acme --yes
```

### sailfork sandbox cloud machines

List the machines started in the connected accounts. Read-only.

```sh
sailfork sandbox cloud machines [flags]
```

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization handle (default: the owner of -R or the current clone) |

Examples:

```sh
sailfork sandbox cloud machines --org acme --json
```

### sailfork sandbox overflow show

Show the overflow policy. Also `sandbox overflow view`. Read-only.

```sh
sailfork sandbox overflow show [flags]
```

| Flag | What it does |
| --- | --- |
| `--org <HANDLE>` | Organization handle (default: the owner of -R or the current clone) |

Examples:

```sh
sailfork sandbox overflow show --org acme
```

### sailfork sandbox overflow set

Change the overflow policy; flags left out keep their value. Changes something.

```sh
sailfork sandbox overflow set [flags]
```

| Flag | What it does |
| --- | --- |
| `--agent <WHEN>` | For agent sandboxes: never, immediately, or seconds to wait for the organization's own hosts. |
| `--ci <WHEN>` | For CI jobs: never, immediately, or seconds to wait for the organization's own hosts. |
| `--pin-secret-jobs <SWITCH>` | Keep work that gets sandbox secrets on the organization's own hosts. One of `on`, `off`. |
| `--org <HANDLE>` | Organization handle (default: the owner of -R or the current clone) |

Examples:

```sh
sailfork sandbox overflow set --org acme --ci immediately --agent 60 --pin-secret-jobs off
```

## sailfork usage

Show metered usage for a month. Read-only.

```sh
sailfork usage [flags]
```

| Flag | What it does |
| --- | --- |
| `--org <ORG>` | Show an organization's usage instead of yours. |
| `--month <MONTH>` | Month as YYYY-MM (default: the current UTC month) |

Examples:

```sh
sailfork usage
sailfork usage --month 2026-10 --org acme
```

---

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