sbx env create
| Description | Create a sandbox environment from sbxenv.yaml |
|---|---|
| Usage | sbx env create [PATH...] [flags] |
Experimental
This command is experimental.
Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.
Description
Read the environment file from PATH (default: current directory), provision its declared secrets at the sandbox scope, merge its credential bindings, and create the sandbox. Use "sbx env run" to attach.
Each PATH may be a directory (the file is -f semantics): later files override earlier ones.
Values may reference the arguments the file declares with ${{ env.args.NAME }},
supplied by --env-arg, plus ${{ env.projectDir }} and ${{ env.fileDir }}.
Nothing else is expanded, so a "$" is literal text.
A directory resolves to the sbxenv.yaml in it and to no other name; any other file is read only when a PATH names it. The hidden .sbxenv.yaml was once read as a directory's own environment too, so a project still holding one now reads as having none.
With no PATH, an existing .sbxenv.yaml in your home directory is merged
underneath as a base layer for defaults shared across projects; naming any
PATH skips the layer. It may not set "name:", which identifies a single
project, and its "workspace:" must be rooted at ${{ env.projectDir }} — for
the base that is always the directory the invocation runs from, since naming
any PATH skips it — so the base mounts each project's own directory rather
than one directory under all of them. Changing its "agent:"
changes the derived
A list such as "ports" or "mcp.servers" concatenates across layers rather than overriding, so an entry declared in both appears twice.
Options
| Option | Default | Description |
|---|---|---|
--clone | Override workspace.clone in sbxenv.yaml (see 'sbx create --clone') | |
--env-arg | experimental Value for an argument the environment file declares, as name=value (can be repeated) | |
--env-args-file | experimental File of name=value environment arguments, one per line (can be repeated); --env-arg overrides | |
-f, --force | Apply the environment plan without asking | |
--kit-arg | experimental Value for an argument a kit declares, as name=value for every kit or kit.name=value for one (can be repeated); overrides the args a kits: entry pins in sbxenv.yaml | |
--kit-args-file | experimental File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides | |
--name | Name for the sandbox, overriding 'name:' in sbxenv.yaml and the derived <agent>-<directory> (every 'sbx env' command addressing this environment needs the same value) | |
--on-timeout | What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only). Only applies when the sandbox is created; 'sbx --cloud env run' refuses it when attaching to an existing one. | |
--skip-host-commands | Skip the host lifecycle commands the environment declares | |
--ttl | Cloud sandbox time-to-live before it times out (e.g. 30m, 2h, 1h30m; units are case-insensitive; cloud only; default: server-side). Only applies when the sandbox is created; 'sbx --cloud env run' refuses it when attaching to an existing one |
Global options
| Option | Default | Description |
|---|---|---|
--cloud | Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list) | |
-D, --debug | Enable debug logging |
Examples
# Create the environment described in the current directory
sbx env create
# Approve the plan without asking
sbx env create --force ./project