sbx env run
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) and drop into the sandbox shell. If the sandbox already exists it is started and re-attached without re-provisioning; otherwise it is created first (provisioning secrets and bindings) and then attached.
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 PATH selects sbxenv.yaml; a file PATH selects that file. With no PATH, ~/.sbxenv.yaml supplies shared defaults when present. Explicit PATHs skip those defaults. Later files override earlier values; lists such as ports and mcp.servers are concatenated.
Options
| Option | Default | Description |
|---|---|---|
--clone | Override workspace.clone in sbxenv.yaml (see 'sbx create --clone') | |
-d, --detach | Create/start the sandbox without attaching | |
--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 host lifecycle commands and disable environment MCP commands until a later env run without this flag | |
--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
Examples
sbx env run
# Start without attaching
sbx env run --detach ./project