Connecting to a Devbox

Open a shell on a Devbox with SSH or a session, and choose the one that fits your work, including running coding agents.

Once a Devbox exists, you work in it through a terminal. There are two ways to get one, and they differ in what happens when you close it. An SSH connection lasts as long as your terminal does. A session is a terminal that lives on the Devbox, so whatever runs in it keeps going after you disconnect, and you can come back to it later.

Open a Shell with SSH

devbox ssh opens an interactive shell on the Devbox. The connection is tunneled through the Namespace API, so the Devbox needs no public IP address or open port.

CLI
Omit the name to pick a Devbox from a list:

devbox ssh

Or name it to connect straight away:

devbox ssh my-devbox

Dashboard
Expand the Devbox on the Devboxes page and select the Terminal tab. It opens a shell on the Devbox in your browser, with nothing to install locally.

Connecting to a stopped Devbox starts it first. The shell ends when you exit it or when your connection drops, and so does anything running in the foreground.

Keep Work Running in a Session

A session is a named terminal that runs on the Devbox. Closing your terminal only detaches you from it: the shell and everything running in it keep going, with their output, until you reconnect. Sessions are tmux sessions managed by the Devbox.

CLI

Connect to a session by name. The session is created the first time you use the name:

devbox session connect my-devbox --session work

Run the same command later to pick up where you left off. Run devbox session connect with no arguments to choose a Devbox and a session from a list.

Dashboard
Open the Devbox in the Namespace dashboard and select New session under Sessions in the sidebar. Click a session in the list to reconnect to it.

A session is shared between the CLI and the dashboard. Start a build from your terminal, close the laptop, and check on it later from the dashboard in a browser. One client is attached at a time: connecting from a new place detaches the previous one.

Create one session per stream of work, for example server for a dev server, tests for a test watcher, and shell for everything else. See devbox session to list sessions.

Run a Coding Agent in a Session

A coding agent that works on the Devbox for a long stretch is the clearest case for a session. Over SSH, the agent stops when your laptop sleeps or your network drops. In a session, it carries on without you, and you can reconnect to see what it has done or give it the next task.

1. Connect to a session for the agent

devbox session connect my-devbox --session agent

2. Start the agent

Start your agent in the session, for example claude, codex, or amp, and give it a task.

3. Disconnect and come back later

Close your terminal while the agent works. Reconnect with the same command to check on it:

devbox session connect my-devbox --session agent

A session counts as activity for only 15 minutes after it is created, so a Devbox can stop for being idle while an agent is still working in it. Ask the agent to create a task marker while it works. See Running long tasks.

Choose Between SSH and a Session

Use SSH for short interactive work, for piping local data into a command, and for tools that need an SSH connection. Use a session for anything you want to come back to: a dev server, a long build, or a coding agent.

To run a command without a terminal at all, and keep its output to read later, use devbox exec instead. For a dev server or another process that should restart when it fails and start again every time the Devbox boots, create a service.

Next Steps

Run commands without a terminal and read their output later.

Open a Devbox in VS Code, Cursor, JetBrains, or Zed.

Keep a Devbox running while a build or an agent works.