Devbox Lifecycle

Creating a Devbox takes one command, and most of its life takes care of itself: it starts when you connect, stops when it goes idle, and keeps your files in between. You still decide when to stop it early, which configuration to start it from, and when to delete it for good.

The Life of a Devbox

A Devbox is a machine you come back to. You create it once, work in it over days or weeks, and it stops when nobody is using it.

Create a Devbox

Give the Devbox a name, an image, and a size. Anything you leave out falls back to your workspace defaults.

CLI
TS SDK
Dashboard

Run devbox create to be prompted for each value:

devbox create

Or pass the values as flags to skip the prompts:

devbox create --name my-devbox --image builtin:default --size m --checkout github.com/your-org/your-repo

For a macOS Devbox, use --platform macos and pick a macOS image:

devbox create --platform macos --image tahoe

devboxes.create() provisions the Devbox and waits for it to become ready:

const devbox = await client.devboxes.create({
  name: "my-devbox",
  imageName: "builtin:default",
  size: "m",
  repository: "github.com/your-org/your-repo",
});

For a macOS Devbox, set os instead of an image:

const devbox = await client.devboxes.create({
  name: "my-mac-devbox",
  os: "macos",
  size: "m",
});

The Devbox is running and ready to connect to as soon as it is created.macOS Devboxes run on Apple Silicon from a Namespace-managed image, so you choose a macOS and Xcode version rather than supplying your own image. They support the M and L sizes only. See devbox create for every option.

Find it again

Come back later and list your Devboxes to see which ones exist and whether they are running:

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));

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

Stop it and pick up later

When you are done for the day, stop the Devbox. It keeps its persistent storage, and you usually do not need to start it by hand: connecting to a stopped Devbox starts it again.

CLI
TS SDK
Dashboard

devbox stop my-devbox

To pick up where you left off, connect to it. The CLI starts the Devbox first:

devbox session connect my-devbox

devbox ssh and devbox open-ide start a stopped Devbox in the same way.

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

start() waits for the Devbox to become ready. Commands, file access, and terminals also start a stopped Devbox on their own, so call start() only when you need to wait for readiness first.

A running Devbox can be stopped from its ... menu or from its detail page. A stopped Devbox shows a Start button.

The Devboxes page with the context menu open on a running Devbox, showing Stop and Delete

You do not have to remember to stop it. A Devbox also stops on its own after it has been idle for a while, see Let Idle Devboxes Stop on Their Own.

Delete it when you no longer need it

Deleting a Devbox removes it and its persistent storage. Copy out anything you want to keep first, because this cannot be undone.

CLI
TS SDK
Dashboard

devbox delete my-devbox

The CLI asks you to confirm. See devbox delete to skip the confirmation.

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 the Devbox and select Delete.

Create from a Saved Configuration

Once you create Devboxes regularly, you can stop repeating the same flags. Save the configuration as a Blueprint in your workspace, or as a spec file in your repository, and create every new Devbox from it.

From a Blueprint

A Blueprint saves a Devbox configuration for your workspace: the operating system, image, machine size, access mode, and optional settings such as repositories, environment variables, and network policy. Every Devbox created from it starts the same way.

CLI
TS SDK
Dashboard

devbox create --blueprint my-blueprint

--blueprint uses the latest version of the named Blueprint, and cannot be combined with --from or --platform.

const devbox = await client.devboxes.create({
  name: "my-devbox",
  blueprint: "my-blueprint",
});

On the Blueprints page, open the ... menu next to a Blueprint, select Create Devbox, give it a name, and press Create Devbox.

The Blueprints page with the Create Devbox action open on a Blueprint

From a Spec File

A spec file keeps the configuration next to your code, so you can review it and reuse it from scripts:

devbox.yaml

name: my-devbox
image: builtin:default
size: m
repository: github.com/your-org/your-repo

devbox create --from devbox.yaml

See the spec file reference for every field, the supported formats, and how to read a spec from stdin.

Idle Timeout

A Devbox stops once it has been idle for the length of its idle timeout, so one you forget about does not keep running. Set the timeout when you create the Devbox:

CLI
Dashboard

devbox create --name my-devbox --auto_stop_idle_timeout 1h

In a spec file, set auto_stop_idle_timeout: 1h.

A Devbox counts as active, and the countdown does not start, while any of these is true:

An SSH connection is open, through devbox ssh, a native SSH client, or an IDE.
A session was created within the last 15 minutes.
A task marker exists under $NAMESPACE_DEVBOX_TASKS_DIR.

A long build or an agent working in a session can outlast those signals, and the Devbox then stops in the middle of the work. Create a task marker for work like that, see Running long tasks.

Maximum Duration

Each Devbox has a maximum duration. When it is reached, Namespace shuts down the Devbox’s instance. The maximum duration depends on your plan:

Plan	Maximum duration
Developer	4 hours
Team	5 hours
Business	24 hours

The limit applies even while you are working in the Devbox. An open connection or a task marker does not keep it running past its maximum duration.

To raise your limit, contact support. The maximum duration can be raised up to 24 hours.

Next Steps

SSH & Sessions

Open a shell on a Devbox with SSH or a session.

Blueprints

Save a Devbox configuration for your team.

Running Long Tasks

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

Products

Platform

Administration

The Life of a Devbox

Create a Devbox

Find it again

Stop it and pick up later

Delete it when you no longer need it

Create from a Saved Configuration

From a Blueprint

From a Spec File

Idle Timeout

Maximum Duration

Next Steps

SSH & Sessions

Blueprints

Running Long Tasks

​The Life of a Devbox

Create a Devbox

Find it again

Stop it and pick up later

Delete it when you no longer need it

​Create from a Saved Configuration

​From a Blueprint

​From a Spec File

​Idle Timeout

​Maximum Duration

​Next Steps

SSH & Sessions

Blueprints

Running Long Tasks

The Life of a Devbox

Create from a Saved Configuration

From a Blueprint

From a Spec File

Idle Timeout

Maximum Duration

Next Steps