Skip to main content
Acquire a lease on a Devbox associated with a tag. The command reuses an unleased Devbox with the same tag, or creates and tags a new Devbox when none is available. The CLI prompts for a tag in an interactive session when you omit it. Tags are limited to 50 characters. Creation options apply only when the command has to create a Devbox. The result identifies whether the Devbox was created or reused and prints its name and lease ID. Release the lease when the work is complete. A later devbox acquire with the same tag can then reuse the Devbox.

Usage

Examples

Acquire a Devbox for a task

Release the resulting lease

Options

string
Set the access mode to private or workspace. When omitted, workspace defaults apply.
boolean
default:"true"
Activate the Devbox immediately after creation.
boolean
default:"false"
Include all images when selecting an image.
duration
Stop the Devbox after it has been idle for this duration, such as 30m or 1h.
stringArray
Select a repository to check out. Repeat the option to check out multiple repositories. The workspace default is used when this option is omitted.
boolean
default:"true"
Use the closest site when selecting where to create the Devbox.
string
Specify a dotfiles repository to use.
boolean
default:"false"
Create an ephemeral Devbox.
string
Load the Devbox specification from a JSON, YAML, or TOML file. Use - for standard input, which defaults to YAML. A tag argument is required when reading the specification from standard input.
string
Force the input specification format to json, yaml, or toml.
string
Use the specified image name or reference. The CLI prompts for an image when one is not otherwise configured.
string
Use the specified image reference. This option is mutually exclusive with --image.
string
Set the Devbox name instead of generating one from the tag.
boolean
default:"false"
Skip repository checkout, including the workspace default. This option is mutually exclusive with --checkout.
boolean
default:"true"
Use persistent storage for a newly created Devbox.
string
Select linux[/amd64] or macos[/arm64]. --machine_type is an alias.
strings
Enable private features, such as EXP_PERSISTENT_VOLUME_IS_XFS.
string
Add a free-form description of what the Devbox is for.
boolean
default:"false"
Configure gh and Git authentication from the local GitHub token. Requires --activate.
string
Use the specified site.
string
Select s, m, l, or xl for Linux, or m or l for macOS. The CLI prompts when no size or tenant default is available.
int
Set the volume size in GiB. A platform default is used when omitted.

Release a Devbox lease

Return an acquired Devbox for later reuse.

Create a Devbox

Create a Devbox without acquiring it by tag.
Last modified on October 26, 2026