What are Sessions?
A Session is a named, persistent terminal environment that preserves your terminal state. Sessions allow you to:- Detach and reattach: Disconnect and reconnect later — from the dashboard or the CLI — to find your terminal exactly as you left it
- Run persistent processes: Keep long-running processes (servers, watchers, builds) running while disconnected
- Access anywhere: Connect to sessions from the web dashboard or your local terminal with the Devbox CLI
Sessions are managed from the dashboard and the Devbox CLI. The TypeScript SDK has no session API:
devbox.terminal.open() opens a transient terminal that ends when you close it, and is not listed as a session.Creating Sessions
A session is created the first time you connect to a name, or declared up front so it exists as soon as the Devbox starts.- CLI
- Dashboard
- Spec file
Run Or name both up front. The session is created if it does not already exist:
devbox session connect with no arguments. The CLI prompts you to pick a Devbox, then lists its sessions alongside a + New session option. If the Devbox has no sessions yet, it asks for a name instead:Managing Sessions
Viewing Sessions
- CLI
- Dashboard
List the sessions on a Devbox:Omit the Devbox name to pick one from a list. The table shows each session’s name and creation time.Add
--output json to include the command a session was started with:Connecting to a Session
Connecting takes exclusive control of a session. If another dashboard tab or CLI connection was attached, it is detached.- CLI
- Dashboard
Connect to a session from your local terminal. The CLI prompts you to pick a Devbox and then a session:Name either one, or both, to skip the prompts:
If the Devbox is paused, it is automatically resumed before connecting.
Deleting Sessions
- Dashboard
Hover over a session in the sidebar and click the close button to delete it. This terminates any running processes in that session.
Sessions vs. Regular Terminals
Use Cases
Development Servers
Run your dev server in a session. The server keeps running when you close your browser, and all logs are available when you reconnect.Multiple Workstreams
Create separate sessions for different tasks: a dev server, test runner, and general shell. Switch between them instantly without losing context.Long-Running Tasks
Start a build or test suite in a session, then disconnect and check the results later. For non-interactive runs you don’t need to attach to,devbox exec -d starts a command detached and devbox logs collects its output.
Next Steps
Remote Development
SSH access and SSH config for a Devbox.
Devbox Lifecycle
Lifecycle operations, machine sizes, workspace defaults, and monitoring.
Executing Commands
Run commands in a Devbox with
devbox exec and read their output with devbox logs.Custom Images
Build custom base images with your tools and runtimes pre-installed.