sbx env exec
| Description | Execute a command inside a sandbox environment |
|---|---|
| Usage | sbx env exec [flags] [PATH...] -- COMMAND [ARG...] |
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
Run COMMAND in the sandbox declared in sbxenv.yaml. The sandbox is started first if stopped. If it does not exist, an interactive terminal prompts to create it and approve the environment plan before running COMMAND. Without an interactive terminal, or with --no-input, create it first with "sbx env create".
Arguments before -- are environment-file paths, following the same rules as
the other "sbx env" subcommands: each PATH may be a directory (the file is
-- every positional
argument forms the command and the environment file is read from the current
directory.
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. Ports with the same sandbox port and effective protocol, MCP servers with the same name, and additional workspaces with the same container target use the later entry, including repeated entries in one file. Kit arguments merge by source. The entrypoint and cmd arrays replace earlier values; other lists concatenate.
Flags match the behavior of "sbx exec".
Exit status is that of the command. sbx exits 125 if it could not run the command, for example because the sandbox does not exist. A missing command exits 127, unless a cloud backend reports it as an error rather than a status, which exits 125.
Options
| Option | Default | Description |
|---|---|---|
--detach-keys | Override the key sequence for detaching an interactive cloud exec session (not supported for local exec) | |
-e, --env | Set environment variables | |
--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 | |
--env-file | Read in a file of environment variables | |
-i, --interactive | Keep STDIN open even if not attached | |
--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) | |
-t, --tty | Allocate a pseudo-TTY | |
-u, --user | Username or UID (format: <name|uid>[:<group|gid>]) | |
-w, --workdir | Working directory inside the container |
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 | |
--no-input | Never prompt; commands that need an answer fail with the command to run instead |
Examples
# Run a command in the environment declared in the current directory
sbx env exec go test ./...
# Open a shell
sbx env exec -it -- bash
# Run against explicitly merged environment files
sbx env exec sbxenv.yaml override.yaml -- npm test