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:

devbox create

In-line params

Pass parameters inline to skip specific prompts:

devbox create --name my-devbox --size M --image builtin:agents

From a Spec File

Define your Devbox configuration in a spec file:

devbox.yaml

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

and create it non-interactively with --from:

devbox create --from devbox.yaml

See 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):

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:

devbox create --ephemeral

Listing Devboxes

Via the CLI:

devbox list

By default this shows only your Devboxes. Use --show-all to see all Devboxes in the workspace. Output as JSON for scripting:

devbox list -o json

Via the Dashboard: The Devboxes dashboard shows all your Devboxes grouped by repository. Toggle between viewing your own Devboxes or all workspace Devboxes.

Starting & Stopping

Devboxes start automatically when you connect via devbox ssh, devbox open-ide, or from the dashboard. To stop a running Devbox: Via the CLI:

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.

Idleness & Auto-Stop

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

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:

devbox delete my-devbox

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

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:

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; you don’t need to do anything in your Dockerfile to make /dev/kvm available. To verify it’s present, run:

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 for more information. Nested virtualization is not available on macOS Devboxes. See Nested Virtualization 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).
`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).
`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).
`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).
`sessions`	List of sessions to create automatically (see below).
`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.

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

env:
  - name: APP_ENV
    value: production
  - name: GITHUB_TOKEN
    from_secret_id: sec_8fumgjd5jk

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

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.

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). Equivalent to passing `--setup_github`.
`tailscale.spec`	Name of a workspace-level Tailscale integration spec. Use `nsc integrations tailscale list` to see available specs.

Example

devbox.yaml

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

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

devbox create --setup_github

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

devbox.yaml

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:

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:

devbox update

Next Steps

Remote Development → Connect to your Devbox via SSH, VS Code, Cursor, Zed, or JetBrains. Sessions → Persistent terminal sessions that survive disconnections and Devbox restarts. Executing Commands → Run commands in a Devbox with devbox exec and read their output with devbox logs. Custom Images → Build custom base images with your tools and runtimes pre-installed.

Products

Platform

Administration

Machine Sizes

Create Devbox

In-line params

From a Spec File

Reading from stdin

Ephemeral Devboxes

Listing Devboxes

Starting & Stopping

Idleness & Auto-Stop

How idleness is detected

Deleting

Volume Size

Nested Virtualization

Spec file reference

Sessions

Environment Variables

Repository

Network Policy

Integrations

Example

Workspace Defaults

Git Configuration

Setting Up GitHub CLI

Resource Monitoring

Site Latency

Self-Update

Next Steps

​Machine Sizes

​Create Devbox

​In-line params

​From a Spec File

​Reading from stdin

​Ephemeral Devboxes

​Listing Devboxes

​Starting & Stopping

​Idleness & Auto-Stop

​How idleness is detected

​Deleting

​Volume Size

​Nested Virtualization

​Spec file reference

​Sessions

​Environment Variables

​Repository

​Network Policy

​Integrations

​Example

​Workspace Defaults

​Git Configuration

​Setting Up GitHub CLI

​Resource Monitoring

​Site Latency

​Self-Update

​Next Steps

Machine Sizes

Create Devbox

In-line params

From a Spec File

Reading from stdin

Ephemeral Devboxes

Listing Devboxes

Starting & Stopping

Idleness & Auto-Stop

How idleness is detected

Deleting

Volume Size

Nested Virtualization

Spec file reference

Sessions

Environment Variables

Repository

Network Policy

Integrations

Example

Workspace Defaults

Git Configuration

Setting Up GitHub CLI

Resource Monitoring

Site Latency

Self-Update

Next Steps