CLI

Install the sail command-line tool, plus every command grouped by area

The sail CLI manages Sailboxes and apps from the terminal. It is a single native binary with no runtime dependencies. Run sail --help or sail <command> --help for the same information at the prompt, and see the Sailboxes guide for what you can do with it.

Install

macOS and Linux

curl -fsSL https://cli.sailresearch.com/install.sh | sh

Installs the latest sail into ~/.sail/bin. If that directory is not on your PATH, the installer adds it to your shell startup files and prints the line to run in the current shell.

Windows

irm https://cli.sailresearch.com/install.ps1 | iex

Installs sail.exe into %LOCALAPPDATA%\sail\bin and puts that directory at the front of your user PATH. Restart your shell afterward.

pip

pip install sail

The Python SDK includes the CLI: sail is on your PATH in that environment, and pip install -U sail updates it.

To pin a version, set SAIL_CLI_VERSION for the installer, substituting the release you want for X.Y.Z:

curl -fsSL https://cli.sailresearch.com/install.sh | SAIL_CLI_VERSION=X.Y.Z sh

SAIL_HOME relocates sail’s home directory, and SAIL_INSTALL_DIR installs a copy at an exact path for provisioning scripts.

Update

sail update

Downloads the latest release and replaces the binary you ran. Sail warns when your CLI version is nearing the end of its support window, and rejects one past it with an update error before any operation runs. Upgrading a Sailbox is a different operation: sail box upgrade <sailbox>.

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 features the one-shot commands lack: line editing and history, a picker menu when you omit a Sailbox id, and confirmation prompts.

sail shell

The individual sail <command> subcommands 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).

Claude Code

Run sail claude --completion-window balanced for a Claude Code session using Sail. The flag accepts asap or balanced; omitting it uses Sail’s default window. sail claude on saves routing in Claude Code settings, sail claude off removes it, and sail claude env prints the environment settings. See Claude Code for window selection and replacing a saved Flex setting.

Authentication

sail auth login [--api-key <key>]   # log in via the browser, or store a key with --api-key (or piped to stdin)
sail auth whoami                    # show the active key
sail auth logout                    # remove the stored key

Every command reads SAIL_API_KEY, falling back to the credential stored by sail auth login. Add --json to any command for machine-readable output. See Configuration.

If the stored key is still valid and tied to your own account, sail auth login reports that login and returns without opening the browser. To log in as a different organization or user, run sail auth logout first. A key passed with --api-key or piped to stdin always replaces 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

Command	Description
sail box show <id>	Show one Sailbox.
sail box top	Live top-style view of Sailbox usage.
sail box list	List Sailboxes in the current org (see flags below).
sail box terminate <id>	Permanently terminate a Sailbox.
sail box sleep <id>	Checkpoint and release compute (--wake-at to schedule a wake).
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 (--name, --ttl-seconds).
sail box from-checkpoint <checkpoint-id> --name <name>	Create a new Sailbox from a checkpoint, called name. --no-restore-memory boots it fresh from the checkpoint’s disk instead of resuming its memory.
sail box upgrade <id>	Upgrade the runtime (now if running, else at next wake).
sail box auto-sleep <id> <value>	Change when Sail may sleep it: never, auto, or 1 through 3600 idle seconds (0 is the same as auto; other numeric values are rejected).

Checkpoints

sail checkpoint list [--name <name>] [--sailbox <id>] [--app-id <id>]   # newest first
sail checkpoint get <checkpoint-id>
sail checkpoint delete <checkpoint-id>

sail checkpoint list shows the checkpoints a Sailbox can still be started from. sail checkpoint delete makes a checkpoint unusable for new Sailboxes; Sailboxes already started from it keep running.

sail box create

sail box create --app <name> --name <name> [options]

