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:

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:

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

Spec file reference

auto_stop_idle_timeout

env

ephemeral

image

integrations

name

name_prefix

network_policy

privileged

repository

sessions

site

size

volume_size_gb

Sessions

Each entry in sessions has:

name

command

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:

name

value

from_secret_id

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

Repository

The repository block supports:

disabled

url

ref

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:

egress_domains

network_policy:
  egress_domains:
    - "*.github.com"
    - api.openai.com

Integrations

The integrations object supports:

tailscale.spec

Example

name: my-devbox
image: default
size: M
repository: github.com/my-org/my-repo
volume_size_gb: 100
sessions:
  - name: server
    command: npm run dev
  - name: tests
    command: npm test -- --watch
integrations:
  tailscale:
    spec: corp
env:
  - name: APP_ENV
    value: production
  - name: GITHUB_TOKEN
    from_secret_id: sec_8fumgjd5jk

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 and configures gh auth and gh auth setup-git on the Devbox, enabling gh commands and HTTPS git authentication.

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.

Custom Images → Build custom base images with your tools and runtimes pre-installed.