> ## 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 create

> Create and configure a Devbox.

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

## Usage

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
devbox create [flags]
```

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

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
devbox create --from <path> [flags]
```

## Examples

### Create a Devbox interactively

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
devbox create
```

### Create a named Devbox for a repository

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
devbox create --name my-devbox --image builtin:default --size m --checkout github.com/myorg/myrepo
```

### Create a Windows Devbox

```bash wrap theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
devbox create --image windows-2022 --size m --name my-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:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
devbox create --name my-devbox --image builtin:default --size m \
  --checkout github.com/myorg/frontend \
  --checkout github.com/myorg/backend
```

### Create a Devbox from a YAML specification

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
devbox create --from devbox.yaml
```

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

### Read a specification from standard input

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
cat devbox.yaml | devbox create --from -
```

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

## Options

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

Set the Devbox access mode to `private` or `workspace`. When omitted, the workspace default applies.

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

Activate the Devbox immediately after creating it.

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

Include all image versions when choosing an image.

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

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

**--blueprint** `string`

Create the Devbox from the latest version of the named Blueprint. This option cannot be combined with `--from` or `--platform`.

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

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

Select the closest site when a site is not specified.

**--dotfiles** `string`

Use the specified dotfiles repository.

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

Create an ephemeral Devbox whose instance and storage are discarded when it stops. Always enabled for Windows Devboxes in early access.

**--from** `string`

Load a Devbox [specification](https://namespace.so/docs/reference/devbox-cli/spec-file.md) from a JSON, YAML, or TOML file. Pass `-` to read from standard input.

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

Force the `--from` input format to `json`, `yaml`, or `toml` instead of inferring it from the filename. Standard input defaults to YAML.

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

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

Use an exact Linux image reference. This option cannot be combined with `--image`.

**--name** `string`

Set the Devbox name and skip the name prompt.

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

Skip repository checkout, including the workspace default. This option cannot be combined with `--checkout`.

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

Enable persistent storage. Not supported for Windows Devboxes in early access.

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

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

Enable one or more private feature IDs for the Devbox.

**--purpose** `string`

Attach a free-form description of the Devbox's purpose.

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

Configure `gh` and Git authentication in the Devbox from the local GitHub token. Requires activation.

**--site** `string`

Create the Devbox at the specified site.

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

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

Set the persistent volume size in GiB. When omitted, the workspace default applies.

## Related topics

> [card] [Devbox Lifecycle](https://namespace.so/docs/devbox/lifecycle.md)
>
> Create, list, stop, and delete Devboxes.

> [card] [Spec file](https://namespace.so/docs/reference/devbox-cli/spec-file.md)
>
> Every field accepted by `--from`.

> [card] [Blueprints](https://namespace.so/docs/devbox/blueprint.md)
>
> Define reusable Devbox configurations.

> [card] [Custom images](https://namespace.so/docs/devbox/images.md)
>
> Build images for use with `--image`.


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