Option	Description
--app <name>	App name (created if missing). Required.
--name <name>	Sailbox name within the app. Required.
--arch <arm|amd>	Base image architecture (default amd).
--port <n>	HTTP ingress port to expose. Repeatable.
--size <s|m|l>	Resource size (default m): s = 1 vCPU, 16 GiB memory, 32 GiB disk; m = 4 vCPU, 32 GiB memory, 128 GiB disk; l = 8 vCPU, 64 GiB memory, 256 GiB disk. Ongoing billing is by usage. Each size also has a one-time creation charge. s gives the fastest cold starts and resumes.
--max-lifetime-seconds <n>	Terminate after this wall-clock lifetime, including sleep and pause. Omit for unlimited. Also accepted by box from-checkpoint.
--memory-limit-gib <n>	Memory ceiling in whole GiB, within the size’s range: 2-64 for s, 8-128 for m, 16-256 for l. The size’s default when omitted.
--disk-limit-gib <n>	Disk ceiling in whole GiB, within the size’s range: 8-128 for s, 32-512 for m, 64-1024 for l. The size’s default when omitted.
--visibility <org|private>	Who may operate the Sailbox: org (the default) lets anyone in your org. private restricts all access to you (creator-only) and requires an API key created by your user. An org admin can override some operations on a private Sailbox with a recorded reason.
--enable-ssh	Expose port 22, trust your org’s CA, and start sshd.
--identity-file <path>	Local SSH key to authenticate with (implies --enable-ssh).
--auto-sleep <value>	When Sail may sleep it on its own: auto (sleep when fully idle, wake the moment anything needs it; the default), never (stays running unless you stop it yourself), or a whole number of idle seconds from 1 through 3600 that replaces the default (0 is the same as auto; other numeric values are rejected).
--no-egress	Stop every outbound connection and name lookup. Inbound connections still work, so --enable-ssh and --port do too. Conflicts with the other egress flags. See No egress and no network.
--no-network	Cut the Sailbox off from the network entirely: no outbound connections, no name lookups, and no exposed ports or SSH. Running commands, the shell, and mounted volumes keep working. Conflicts with --port, --enable-ssh, --identity-file, and the other egress flags. See No egress and no network.
--egress-allow-only <host>	Allow outbound connections only to these destinations (comma-separated or repeated, up to 128): hostnames such as api.github.com, *. wildcards such as *.github.com for any host below it, IPv4 addresses, or ranges such as 203.0.113.0/24. Inbound ports and SSH are unaffected. Conflicts with --no-egress, --no-network, and the two --egress-policy flags. See Egress policy.
--egress-block-host <host>	Remove destinations from what the Sailbox may otherwise reach (comma-separated or repeated, up to 128). With --egress-allow-only, block a hostname under an allowed *. wildcard, or an address or range inside an allowed range. On its own, block an IPv4 address or range. A hostname on its own is not supported. See Blocked.
--egress-policy <id>	Run the Sailbox under a saved egress policy, created with sail egress-policy create. A saved policy holds everything the host flags can express, plus rules for HTTPS requests, such as adding a credential to every request sent to one host. Conflicts with the other egress flags.
--egress-policy-file <path>	Run the Sailbox under the egress policy document in this JSON file (- reads standard input). A document that references a secret must be saved first. Conflicts with the other egress flags.

sail box list

Option	Description
--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.

sail box top

Option	Description
--app <name>	Filter by app name.
--status <status>	Filter by status.
--search <text>	Filter by id/name substring.
--refresh <seconds>	Refresh interval in seconds, 1 through 60 (default 2).
--limit <n>	Maximum active rows to display, 1 through 200 (default 50).

Run commands and connect

sail box exec

Run a command in a Sailbox, streaming its output.

sail box exec [options] <id> -- <command> [args...]

Option	Description
--cwd <dir>	Working directory inside the guest.
--timeout <dur>	Kill the command after this long (e.g. 30s, 5m).
-e, --env <K=V>	Environment variable for the command (repeatable).
--user <spec>	Run as this user: a name or numeric uid, optionally with a group after a colon (alice, 1000, alice:staff). Default: the image’s USER, else root. Pass 0:0 to force root.
-i, --stdin	Pipe local stdin to the guest command.
-t, --tty	Run under a pseudo-terminal driven by your terminal.
--no-forward	With --tty, turn off all local forwarding (browser, ports, paste/clipboard).
--background	Start the command and leave it running in the Sailbox, returning once the Sailbox has accepted it. Output is not 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 flags (--arch, sizing, --port) plus --name (default run-<hex>), --cwd, --timeout, --env, --user, --auto-sleep (as on create, for use with --keep), the egress policy flags (--no-egress, --no-network, --egress-allow-only, --egress-block-host, --egress-policy, and --egress-policy-file, as on create), and --keep (leave the Sailbox running instead of terminating it). An exposed port is reachable while the command runs, and after it ends only with --keep.

