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

# create

> Create a new sandbox from a template

## `bonya create [name]`

> [!NOTE]
>
> Aliases: `new`, `c`

Starts a new sandbox from a template.

```shell theme={null}
bonya create --template bonya-dev        # generated name
bonya create web --template bonya-dev    # named "web"
bonya create                               # deployment default template
```

When `--template` is omitted, the CLI uses the deployment's configured default template. The name is optional and **positional** — leave it out and the service generates a friendly one (like `swift-otter-9c3f`), which is printed as part of the result. Names are not unique, so two sandboxes can share the same one.

## Flags

| Flag | Default | Description |
| - | - | - |
| `--template` | deployment default | Template to create the sandbox from. Interactive terminals offer the published catalog when omitted. |
| `--version` | server-selected version | Template version to use. Requires `--template`. |
| `--wait` | `ready` | Either `ready` (block until the sandbox is ready) or `none` (return immediately after the create call is accepted). |
| `--idempotency-key` | — | Idempotency key for the create request. |
| `--name` | — | Display name for the sandbox. Prefer the positional form; kept for scripts written against it before the positional form existed. |

### Positional name vs. `--name`

If you pass both a positional name and `--name` and they disagree, `create` fails:

```console theme={null}
$ bonya create web --name api --template bonya-dev
name given twice: "web" and --name "api"
```

Passing the same value both ways is harmless. In new scripts, prefer the positional form.

## Post-create console offer

On an interactive terminal, once the sandbox is ready `create` offers to open a console in it immediately — press Enter to accept (the prompt defaults to yes):

```console theme={null}
$ bonya create --template bonya-dev
id           sbx-4f1c9a2b3c4d5e6f7a8b9c0d1e2f3a4b
name         swift-otter-9c3f
status       running
template     bonya-dev
...

Open a console now? (Y/n)
```

This offer is skipped — and the "open a shell with" hint is printed instead — under any of:

* `--wait none` (the sandbox isn't up yet, so attaching would block on the boot you explicitly asked not to wait for)
* `--json`
* `--no-input`
* a non-interactive session (piped, CI, etc.)

## Examples

```shell Generated name theme={null}
bonya create --template bonya-dev
```

```shell Explicit name theme={null}
bonya create web --template bonya-dev
```

```shell Don't wait for the sandbox to be ready theme={null}
bonya create --template bonya-dev --wait none
```

```shell Pin a template version theme={null}
bonya create --template bonya-dev --version 2024.11
```

On a real terminal, a successful create looks like this:


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