> ## Documentation Index
> Fetch the complete documentation index at: https://docs.celesto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# celesto sandbox exec

> Use celesto sandbox exec to run a single command inside a running sandbox and stream its output, with exit-code passthrough and an optional JSON envelope.

`celesto sandbox exec` runs one command inside a running sandbox and streams its output back to your terminal. Use it in scripts and agent tooling when you want to invoke something in a sandbox without opening an interactive shell — the guest's exit code is returned as `celesto`'s exit code, so it fits directly into pipelines and CI steps.

By default the sandbox must already be running. Pass `--start` to have Celesto start or resume it first, like `sandbox shell` and `sandbox ssh` do.

## Synopsis

```bash theme={null}
celesto sandbox exec <sandbox> [OPTIONS] -- <command> [args...]
```

Everything after `--` is passed to the guest verbatim, including flags that would otherwise be interpreted by the CLI.

## Arguments

<ParamField path="sandbox" type="string" required>
  Name or ID of the sandbox to run the command in.
</ParamField>

<ParamField path="command" type="string" required>
  The command to run inside the sandbox. Put it after `--` so shell flags aren't consumed by `celesto`.
</ParamField>

## Options

<ParamField path="--start" type="flag">
  Start or resume the sandbox first if it is not already running. Without this flag, `exec` exits with an error when the sandbox is stopped or paused.
</ParamField>

<ParamField path="--timeout" type="number" default="30">
  Seconds to wait for the command to finish.
</ParamField>

<ParamField path="--boot-timeout" type="number" default="30">
  Seconds to wait for the sandbox to become ready when `--start` is used.
</ParamField>

<ParamField path="--json" type="flag">
  Emit a JSON envelope with `ok`, `data` (including `stdout`, `stderr`, and `exit_code`), and `error` instead of streaming raw output. On a non-zero guest exit, `error.code` is `command_failed`.
</ParamField>

## Examples

### Run a command in a running sandbox

```bash theme={null}
celesto sandbox exec my-sandbox -- python --version
```

### Start the sandbox first if it's stopped

```bash theme={null}
celesto sandbox exec my-sandbox --start -- ls -la /workspace
```

### Get structured output for a script

```bash theme={null}
celesto sandbox exec my-sandbox --json -- uname -a
```

### Use the exit code in a pipeline

```bash theme={null}
celesto sandbox exec my-sandbox -- pytest tests/ && echo "tests passed"
```

## How it behaves

`sandbox exec` streams the command's `stdout` and `stderr` back as they arrive and returns the guest's exit code as its own. Piping into a reader that closes early (for example `| head`) exits cleanly instead of raising.

If the sandbox is stopped or paused and `--start` is not set, `exec` exits with an actionable error that names both `celesto sandbox start` and the `--start` flag. In `--json` mode the same condition returns an envelope with `ok: false` and an `error` object.

## Related commands

* [`celesto sandbox shell`](/smolvm/cli/shell) - Open an interactive shell instead
* [`celesto sandbox logs`](/smolvm/cli/logs) - Read the sandbox's boot and console logs
* [`celesto sandbox start`](/smolvm/cli/stop) - Start a stopped sandbox manually


## Related topics

- [celesto sandbox logs](/smolvm/cli/logs.md)
- [CLI overview](/smolvm/cli/overview.md)
- [celesto sandbox create](/smolvm/cli/create.md)
- [celesto sandbox stop](/smolvm/cli/stop.md)
- [celesto sandbox list](/smolvm/cli/list.md)