sail box shell

sail box shell <id> [--shell <path>] [--user <spec>] [--env <K=V>]... [--no-forward]

Open an interactive shell inside a running Sailbox. This is the simplest and preferred way in: it runs a PTY over exec, so it does not open a port and does not count against your org’s raw-TCP endpoint limit. (Not to be confused with sail shell, the local REPL for managing boxes.)

The session runs as the image’s USER, or as root when the image sets none: the same identity sail box exec uses. --user opens it as someone else (a name or numeric uid, optionally with a group after a colon, like alice, 1000, or alice:staff). --user 0:0 forces root. --env K=V (or -e, repeatable) adds environment variables to the session, as on sail box exec.

While the shell is open, the session forwards to your machine:

• Browser opens. When a program in the box opens a browser, the page opens in your local browser instead. This covers logins like claude login, codex login, and gh auth login. A login that redirects to a localhost callback completes end to end.
• Localhost servers. A server the box starts on localhost (say a dev server on port 3000) becomes reachable at http://localhost:3000 on your machine. The same port is used on your machine, so if it is already in use locally that server is not forwarded.
• Paste and drag-and-drop. Files dragged onto the terminal upload to /tmp/sail-drops in the box and paste as their guest paths. Press Ctrl+V to forward your clipboard. On devbox images an image or text is placed on the box’s clipboard, so pasting a screenshot into claude or codex works as it does locally, and text copied inside the box is copied back to yours. On other images a Ctrl+V image uploads as a file and pastes its path, while text uses your terminal’s own paste. Large uploads show a progress line. Press Esc to cancel one.

Pass --no-forward to turn all of it off, for example for an untrusted or automated session. sail box exec --tty forwards the same way and takes the same flag.

A dropped connection does not end the session. The shell prints a notice, keeps reconnecting, and redraws the screen once the Sailbox is reachable again. If the Sailbox goes to sleep, the next key you press wakes it and resumes the same session. If it is paused, the shell says so when you press a key and sends your keys once the Sailbox is resumed. To leave while disconnected or paused, press Ctrl-D. The session ends if the Sailbox is terminated. sail box exec --tty reconnects the same way.

sail box cp

sail box cp <src> <dst> [--recursive] [--user <spec>]

Copy a file or directory to or from a Sailbox. <id>:<path> denotes the remote side. Uploaded files belong to the image’s USER, or to root when the image sets none: the same identity sail box exec runs commands as. --user names a different owner for the file and any directories the upload creates (a name or numeric uid, optionally with a group after a colon, like alice, 1000, or alice:staff). --user 0:0 forces root. --user applies to uploads only. Downloaded files are owned by whoever runs the CLI.

Pass --recursive (-r) to copy a directory: the source directory’s contents are copied into the destination directory, which is created if needed. Copying a directory requires the flag. With --recursive, --user sets the owner of the copied entries, the destination directory, and any missing parents the copy creates.

Networking

