> ## Documentation Index
> Fetch the complete documentation index at: https://namespace.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing Devboxes

Listing, stopping, deleting, configuring defaults, and monitoring resource usage.

## Machine Sizes

Both the CLI (`--size`) and the dashboard provide the same size options:

| Size   | CPU              | Memory |
| ------ | ---------------- | ------ |
| **S**  | Burst to 4 vCPU  | 8 GB   |
| **M**  | Burst to 8 vCPU  | 16 GB  |
| **L**  | Burst to 16 vCPU | 32 GB  |
| **XL** | Burst to 32 vCPU | 64 GB  |

vCPU counts represent burstable capacity. Your workspace policy may restrict which sizes are available.

## Create Devbox

Create a new Devbox with interactive prompts:

```bash theme={null}
devbox create
```

### In-line params

Pass parameters inline to skip specific prompts:

```bash theme={null}
devbox create --name my-devbox --size M --image builtin:agents
```

<h3 id="creating-from-a-spec-file">
  From a Spec File
</h3>

Define your Devbox configuration in a spec file:

```yaml devbox.yaml theme={null}
name: my-devbox
image: builtin:agents
size: m
repository: github.com/your-org/your-repo
```

and create it non-interactively with `--from`:

```bash theme={null}
devbox create --from devbox.yaml
```

