Skip to main content
Create a Devbox interactively, from command-line options, from a Blueprint, or from a JSON, YAML, or TOML specification.

Usage

To load a specification from a file or standard input, use --from:

Examples

Create a Devbox interactively

Create a named Devbox for a repository

Create a Windows Devbox

Run devbox image list --platform windows to see the available images. Windows Devboxes are in early access and support ephemeral Devboxes only.

Check out multiple repositories

Repeat --checkout for each repository:

Create a Devbox from a YAML specification

The file extension selects the parser. Supported extensions are .json, .yaml, .yml, and .toml.

Read a specification from standard input

Standard input defaults to YAML. Use --from_format to select another format.

Options

string
Set the Devbox access mode to private or workspace. When omitted, the workspace default applies.
boolean
default:"true"
Activate the Devbox immediately after creating it.
boolean
default:"false"
Include all image versions when choosing an image.
duration
Stop the Devbox after it remains idle for this duration, such as 30m or 1h.
string
Create the Devbox from the latest version of the named Blueprint. This option cannot be combined with --from or --platform.
stringArray
Check out this repository. Repeat the option to check out multiple repositories. When omitted, the workspace default repository applies. This option cannot be combined with --no_checkout.
boolean
default:"true"
Select the closest site when a site is not specified.
string
Use the specified dotfiles repository.
boolean
default:"false"
Create an ephemeral Devbox whose instance and storage are discarded when it stops. Always enabled for Windows Devboxes in early access.
string
Load a Devbox specification from a JSON, YAML, or TOML file. Pass - to read from standard input.
string
Force the --from input format to json, yaml, or toml instead of inferring it from the filename. Standard input defaults to YAML.
string
Use a Linux image name or reference, or a managed macOS or Windows image name. When omitted, the CLI prompts for an image. This option cannot be combined with --image_ref.
string
Use an exact Linux image reference. This option cannot be combined with --image.
string
Set the Devbox name and skip the name prompt.
boolean
default:"false"
Skip repository checkout, including the workspace default. This option cannot be combined with --checkout.
boolean
default:"true"
Enable persistent storage. Not supported for Windows Devboxes in early access.
string
Select linux, linux/amd64, macos, macos/arm64, windows, or windows/amd64. --machine_type is an alias. This option cannot be combined with --from or --blueprint.
strings
Enable one or more private feature IDs for the Devbox.
string
Attach a free-form description of the Devbox’s purpose.
boolean
default:"false"
Configure gh and Git authentication in the Devbox from the local GitHub token. Requires activation.
string
Create the Devbox at the specified site.
string
Select s, m, l, or xl for Linux and Windows, or m or l for macOS. When omitted, the CLI prompts for a size.
int
Set the persistent volume size in GiB. When omitted, the workspace default applies.

Devbox Lifecycle

Create, list, stop, and delete Devboxes.

Spec file

Every field accepted by --from.

Blueprints

Define reusable Devbox configurations.

Custom images

Build images for use with --image.
Last modified on November 10, 2026