> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sailresearch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Devboxes

> A cloud dev environment with SSH and coding agents, set up in one command

A devbox is a Sailbox set up for everyday development. One command creates it
from the [devbox image](/sailbox-sdk-images), which includes Node, Docker,
compilers, and common developer tools. The same command also:

* 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.function`](/sailbox-sdk-images#sail-function) code runs there
  unchanged.

You need an SSH key on your machine. If you don't have one, create it with
`ssh-keygen -t ed25519`.

```bash theme={null}
sail box devbox up
```

This creates a devbox named `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](/sailbox-sdk-apps) 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](#set-up-an-existing-sailbox).

## Connect

For a terminal, use `sail box shell` with the Sailbox id that `up` prints:

```bash theme={null}
sail box shell sb_0190a3b2-7c4d-7e8f-9a0b-1c2d3e4f5a6b
```

It needs no SSH setup. While it is open, pages the devbox opens (such as an
agent's sign-in page) open in your local browser, and servers it starts on
`localhost` are reachable on your machine. See
[`sail box shell`](/reference/cli#sail-box-shell) for details.

Use SSH for tools that connect over it: your editor's remote mode, the Codex
app's [remote connections](https://learn.chatgpt.com/docs/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`:

```bash theme={null}
ssh my-box.sail
code --remote ssh-remote+my-box.sail /root
cursor --remote ssh-remote+my-box.sail /root
```

You connect as `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](/sailboxes-autosleep) 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](/sailboxes-access-control#choose-who-can-operate-the-sailbox).

A private devbox needs an API key tied to your own account. If you use an
organization service key, run `sail 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:

```toml theme={null}
# Optional: which agents to install (default: all of them).
agents = ["claude", "codex", "pi"]

# Add an agent, or replace a built-in one by reusing its id.
[[agent]]
id = "pi"
install = "npm install -g @earendil-works/pi-coding-agent"

  # Login files to copy onto a private devbox.
  [[agent.creds]]
  local = "~/.pi/agent/auth.json"
  remote = "~/.pi/agent/auth.json"
```

Set `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:

```bash theme={null}
sail box devbox up sb_0190a3b2-7c4d-7e8f-9a0b-1c2d3e4f5a6b
```

The Sailbox gets SSH, the coding agents, and your Python version. It keeps its
own name, app, architecture, and image, and does not get the devbox image's
tools.

## Manage devboxes

```bash theme={null}
sail box devbox list
sail box devbox show my-box
sail box devbox down my-box
```

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