# 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:

```bash
devbox create
```

Or pass the values as flags to skip the prompts:

```bash
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:

```bash
devbox create --platform macos --image tahoe
```

**TS SDK**

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

```typescript
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:

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

**Dashboard**

Press **+ Create** on the [Devboxes page](https://cloud.namespace.so/workspace/devboxes). 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`](/content/docs/reference/devbox-cli/create/index.html) 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**

```bash
devbox list
```

This shows only your Devboxes. See [`devbox list`](/content/docs/reference/devbox-cli/list/index.html) for JSON output and for including other members' Devboxes.

**TS SDK**

```typescript
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](https://cloud.namespace.so/workspace/devboxes) 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**

```bash
devbox stop my-devbox
```

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

```bash
devbox session connect my-devbox
```

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

**TS SDK**

```typescript
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](#idle-timeout).

### 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**

```bash
devbox delete my-devbox
```

The CLI asks you to confirm. See [`devbox delete`](/content/docs/reference/devbox-cli/delete/index.html) to skip the confirmation.

**TS SDK**

```typescript
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](/content/docs/devbox/blueprint.md) in your workspace, and create every new Devbox from it.

**CLI**

```bash
devbox create --blueprint my-blueprint
```

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

**TS SDK**

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

**Dashboard**

On the [Blueprints page](https://cloud.namespace.so/workspace/devboxes/blueprints), 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**

```bash
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](/content/docs/devbox/services.md#prevent-idle-shutdown/index.html) 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](/content/docs/guides/devbox/long-running-tasks.md).

## 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](mailto:support@namespace.so). The maximum duration can be raised up to 24 hours.

## Next Steps

**[SSH & Sessions](/content/docs/devbox/connecting.md)**  
Open a shell on a Devbox with SSH or a session.

**[Blueprints](/content/docs/devbox/blueprint.md)**  
Save a Devbox configuration for your team.

**[Running Long Tasks](/content/docs/guides/devbox/long-running-tasks.md)**  
Keep a Devbox running while a build or an agent works.