Devbox Lifecycle

A Devbox exists until you delete it. In between it starts when you connect, stops when it goes idle, and keeps its persistent storage across both.

Listing Devboxes

See which Devboxes exist and what state they are in.

CLI
TS SDK
Dashboard

devbox list

This shows only your Devboxes. See devbox list for JSON output and for including other members’ Devboxes.

const page = await client.devboxes.list({
  limit: 20,
  orderBy: "last-used",
});

page.items.forEach((devbox) => console.log(devbox.info));

Listing skips per-Devbox runtime lookups, so each handle reports info.state as "unknown". Call refresh() on a handle before relying on its state. Use devboxes.iterate() to walk every page automatically.

Starting & Stopping

Stopped Devboxes retain all persistent storage and resume in seconds.

CLI
TS SDK
Dashboard

Devboxes start automatically when you connect with devbox ssh or devbox open-ide. To stop one:

devbox shutdown

devbox stop is an alias. See devbox shutdown for its options.

await client.devboxes.start("my-devbox");
await client.devboxes.stop("my-devbox");

start() waits for the Devbox to become ready. Connection-backed operations such as commands, files, and terminals start a stopped Devbox on their own, so call start() explicitly only when you need to wait for readiness first.

A stopped Devbox shows a Start button. A running one shows the Open VSCode dropdown, and can be stopped from its ... menu or from the Devbox detail page.

Deleting

Deleting a Devbox permanently removes it and its persistent volume. This cannot be undone.

CLI
TS SDK
Dashboard

devbox delete my-devbox

See devbox delete for skipping the confirmation and for its aliases.

await client.devboxes.delete("my-devbox");

There is no confirmation step. Use devbox.delete() when you already hold a handle, and do not use that handle afterwards.

Open the ... menu on a Devbox and select Delete.

Idleness & Auto-Stop

A Devbox stops on its own once it has been idle for the length of its idle timeout. Set that timeout when you create the Devbox, see Idle Timeout.

How idleness is detected

A Devbox is considered active (not idle) if any of the following are true:

There is an active SSH connection, whether through devbox ssh or a native SSH client. This includes SSH connections kept open by IDEs.
A session was created within the last 15 minutes.
Files exist under /.namespace/tasks, which indicate ongoing tasks and can be created by users.
See the long-running tasks guide to learn more.

The idle timeout countdown only applies once none of the conditions above are present.

Next Steps

Creating Devboxes

Machine sizes, images, repositories, and workspace defaults.

Remote Development

SSH access and SSH config for a Devbox.

Sessions

Persistent terminal sessions that survive disconnections.

Products

Platform

Administration

Listing Devboxes

Starting & Stopping

Deleting

Idleness & Auto-Stop

How idleness is detected

Next Steps

Creating Devboxes

Remote Development

Sessions

​Listing Devboxes

​Starting & Stopping

​Deleting

​Idleness & Auto-Stop

​How idleness is detected

​Next Steps

Creating Devboxes

Remote Development

Sessions

Listing Devboxes

Starting & Stopping

Deleting

Idleness & Auto-Stop

How idleness is detected

Next Steps