> ## Documentation Index
> Fetch the complete documentation index at: https://celesto.ai/docs/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

**sandbox** `string` *required*

Name or ID of the sandbox to run the command in.

**command** `string` *required*

The command to run inside the sandbox. Put it after `--` so shell flags aren't consumed by `celesto`.

## Options

**--start** `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.

**--timeout** `number` (default: 30)

Seconds to wait for the command to finish.

**--boot-timeout** `number` (default: 30)

Seconds to wait for the sandbox to become ready when `--start` is used.

**--json** `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`.

## 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`](https://celesto.ai/docs/celesto/cli/shell) - Open an interactive shell instead
* [`celesto sandbox logs`](https://celesto.ai/docs/celesto/cli/logs) - Read the sandbox's boot and console logs
* [`celesto sandbox start`](https://celesto.ai/docs/celesto/cli/stop) - Start a stopped sandbox manually


## Related topics

- [celesto sandbox logs](https://celesto.ai/docs/celesto/cli/logs.md)
- [Use the Celesto HTTP API and TypeScript SDK](https://celesto.ai/docs/celesto/guides/http-api-typescript-sdk.md)
- [CLI overview](https://celesto.ai/docs/celesto/cli/overview.md)
- [celesto sandbox create](https://celesto.ai/docs/celesto/cli/create.md)
- [celesto sandbox list](https://celesto.ai/docs/celesto/cli/list.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.