sail box expose <id> <guest-port> [--tcp] [--allowlist <addr|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 an address or a range (e.g. 203.0.113.0/24), or, for HTTP listeners, a Sail app name. Re-exposing a port replaces its whole list. Omitting --allowlist reopens the port. See Access Control for the full model.

Secrets and egress policies

Store a secret for your organization, save an egress policy whose rules use it, then give that policy to a Sailbox. See Egress policy for the policy document and Credential injection for a complete example.

sail secret set <name> [--from-env <variable>]  # prompt for a value, read an environment variable, or read piped input
sail secret show <name>                         # show the name and timestamps, never the value
sail secret list                                # list secret names and timestamps
sail secret delete <name>

sail egress-policy create <name> --file <path>  # use --file - to read JSON from standard input
sail egress-policy show <policy-id>
sail egress-policy list [--search <text>] [--limit <n>] [--offset <n>]
sail egress-policy rename <policy-id> <name>
sail egress-policy delete <policy-id>

sail box egress-policy show <sailbox-id>
sail box egress-policy set <sailbox-id> --egress-policy <policy-id>
sail box egress-policy set <sailbox-id> --egress-policy-file <path>
sail box egress-policy set <sailbox-id> --egress-allow-only <host>[,<host>...] [--egress-block-host <host>[,<host>...]]
sail box egress-policy set <sailbox-id> --no-egress
sail box egress-policy set <sailbox-id> --no-network
sail box egress-policy clear <sailbox-id>

set replaces the Sailbox’s whole policy and clear removes it. A change applies to connections opened after it. --no-network is refused while the Sailbox exposes ports or SSH.

Cron jobs

sail box cron runs a shell command in a Sailbox on a schedule, waking the Sailbox when a run is due.

sail box cron add <id> "<schedule>" "<command>" [--timezone <tz>] [--cwd <dir>] [--user <spec>] [--env <K=V>]... [--timeout <dur>]
sail box cron list <id>
sail box cron remove <id> <cron-job-id>

See Run a command on a schedule for the schedule format and how runs behave.

Custom domains

sail box domain serves a Sailbox HTTP listener on a hostname you own, with TLS certificates obtained and renewed for you.

sail box domain target                             # print the custom-domain and wildcard certificate targets
sail box domain attach <id> <domain> --port <guest-port>  # attach a domain to an exposed HTTP listener
sail box domain list <id>                          # list the domains attached to a Sailbox
sail box domain detach <id> <domain>               # stop routing a domain to the Sailbox

attach requires --port naming an exposed HTTP listener, and checks that your DNS record points at your target first. See Custom domains for the DNS setup, apex-domain options, and certificate behavior.

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 does not need an open port. Use SSH when you need a real SSH endpoint rather than a PTY over exec, such as for 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 raw-TCP endpoint limit.

sail box ssh enable <id> [--identity-file <path>] [--allowlist <addr>]... [--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. --allowlist <addr> restricts the sources allowed to reach port 22 to an address or a range (repeatable). Passing --allowlist replaces the port’s current restriction. Omitting it on a first enable leaves port 22 open to any source. On a re-enable it keeps the existing restriction.
• 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.

Devboxes

sail box devbox creates and manages devboxes: Sailboxes set up for development, with SSH, coding-agent CLIs, and your local Python version. See Devboxes for the full guide, including ~/.sail/devbox.toml.

sail box devbox up [<name-or-id>] [options]
sail box devbox list [--app <name>] [--all]
sail box devbox show <name-or-id> [--app <name>]
sail box devbox down <name-or-id> [--app <name>] [--yes]

sail box devbox up

up creates the devbox with the given name (default devbox), or sets it up again if you already set it up from this machine. For a shared devbox, include --shared each time. Pass a Sailbox id to set up an existing Sailbox instead. It keeps its own name, app, architecture, and image.

Option	Description
--app <name>	App the devbox belongs to, created if missing (default devboxes).
--arch <arm|amd>	Architecture for a new devbox (default amd).
--shared	Let everyone in your organization use a new devbox. Your agent logins are not copied onto a shared devbox.
--with <agents>	Install only these agents. Repeat the flag or separate names with commas.
--without <agents>	Skip these agents. Repeat the flag or separate names with commas.
--identity-file <path>	SSH key to connect with. Defaults to ~/.ssh/id_ed25519, then ~/.ssh/id_rsa.
--python <version>	Python version to install for @sail.function (default: this machine’s version). Pass none to skip.
--step-timeout <dur>	Time limit for each setup command on the devbox, from 1s to 24h (default 10m).

The built-in agents are claude, codex, cursor-agent, and opencode. --app, --arch, and --shared apply only to a devbox given by name.

list shows the devboxes you set up from this machine with your current API key. --all also shows deleted devboxes, and ones Sail can’t find in your current organization. show reports one devbox’s state and, while it runs, its agents. down permanently deletes a devbox and its <name>.sail shortcut after asking you to confirm, which --yes skips.

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)