Creating Devboxes

Everything you choose when a Devbox is created: how big it is, what image it runs, which repository it checks out, and how long it lives. For the full flag set, see devbox create.

Creating a Devbox

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

CLI
TS SDK
Dashboard

Run devbox create with no arguments to be prompted for each value:

devbox create

Or pass them inline to skip the prompts:

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

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

const devbox = await client.devboxes.create({
  name: "my-devbox",
  imageName: "builtin:agents",
  size: "m",
  repository: "github.com/your-org/your-repo",
});

See Create and manage Devboxes for every input field.

Create a macOS Devbox

Ask for macOS instead of the default Linux.

CLI
TS SDK
Dashboard

devbox create --platform macos

--platform also accepts macos/arm64, linux, and linux/amd64.

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

macOS creation cannot set image or imageName.

macOS Devboxes run on Apple Silicon from a Namespace-managed base image, so you choose a macOS and Xcode version rather than supplying your own. They support the M and L sizes only, and cannot use custom images or nested virtualization.

Create from a blueprint

Create a Devbox from a saved Blueprint definition.

CLI
TS SDK
Dashboard

devbox create --blueprint my-blueprint

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

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

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

A Blueprint captures the operating system, base image, machine size, access mode, and optional settings such as repositories, environment variables, and network policy. See Devbox Blueprints to create and configure one.

Create from a spec file

Declare the configuration in a file, then create from it non-interactively:

devbox.yaml

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

devbox create --from devbox.yaml

See the spec file reference for every field, the supported formats, and how to read a spec from stdin.

Configuration Options

Set these when you create a Devbox, in any of the forms above.

Image

Choose the image the Devbox starts from.

CLI
TS SDK
Dashboard

devbox create --image builtin:agents

List the images your workspace can use. Both Linux and macOS images are shown:

devbox image list

Filter with --platform linux or --platform macos. To create from a macOS image, pass the platform and the image name together:

devbox create --platform macos --image tahoe

--image follows the latest build of a named image. To pin one exact build, see Pin an exact image.

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

imageName selects a built-in or registered image by name. Use image for a full image reference. Call client.images.list() to see what is available.

macOS images are Namespace-managed and named after their release, such as tahoe or sequoia, and each bundles a macOS and Xcode version. Only Linux Devboxes can use images you build yourself. To bake your own tools and runtimes into an image, see Custom Images.

Machine Size

Choose how much CPU and memory the Devbox gets.

CLI
TS SDK
Dashboard

devbox create --size m

const devbox = await client.devboxes.create({
  name: "my-devbox",
  imageName: "builtin:agents",
  size: "m",
});

The available sizes differ between Linux and macOS.

Linux
macOS

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

Linux vCPU counts represent burstable capacity.

Size	CPU	Memory
M	6 vCPU	14 GB
L	12 vCPU	28 GB

Your workspace policy may restrict which sizes are available.

Repository

Clone a repository into the Devbox when it is created. This requires a connected GitHub organization.

CLI
TS SDK
Dashboard

devbox create --checkout github.com/your-org/your-repo

Omitting --checkout applies the workspace default repository. Pass --no_checkout to skip the checkout entirely.

const devbox = await client.devboxes.create({
  name: "my-devbox",
  imageName: "builtin:agents",
  repository: "github.com/your-org/your-repo",
});

To pin a branch, tag, or commit, use the repository block in a spec file.

Access Mode

Choose whether the Devbox is private to you or shared with the workspace. When omitted, the workspace default applies.

CLI
TS SDK
Dashboard

devbox create --access_mode shared

--access_mode accepts private or shared.

const devbox = await client.devboxes.create({
  name: "my-devbox",
  imageName: "builtin:agents",
  access: "workspace",
});

access accepts private or workspace.

Idle Timeout

Control how long a Devbox stays running after it goes idle. The dashboard offers presets of 15 minutes, 30 minutes, 1 hour, 4 hours, and 8 hours, plus a custom value. The CLI accepts any duration.

CLI
Dashboard

devbox create --auto_stop_idle_timeout=1h

See Idleness and auto-stop for how idleness is detected, and Running long tasks to learn how to keep a Devbox alive for long-running tasks.

Volume Size

Persistent storage defaults to the workspace setting. Override it when a repository or build cache needs more room:

