> ## 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:default --size m
```

### Release the resulting lease

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

## Options

**--access\_mode** `string`

Set the access mode to `private` or `workspace`. When omitted, workspace defaults apply.

**--activate** `boolean` (default: true)

Activate the Devbox immediately after creation.

**--all\_images** `boolean` (default: false)

Include all images when selecting an image.

**--auto\_stop\_idle\_timeout** `duration`

Stop the Devbox after it has been idle for this duration, such as `30m` or `1h`.

**--checkout** `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.

**--closest** `boolean` (default: true)

Use the closest site when selecting where to create the Devbox.

**--dotfiles** `string`

Specify a dotfiles repository to use.

**--ephemeral** `boolean` (default: false)

Create an ephemeral Devbox.

**--from** `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.

**--from\_format** `string`

Force the input specification format to `json`, `yaml`, or `toml`.

**--image** `string`

Use the specified image name or reference. The CLI prompts for an image when one is not otherwise configured.

**--image\_ref** `string`

Use the specified image reference. This option is mutually exclusive with `--image`.

**--name** `string`

Set the Devbox name instead of generating one from the tag.

**--no\_checkout** `boolean` (default: false)

Skip repository checkout, including the workspace default. This option is mutually exclusive with `--checkout`.

**--persistent** `boolean` (default: true)

Use persistent storage for a newly created Devbox.

**--platform** `string`

Select `linux[/amd64]` or `macos[/arm64]`. `--machine_type` is an alias.

**--private\_features** `strings`

Enable private features, such as `EXP_PERSISTENT_VOLUME_IS_XFS`.

**--purpose** `string`

Add a free-form description of what the Devbox is for.

**--setup\_github** `boolean` (default: false)

Configure `gh` and Git authentication from the local GitHub token. Requires `--activate`.

**--site** `string`

Use the specified site.

**--size** `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.

**--volume\_size\_gb** `int`

Set the volume size in GiB. A platform default is used when omitted.

## Related topics

> [card] [Release a Devbox lease](https://namespace.so/docs/reference/devbox-cli/release.md)
>
> Return an acquired Devbox for later reuse.

> [card] [Create a Devbox](https://namespace.so/docs/reference/devbox-cli/create.md)
>
> Create a Devbox without acquiring it by tag.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.