> ## 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={null}
devbox create [flags]
```

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

```bash theme={null}
devbox create --from <path> [flags]
```

## Examples

### Create a Devbox interactively

```bash theme={null}
devbox create
```

### Create a named Devbox for a repository

```bash theme={null}
devbox create --name my-devbox --image builtin:agents --size m --checkout github.com/myorg/myrepo
```

### Create a Devbox from a YAML specification

```bash theme={null}
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={null}
cat devbox.yaml | devbox create --from -
```

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

## Options

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

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

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

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

<ResponseField name="--blueprint" type="string">
  Create the Devbox from the latest version of the named Blueprint. This option cannot be combined with `--from` or `--platform`.
</ResponseField>

<ResponseField name="--checkout" type="string">
  Check out this repository. When omitted, the workspace default repository applies. This option cannot be combined with `--no_checkout`.
</ResponseField>

<ResponseField name="--closest" type="boolean" default="true">
  Select the closest site when a site is not specified.
</ResponseField>

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

<ResponseField name="--ephemeral" type="boolean" default="false">
  Create an ephemeral Devbox whose instance and storage are discarded when it stops.
</ResponseField>

<ResponseField name="--from" type="string">
  Load a Devbox specification from a JSON, YAML, or TOML file. Pass `-` to read from standard input.
</ResponseField>

<ResponseField name="--from_format" type="string">
  Force the `--from` input format to `json`, `yaml`, or `toml` instead of inferring it from the filename. Standard input defaults to YAML.
</ResponseField>

<ResponseField name="--image" type="string">
  Use an image name or reference. When omitted, the CLI prompts for an image. This option cannot be combined with `--image_ref`.
</ResponseField>

<ResponseField name="--image_ref" type="string">
  Use an exact image reference. This option cannot be combined with `--image`.
</ResponseField>

<ResponseField name="--name" type="string">
  Set the Devbox name and skip the name prompt.
</ResponseField>

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

<ResponseField name="--persistent" type="boolean" default="true">
  Enable persistent storage.
</ResponseField>

<ResponseField name="--platform" type="string">
  Select `linux`, `linux/amd64`, `macos`, or `macos/arm64`. `--machine_type` is an alias. This option cannot be combined with `--from` or `--blueprint`.
</ResponseField>

<ResponseField name="--private_features" type="strings">
  Enable one or more private feature IDs for the Devbox.
</ResponseField>

<ResponseField name="--purpose" type="string">
  Attach a free-form description of the Devbox's purpose.
</ResponseField>

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

<ResponseField name="--site" type="string">
  Create the Devbox at the specified site.
</ResponseField>

<ResponseField name="--size" type="string">
  Select `s`, `m`, `l`, or `xl` for Linux, or `m` or `l` for macOS. When omitted, the CLI prompts for a size.
</ResponseField>

<ResponseField name="--volume_size_gb" type="int">
  Set the persistent volume size in GiB. When omitted, the workspace default applies.
</ResponseField>

## Related topics

<Columns cols={3}>
  <Card title="Managing Devboxes" icon="settings" href="/docs/devbox/managing">
    Configure Devboxes and see the specification file reference.
  </Card>

  <Card title="Blueprints" icon="layers" href="/docs/devbox/blueprint">
    Define reusable Devbox configurations.
  </Card>

  <Card title="Custom images" icon="hard-drive" href="/docs/devbox/images">
    Build images for use with `--image`.
  </Card>
</Columns>