Skip to main content
The sail CLI manages sailboxes and apps from the terminal. To install it, see Install the CLI. Run sail --help or sail <command> --help for the same information at the prompt.

​
Interactive shell

For interactive use, sail shell is usually the most convenient option. It opens a REPL on your machine that accepts every command below without the leading sail (so box list, box create ...), and adds touches the one-shot commands do not: line editing and history, a picker menu when you omit a sailbox id, and confirmation prompts. 
sail shell
The individual sail <command> subcommands are non-interactive and take their arguments up front, which suits scripts and agents (add --json for machine-readable output). Mind the naming: sail shell is a shell for managing sailboxes from your machine. It is not a shell inside a box. To open a shell inside a running sailbox, use sail box shell (below).

​
Global options

These work on any command.
OptionEffect
--jsonEmit machine-readable JSON instead of human-readable text.
--helpShow help for the CLI or a command.
sail --version prints the CLI version (top-level only). Authentication comes from SAIL_API_KEY, falling back to the credential stored by sail auth login. See Configuration.

​
Authentication

sail auth login [--api-key <key>]   # browser login, or store/validate a key (also reads a piped key)
sail auth whoami                    # show the active key
sail auth logout                    # remove the stored key

​
Apps

sail app find <name>     # find an app by name
sail app create <name>   # create an app (returns the existing one if present)
sail app list            # list apps in the current org

​
Sailbox lifecycle

CommandDescription
sail box show <id>Show a single sailbox.
sail box listList sailboxes in the current org (see flags below).
sail box terminate <id>Permanently terminate a sailbox.
sail box sleep <id>Checkpoint and release compute.
sail box pause <id>Freeze in place.
sail box resume <id>Resume a paused or sleeping sailbox.
sail box checkpoint <id>Checkpoint a running sailbox.
sail box from-checkpoint <checkpoint-id>Create a new sailbox from a checkpoint (--name).
sail box upgrade <id>Upgrade the runtime (now if running, else at next wake).

​
sail box create

sail box create --app <name> --name <name> [options]
OptionDescription
--app <name>App name (created if missing). Required.
--name <name>Sailbox name within the app. Required.
--arch <arm|amd>Base image architecture (default arm).
--port <n>HTTP ingress port to expose. Repeatable.
--size <s|m>Resource size (default m): s = 1 vCPU, 16 GB memory, 32 GB disk; m = 4 vCPU, 32 GB memory, 128 GB disk. Billing is by usage, so a bigger size costs no more on its own. s gives the fastest cold starts, forks, and resumes, and its lower ceilings cap what a runaway workload can consume.
--memory-gib <n>Memory ceiling in whole GiB, within the size’s range: 2-64 for s, 8-128 for m. The size’s default when omitted.
--disk-gib <n>Disk size in whole GiB, within the size’s range: 8-128 for s, 32-512 for m. The size’s default when omitted.
--enable-sshExpose port 22, trust your org’s CA, and start sshd.
--identity-file <path>Local SSH key to authenticate with (implies --enable-ssh).

​
sail box list

OptionDescription
--app <name>Filter by app name.
--status <status>Filter by status.
--search <text>Filter by id/name substring.
--limit <n>Maximum rows.
--offset <n>Rows to skip.

​
Run commands and connect

​
sail box exec

Run a command in a sailbox, streaming its output. 
sail box exec [options] <id> -- <command> [args...]
OptionDescription
--cwd <dir>Working directory inside the guest.
--timeout <dur>Kill the command after this long (e.g. 30s, 5m).
-i, --stdinPipe local stdin to the guest command.
-t, --ttyRun under a pseudo-terminal driven by your terminal.
--backgroundStart the command and return once accepted (no output captured).

​
sail box run

Create an ephemeral sailbox, run a command, then terminate it. A shortcut for create + exec + terminate; for workflows that reuse a sailbox, use those directly. 
sail box run --app <name> [options] -- <command> [args...]
Takes the same create sizing/port flags plus --name (default run-<hex>), --cwd, --timeout, and --keep (leave the sailbox running instead of terminating it).

​
sail box shell

sail box shell <id> [--shell <path>]
Open an interactive shell inside a running sailbox. This is the simplest and preferred way in: it runs a PTY over exec, so it opens no port and does not count against your org’s port allocation. (Not to be confused with sail shell, the local REPL for managing boxes.)

​
sail box cp

sail box cp <src> <dst>
Copy a file to or from a sailbox; <id>:<path> denotes the remote side.

​
Networking

sail box expose <id> <guest-port> [--tcp] [--allowlist <cidr|app>]...  # expose a guest port at runtime
sail box unexpose <id> <guest-port>                                    # remove a runtime ingress port
sail box listeners <id>                                                # list a sailbox's ingress listeners
sail box address <id> <guest-port>                                     # print the external address for one port
--tcp exposes raw TCP instead of HTTP. --allowlist restricts sources to a CIDR prefix (e.g. 203.0.113.0/24), or, for HTTP listeners, a Sail app name. See Networking for the full model.

​
SSH

sail box ssh sets up SSH access so you can reach a box as ssh <name>.sail. For a quick interactive shell, prefer sail box shell: it needs no open port. Reach for SSH when you need a real SSH endpoint rather than a PTY over exec, such as scp/rsync, an editor’s remote mode, or a devbox you work in day to day. Enabling it exposes port 22 as a TCP ingress port, which counts against your org’s port allocation. 
sail box ssh enable <id> [--identity-file <path>] [--no-wait] [--timeout <dur>]
sail box ssh alias <id>... [--identity-file <path>]
sail box ssh disable <id>
  • enable: turn on SSH for a box (expose port 22, install your org’s CA, start sshd), certify your key on this machine, and add the <name>.sail shortcut.
  • alias: add ssh <name>.sail shortcuts for boxes already SSH-enabled elsewhere (e.g. from the SDK), without waking them.
  • disable: stop SSH on a box and drop its local shortcut.
Only the public half of your key is certified; the private key is referenced in your SSH config, never read.

​
Configuration

Manage ~/.sail/config.toml. 
sail config get [key]          # print one value, or the whole file
sail config set <key=value>... # set one or more entries
sail config unset <key>...     # remove one or more keys
sail config reset              # reset user-settable settings (run 'sail auth logout' to remove the stored key)