- sets up SSH, so your editor and other SSH tools can connect;
- installs the Claude Code, Codex, Cursor Agent, and opencode CLIs, and copies their logins from your machine where it can;
- installs the Python version you use locally, so
@sail.functioncode runs there unchanged.
ssh-keygen -t ed25519.
devbox and prints how to connect. Pass a name to
create another one, for example sail box devbox up my-box. Devboxes go in an
app called devboxes, which is created the first time you
need it. Pass --app to use a different app.
Run up again at any time. If you already set up that devbox from this
machine, up sets it up again and updates its agents. Your files stay as they
are. For a shared devbox, include --shared each time. To set up a devbox you
made on another machine, or a teammate’s shared one, pass its Sailbox id as
shown below.
Connect
For a terminal, usesail box shell with the Sailbox id that up prints:
localhost are reachable on your machine. See
sail box shell for details.
Use SSH for tools that connect over it: your editor’s remote mode, the Codex
app’s remote connections,
and file copies with scp or rsync. up adds a shortcut named after the
devbox to your SSH config, such as my-box.sail:
root, so /root is your home folder. If your SSH config
already uses that shortcut for another Sailbox, the new one gets a short suffix, such
as my-box-1a2b3c.sail. up prints the one to use.
Like any Sailbox, a devbox goes to sleep when idle,
unless its auto-sleep is set to never.
Connecting with SSH wakes it.
Private and shared devboxes
A devbox is private by default. Only you can use it, although an organization admin can act on it by giving a reason, which is recorded in the audit log. See who can operate a Sailbox. A private devbox needs an API key tied to your own account. If you use an organization service key, runsail auth login first.
Pass --shared to create a devbox that everyone in your organization can use.
You choose this when the devbox is created and can’t change it later.
Coding agents
On a private devbox,up copies the Claude Code, Codex, and opencode logins
from your machine, including a Claude Code login stored in the macOS Keychain.
macOS may ask you to allow that. It also copies Claude Code’s default
permission mode. If an agent has no login on your machine and you run up in
a terminal, it offers to sign the agent in on the devbox. The summary up
prints at the end lists any agent still signed out, so you can sign it in from
sail box shell.
On a shared devbox, up installs the agents but does not copy your logins.
Everyone connects as the same root user, so anyone who can reach a shared
devbox can use a login stored on it. Keep personal logins on a private devbox.
To install only some agents, use --with or --without, for example
--with claude,codex.
Add your own agents
To add an agent, or change how a built-in one is installed, create~/.sail/devbox.toml on your machine:
id to the command that starts the agent. Each [[agent]] can set
install (the command that installs it), login (a command that signs in
when no login was copied), and any number of [[agent.creds]] files to copy.
Reusing a built-in id such as claude replaces that agent completely.
Set up an existing Sailbox
Pass a Sailbox id instead of a name to set up a Sailbox you created, or a shared one:Manage devboxes
list shows the devboxes you set up from this machine with your current API
key, and whether each one is running. show reports one devbox’s state and,
while it is running, which agents are installed.
down permanently deletes a devbox, including everything on its disk, and
removes its SSH shortcut. It asks you to confirm first. Pass --yes to skip
the question. show and down also accept a Sailbox id.