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 must already exist (see "sbx env create" and "sbx env run"); a stopped sandbox is started first.
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 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:" or "workspace:", each of which
identifies a single project. 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.
Flags match the behavior of "sbx exec".
Options
| Option | Default | Description |
|---|---|---|
-d, --detach | Detached mode: run command in the background | |
--detach-keys | Override the key sequence for detaching a container | |
-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 | |
--privileged | Give extended privileges to the command | |
-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) | |
--cloud-api-url | https://api.sandboxes-cloud.docker.com | Cloud Sandboxes API base URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com). Set DOCKER_CLOUD_API_URL or pass this flag to override; a legacy value ending in /v1 is accepted. |
-D, --debug | Enable debug logging |
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