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 shared. 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.
​
string
Select the repository to check out. 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 August 28, 2026