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

# Execute

The `sandbox exec` command runs a single command inside an already-running sandbox and streams its output back to your terminal. Use it for one-off commands, scripts, and automation; for an interactive shell session, use the remote shell (`connect`) command instead.

## Prerequisites

Set the `NOVITA_API_KEY` environment variable before running the command. You also need the ID of a running sandbox.

## Usage

```bash CLI icon="terminal" theme={"system"}
novita-sandbox-cli sandbox exec <sandboxID> <command...>
```

The command has the alias `ex`. Everything after the sandbox ID is treated as the command to execute.

```bash CLI icon="terminal" theme={"system"}
# Run a simple command
novita-sandbox-cli sandbox exec sbx-123 ls -l /tmp

# Using the alias
novita-sandbox-cli sandbox exec sbx-123 python3 --version
```

## Arguments

| Argument       | Description                                                                               |
| -------------- | ----------------------------------------------------------------------------------------- |
| `<sandboxID>`  | ID of the running sandbox to execute the command in.                                      |
| `<command...>` | The command to execute. Multiple parts are quoted and joined into a single shell command. |

## Options

| Option                  | Description                                                                                                                 |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `-b, --background`      | Run the command in the background and return immediately. The process ID (PID) is printed, and the CLI exits with code `0`. |
| `-c, --cwd <dir>`       | Working directory to run the command in.                                                                                    |
| `-u, --user <user>`     | Run the command as the specified user.                                                                                      |
| `-e, --env <KEY=VALUE>` | Set an environment variable for the command. Repeatable to set multiple variables.                                          |

## Foreground execution

By default, the command runs in the foreground. Its `stdout` and `stderr` stream to your terminal in real time, and the CLI exits with the same exit code as the remote command.

```bash CLI icon="terminal" theme={"system"}
# Run in a specific directory, as a specific user, with env vars
novita-sandbox-cli sandbox exec sbx-123 \
  --cwd /home/user/app \
  --user root \
  --env LOG_LEVEL=debug \
  --env REGION=us-east \
  ./run.sh
```

## Background execution

Pass `-b` / `--background` to start the command and return immediately without waiting for it to finish. The CLI prints the process ID and exits with code `0`.

```bash CLI icon="terminal" theme={"system"}
novita-sandbox-cli sandbox exec sbx-123 --background \
  "python3 -m http.server 3000"
```

## Piping stdin

You can pipe data into the command through standard input; the CLI streams it to the remote process and signals end-of-file when the input is exhausted, so tools like `cat`, `wc`, and `grep` terminate correctly.

```bash CLI icon="terminal" theme={"system"}
# Pipe local data into a command running in the sandbox
cat local-file.txt | novita-sandbox-cli sandbox exec sbx-123 "wc -l"

# Redirect a file into the command
novita-sandbox-cli sandbox exec sbx-123 "grep error" < app.log
```

<Warning>
  Piped stdin requires a recent sandbox version. If the sandbox does not support it, the CLI prints a warning and ignores the piped input — rebuild your template to pick up the latest sandbox version.
</Warning>

## Exit codes and interruption

* In the foreground, the CLI exits with the remote command's exit code, so it composes naturally with shell scripts and CI.
* If the command cannot be started or another error occurs, the CLI prints the error and exits with code `1`.
* Pressing `Ctrl+C` (or sending a termination signal) kills the remote process before the CLI exits.