> ## Documentation Index
> Fetch the complete documentation index at: https://namespace.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# devbox acquire

> Acquire a reusable Devbox by tag.

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

```bash theme={null}
devbox acquire [tag] [flags]
```

## Examples

### Acquire a Devbox for a task

```bash theme={null}
devbox acquire pull-request-123 --image builtin:agents --size m
```

### Release the resulting lease

```bash theme={null}
devbox release my-devbox --lease_id=LEASE_xyz
```

## Options

<ResponseField name="--access_mode" type="string">
  Set the access mode to `private` or `shared`. When omitted, workspace defaults apply.
</ResponseField>

<ResponseField name="--activate" type="boolean" default="true">
  Activate the Devbox immediately after creation.
</ResponseField>

<ResponseField name="--all_images" type="boolean" default="false">
  Include all images when selecting an image.
</ResponseField>

<ResponseField name="--auto_stop_idle_timeout" type="duration">
  Stop the Devbox after it has been idle for this duration, such as `30m` or `1h`.
</ResponseField>

<ResponseField name="--checkout" type="string">
  Select the repository to check out. The workspace default is used when this option is omitted.
</ResponseField>

<ResponseField name="--closest" type="boolean" default="true">
  Use the closest site when selecting where to create the Devbox.
</ResponseField>

<ResponseField name="--dotfiles" type="string">
  Specify a dotfiles repository to use.
</ResponseField>

<ResponseField name="--ephemeral" type="boolean" default="false">
  Create an ephemeral Devbox.
</ResponseField>

<ResponseField name="--from" type="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.
</ResponseField>

<ResponseField name="--from_format" type="string">
  Force the input specification format to `json`, `yaml`, or `toml`.
</ResponseField>

<ResponseField name="--image" type="string">
  Use the specified image name or reference. The CLI prompts for an image when one is not otherwise configured.
</ResponseField>

<ResponseField name="--image_ref" type="string">
  Use the specified image reference. This option is mutually exclusive with `--image`.
</ResponseField>

<ResponseField name="--name" type="string">
  Set the Devbox name instead of generating one from the tag.
</ResponseField>

<ResponseField name="--no_checkout" type="boolean" default="false">
  Skip repository checkout, including the workspace default. This option is mutually exclusive with `--checkout`.
</ResponseField>

<ResponseField name="--persistent" type="boolean" default="true">
  Use persistent storage for a newly created Devbox.
</ResponseField>

<ResponseField name="--platform" type="string">
  Select `linux[/amd64]` or `macos[/arm64]`. `--machine_type` is an alias.
</ResponseField>

<ResponseField name="--private_features" type="strings">
  Enable private features, such as `EXP_PERSISTENT_VOLUME_IS_XFS`.
</ResponseField>

<ResponseField name="--purpose" type="string">
  Add a free-form description of what the Devbox is for.
</ResponseField>

<ResponseField name="--setup_github" type="boolean" default="false">
  Configure `gh` and Git authentication from the local GitHub token. Requires `--activate`.
</ResponseField>

<ResponseField name="--site" type="string">
  Use the specified site.
</ResponseField>

<ResponseField name="--size" type="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.
</ResponseField>

<ResponseField name="--volume_size_gb" type="int">
  Set the volume size in GiB. A platform default is used when omitted.
</ResponseField>

## Related topics

<Columns cols={2}>
  <Card title="Release a Devbox lease" icon="rotate-ccw" href="/docs/reference/devbox-cli/release">
    Return an acquired Devbox for later reuse.
  </Card>

  <Card title="Create a Devbox" icon="plus" href="/docs/reference/devbox-cli/create">
    Create a Devbox without acquiring it by tag.
  </Card>
</Columns>