create

`bonya create [name]`

Aliases: new, c

Starts a new sandbox from a template.

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:

$ 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):

$ 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

bonya create --template bonya-dev

bonya create web --template bonya-dev

bonya create --template bonya-dev --wait none

bonya create --template bonya-dev --version 2024.11

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

Overview

Getting started

Sandboxes

Inside a sandbox

Account

`bonya create [name]`

Flags

Positional name vs. `--name`

Post-create console offer

Examples

​bonya create [name]

​Flags

​Positional name vs. --name

​Post-create console offer

​Examples

`bonya create [name]`

Flags

Positional name vs. `--name`

Post-create console offer

Examples