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

CLI

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.

CLI

# 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.

CLI

# 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.

CLI

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.

CLI

# 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

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.

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.

Get started

Model APIs

Novita Sandbox

GPUs

Observability

Resources

Prerequisites

Usage

Arguments

Options

Foreground execution

Background execution

Piping stdin

Exit codes and interruption

​Prerequisites

​Usage

​Arguments

​Options

​Foreground execution

​Background execution

​Piping stdin

​Exit codes and interruption

Prerequisites

Usage

Arguments

Options

Foreground execution

Background execution

Piping stdin

Exit codes and interruption