* See [Spec file reference](#spec-file-reference) below for all available configuration options.
* Spec files can be JSON (`.json`), YAML (`.yaml` / `.yml`), or TOML (`.toml`).
* The `--from` flag works with `devbox acquire`.

#### Reading from stdin

Pass `-` as the path to read the spec from stdin. Stdin is parsed as YAML by
default; use `--from_format` to override (`json`, `yaml`, or `toml`):

```bash theme={null}
cat devbox.yaml | devbox create --from -
```

### Ephemeral Devboxes

Devboxes can be created as ephemeral, tying their instance and storage to a single run.
When an ephemeral Devbox stops, both its instance and storage are automatically deleted. On restart, it starts fresh.

Ephemeral Devboxes suit short-lived tasks or experimentation where you don't need to retain data across restarts.

Create an ephemeral Devbox with the `--ephemeral` flag:

```bash theme={null}
devbox create --ephemeral
```

## Listing Devboxes

**Via the CLI:**

```bash theme={null}
devbox list
```

By default this shows only your Devboxes. Use `--show-all` to see all Devboxes in the workspace.

Output as JSON for scripting:

```bash theme={null}
devbox list -o json
```

**Via the Dashboard:**

The [Devboxes dashboard](https://cloud.namespace.so/workspace/devboxes) shows all your Devboxes grouped by repository. Toggle between viewing your own Devboxes or all workspace Devboxes.

<h2 id="starting--stopping">
  Starting & Stopping
</h2>

Devboxes start automatically when you connect via `devbox ssh`, `devbox open-ide`, or from the dashboard.

To stop a running Devbox:

**Via the CLI:**

```bash theme={null}
devbox shutdown
```

This presents an interactive picker. You can also use the alias `devbox stop`.

**Via the Dashboard:**

Click the stop button on any running Devbox in the dashboard or from the Devbox detail page.

Stopped Devboxes retain all persistent storage. They resume in seconds on the next connection.

<h2 id="idleness--auto-stop">
  Idleness & Auto-Stop
</h2>

Control how long a Devbox stays running after becoming idle. Available timeouts: 15 min, 30 min, 1 hour, 4 hours, or 8 hours.

**CLI:**

```bash theme={null}
devbox create --auto_stop_idle_timeout=1h
```

**Dashboard:** Expand the **Advanced** section in the create dialog to configure the 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.

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

## Deleting

Deleting a Devbox permanently removes it and its associated persistent volume.

**Via the CLI:**

```bash theme={null}
devbox delete my-devbox
```

You'll be prompted to confirm by typing the Devbox name. Skip the confirmation with `--force`:

```bash theme={null}
devbox delete my-devbox --force
```

Without a name argument, an interactive picker is shown.

**Via the Dashboard:**

Delete a Devbox from its context menu in the dashboard.

## Volume Size

Override the default persistent volume size:

```bash theme={null}
devbox create --volume_size_gb=300
```

## Nested Virtualization

Linux Devboxes support nested virtualization: `/dev/kvm` is available inside the Devbox, so processes can use hardware-assisted virtualization. No flag or spec file option is needed: the device is mounted automatically, and its permissions are set so non-root users can use it without additional setup.

This works the same way with [custom images](/docs/devbox/images); you don't need to do anything in your Dockerfile to make `/dev/kvm` available.

To verify it's present, run:

```bash theme={null}
ls -l /dev/kvm
```

The most common use is Android emulators: hardware acceleration cuts emulator startup from minutes to seconds and avoids flaky tests caused by CPU-only emulation timeouts. Emulator acceleration requires `linux/amd64`. See [Android Emulators](/docs/integrations/android-emulators) for more information.

Nested virtualization is not available on macOS Devboxes. See [Nested Virtualization](/docs/architecture/compute/nestedvirt) for full platform support details.

## Spec file reference

| Field                    | Description                                                                                                     |
| ------------------------ | --------------------------------------------------------------------------------------------------------------- |
| `access_mode`            | Access mode: `private` (just you) or `shared` (workspace-wide).                                                 |
| `auto_stop_idle_timeout` | Idle timeout duration (e.g. `30m`, `1h`).                                                                       |
| `env`                    | Environment variables to set on the Devbox container ([see below](#environment-variables)).                     |
| `ephemeral`              | When `true`, the Devbox is ephemeral — no data is persisted across its lifecycle.                               |
| `image`                  | Image name or reference to use as the base environment (required).                                              |
| `integrations`           | Integration configuration ([see below](#integrations)).                                                         |
| `name`                   | Exact Devbox name (required, mutually exclusive with `name_prefix`).                                            |
| `name_prefix`            | Prefix for an auto-generated name — a random suffix is appended (required, mutually exclusive with `name`).     |
| `network_policy`         | Outbound network policy ([see below](#network-policy)).                                                         |
| `privileged`             | Run in privileged mode. Omit to use the image default.                                                          |
| `repository`             | Git repository to clone into the Devbox. Either a URL string, or a block of options ([see below](#repository)). |
| `sessions`               | List of sessions to create automatically ([see below](#sessions)).                                              |
| `site`                   | Target site. If omitted, the closest site is selected automatically.                                            |
| `size`                   | Machine size: `S`, `M`, `L`, or `XL` (required, case-insensitive).                                              |
| `volume_size_gb`         | Persistent volume size in GiB.                                                                                  |

### Sessions

Each entry in `sessions` has:

| Field     | Description                               |
| --------- | ----------------------------------------- |
| `name`    | Session name (required).                  |
| `command` | Command to run in the session (required). |

Configure one or more `session-command` pairs to have the Devbox automatically create sessions and run the specified commands on startup.

```yaml theme={null}
sessions:
  - name: server
    command: npm run dev
  - name: tests
    command: npm test -- --watch
```

### Environment Variables

Each entry in `env` has a `name` and exactly one of `value` or `from_secret_id`:

| Field            | Description                                                                        |
| ---------------- | ---------------------------------------------------------------------------------- |
| `name`           | Variable name (required).                                                          |
| `value`          | Literal value. Supports `$NAME` / `${NAME}` expansion from your local environment. |
| `from_secret_id` | Workspace vault secret ID (see [nsc vault list](/docs/reference/cli/vault-list)).       |

```yaml theme={null}
env:
  - name: APP_ENV
    value: production
  - name: GITHUB_TOKEN
    from_secret_id: sec_8fumgjd5jk
```

See [Managing Secrets](/docs/architecture/storage/secrets#managing-secrets) to learn how to create and manage vault secrets.

#### Repository

The `repository` block supports:

| Field      | Description                                                                           |
| ---------- | ------------------------------------------------------------------------------------- |
| `disabled` | When `true`, skips the checkout entirely, including any workspace default repository. |
| `url`      | Git repository URL to clone. Equivalent to using the string shorthand.                |
| `ref`      | Branch, tag, or commit SHA to check out. Defaults to the repository's default branch. |

Omit `repository` to fall back to the workspace default. To explicitly create a Devbox with no repository checked out:

```yaml theme={null}
repository:
  disabled: true
```

### Network Policy

The `network_policy` block restricts outbound network access:

| Field            | Description                                                                                                                                                      |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `egress_domains` | List of domains the Devbox is allowed to reach. Prefix a domain with `*.` to include all of its subdomains. Namespace infrastructure domains are always allowed. |

```yaml theme={null}
network_policy:
  egress_domains:
    - "*.github.com"
    - api.openai.com
```

### Integrations

The `integrations` object supports:

| Field               | Description                                                                                                                                                               |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `github.share_auth` | When `true`, authenticates the `gh` CLI and git on the Devbox with your local GitHub token ([see below](#setting-up-github-cli)). Equivalent to passing `--setup_github`. |
| `tailscale.spec`    | Name of a workspace-level [Tailscale integration spec](/docs/integrations/tailscale). Use `nsc integrations tailscale list` to see available specs.                            |

### Example

```yaml devbox.yaml theme={null}
name: my-devbox
image: builtin:agents
size: M
access_mode: private
volume_size_gb: 100
auto_stop_idle_timeout: 30m
privileged: false
repository:
  url: github.com/my-org/my-repo
  ref: main
sessions:
  - name: server
    command: npm run dev
  - name: tests
    command: npm test -- --watch
integrations:
  github:
    share_auth: true
  tailscale:
    spec: corp
env:
  - name: APP_ENV
    value: production
  - name: GITHUB_TOKEN
    from_secret_id: my-github-token-id
network_policy:
  egress_domains:
    - "*.github.com"
    - api.openai.com
```

## Workspace Defaults

Workspace admins can set default values applied to all newly created Devboxes. Navigate to the [Defaults page](https://cloud.namespace.so/workspace/Devboxes/defaults) in the dashboard to configure:

* **Instance Size**: default CPU and memory allocation
* **Image**: default base image
* **Git Repository**: default repository to clone
* **Access Mode**: private (just you) or workspace-wide (shared with all members)
* **Idle Timeout**: how long Devboxes stay running when idle
* **Tailscale**: default [Tailscale integration spec](/docs/integrations/tailscale) to connect Devboxes to your tailnet
* **Network Policy**: default outbound network access restrictions

When a workspace policy is active, policy-enforced values take precedence and are shown as locked in the UI.

## Git Configuration

Configure the git author name and email used across your Devboxes from the dashboard. Click your name in the Devboxes header to open the git configuration dialog.

This sets `user.name` and `user.email` for git operations in all your Devboxes.

## Setting Up GitHub CLI

Forward your local `gh` CLI authentication to a Devbox:

```bash theme={null}
devbox setup-github my-devbox
```

This transfers your local GitHub token to the Devbox and configures both the `gh` CLI (via `gh auth login`) and git (via [`gh auth setup-git`](https://cli.github.com/manual/gh_auth_setup-git)) to use it, so `gh` commands and HTTPS git operations are authenticated. This requires `gh` to be on the Devbox's `PATH`.

You can also do this as part of creating or acquiring a Devbox, so you don't need a separate step. Pass `--setup_github`:

```bash theme={null}
devbox create --setup_github
```

Or enable it in a spec file with `integrations.github.share_auth`:

```yaml devbox.yaml theme={null}
name: my-devbox
image: builtin:agents
size: m
integrations:
  github:
    share_auth: true
```

The local `gh` token is read before the Devbox is created, so a missing or expired login fails fast. Because it forwards your local authentication, this step requires the Devbox to be activated. When both are given, the `--setup_github` flag overrides the spec value.

## Resource Monitoring

The dashboard shows live resource metrics for running Devboxes:

* **CPU utilization**: overall and per-core usage with historical graphs
* **Memory utilization**: current usage percentage with history
* **Network latency**: ping indicator showing connection quality to your Devbox's site

These metrics are streamed in real time from the Devbox detail page.

## Site Latency

Devboxes are automatically created in the site closest to you. To manually check latency to available sites:

```bash theme={null}
devbox site-latency
```

The dashboard measures site latency automatically and selects the best site when creating a Devbox.

## Self-Update

Keep the Devbox CLI up to date:

```bash theme={null}
devbox update
```

## Next Steps

**[Remote Development →](/docs/devbox/remote-development)**
Connect to your Devbox via SSH, VS Code, Cursor, Zed, or JetBrains.

**[Sessions →](/docs/devbox/sessions)**
Persistent terminal sessions that survive disconnections and Devbox restarts.

**[Executing Commands →](/docs/devbox/exec)**
Run commands in a Devbox with `devbox exec` and read their output with `devbox logs`.

**[Custom Images →](/docs/devbox/images)**
Build custom base images with your tools and runtimes pre-installed.