CLI
TS SDK
Dashboard

devbox create --volume_size_gb=300

const devbox = await client.devboxes.create({
  name: "my-devbox",
  imageName: "builtin:agents",
  volumeSizeGB: 300,
});

Ephemeral

Create a Devbox whose instance and storage are deleted when it stops.

CLI
TS SDK

devbox create --ephemeral

const devbox = await client.devboxes.create({
  name: "throwaway",
  imageName: "builtin:agents",
  ephemeral: true,
});

Pass an object instead of true to control how long the stopped Devbox is retained.

Ephemeral Devboxes start fresh every time. They suit short-lived tasks or experimentation where you don’t need to keep data across restarts.

Site

Pin the Devbox to a specific site. By default it is created in the site closest to you.

CLI
TS SDK

devbox create --site iad

To list the available sites with their measured latencies, run devbox site-latency:

devbox site-latency

It reports p50 and p90 for each site and highlights the closest one.

const devbox = await client.devboxes.create({
  name: "my-devbox",
  imageName: "builtin:agents",
  site: "iad",
});

Workspace Defaults

Workspace admins can set default values applied to all newly created Devboxes. Navigate to the Defaults page in the dashboard to configure:

Image: default base image, which also determines the operating system (Linux or macOS)
Instance size: default CPU and memory allocation
Volume size: default persistent volume size for new Devboxes
Git repository: default repository to clone
Access mode: private (just you) or workspace-wide (shared with all members)
Auto-stop timeout on idle: how long Devboxes stay running when idle

Network

Egress policy: default outbound network access restrictions

Integrations

Bazel: enable Bazel integration to share Bazel cache across Devboxes
Tailscale: default Tailscale integration spec to connect Devboxes to your tailnet

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

Pin an exact image

--image follows the latest build of a named image, so a Devbox created today and one created next month can differ. To pin a single build that never changes, pass a full registry reference to --image_ref instead. List the images with their references:

devbox beta image list --output json

Output

{
  "name": "builtin:base",
  "os": "linux",
  "description": "Default image",
  "linux": {
    "image_ref": "public.registry.namespace.systems/namespacelabs.dev/internal/devbox/userimages/base@sha256:8df5e479...",
    "repository": "public.registry.namespace.systems/namespacelabs.dev/internal/devbox/userimages/base",
    "digest": "sha256:8df5e479..."
  }
}

Pass the image_ref value to devbox create:

devbox create --image_ref <repository>@sha256:<digest>

--image and --image_ref are mutually exclusive. --image_ref applies to Linux images only: macOS Devboxes must use --image with a macOS image name.

GitHub CLI Authentication

Forward your local gh CLI authentication to a Devbox so gh commands and HTTPS git operations are authenticated. Do it at creation time, or against a Devbox that already exists:

At creation
Existing Devbox
Spec file

devbox create --setup_github

devbox setup-github my-devbox

See devbox setup-github for what the command does on the Devbox.

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. When both are given, the --setup_github flag overrides the spec value.

Next Steps

Devbox Lifecycle

Listing, starting, stopping, idleness, and deleting.

Sessions

Persistent terminal sessions that survive disconnections.

Blueprints

Reusable Devbox configurations to create from.

Products

Platform

Administration

Creating a Devbox

Create a macOS Devbox

Create from a blueprint

Create from a spec file

Configuration Options

Image

Machine Size

Repository

Access Mode

Idle Timeout

Volume Size

Ephemeral

Site

Workspace Defaults

Pin an exact image

GitHub CLI Authentication

Next Steps

Devbox Lifecycle

Sessions

Blueprints

​Creating a Devbox

​Create a macOS Devbox

​Create from a blueprint

​Create from a spec file

​Configuration Options

​Image

​Machine Size

​Repository

​Access Mode

​Idle Timeout

​Volume Size

​Ephemeral

​Site

​Workspace Defaults

​Pin an exact image

​GitHub CLI Authentication

​Next Steps

Devbox Lifecycle

Sessions

Blueprints

Creating a Devbox

Create a macOS Devbox

Create from a blueprint

Create from a spec file

Configuration Options

Image

Machine Size

Repository

Access Mode

Idle Timeout

Volume Size

Ephemeral

Site

Workspace Defaults

Pin an exact image

GitHub CLI Authentication

Next Steps