lifecycle.md

Devbox Lifecycle

Follow a Devbox through its life: create it, find it again, stop and resume it, and delete it when you are done.

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.

1. Create a Devbox

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

CLI

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

TS SDK

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",
});

Dashboard

Press + Create on the Devboxes page. The dialog is pre-filled with a generated name, a default image, and a default size. Press Create Devbox right away, or pick a repository, size, and image first.

For a macOS Devbox, select macOS in the toggle at the top of the dialog, then choose the macOS version and size.

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.

2. Find it again

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

CLI

devbox list

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

TS SDK

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.

Dashboard

The Devboxes page groups Devboxes into My Devboxes, Shared Devboxes from your workspace, and Managed Agents created by integrations. Each row shows the operating system, machine size, and how long the Devbox has been idle. A green dot marks a running Devbox.

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

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.

TS SDK

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.

Dashboard

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

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.

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

devbox delete my-devbox

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

TS SDK

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.

Dashboard

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

Create from a Blueprint

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

CLI

devbox create --blueprint my-blueprint

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

TS SDK

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

Dashboard

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

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

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

Dashboard

Expand the Advanced section in the create dialog and pick a timeout. The presets are 15 minutes, 30 minutes, 1 hour, 4 hours, and 8 hours, plus a custom value.

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 service with idle shutdown prevention enabled is running.

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	3 hours
Devbox Plus	3 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.

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