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

# ppio sandbox exec

> Run one-off commands in a running sandbox from the CLI, with a working directory, a user and environment variables, in the background or with piped input.

The `exec` command runs a single command inside a running sandbox and streams its output back to the terminal. It fits one-off commands, scripts and automation. For an interactive shell session, use the remote shell command, `connect`.

> [!NOTE]
>
> Install the CLI and set the `PPIO_API_KEY` and `PPIO_DOMAIN` environment variables before running these commands. See [Install and authenticate](https://docs.ppio.ai/sandbox/cli/install.md).

## Usage

```bash theme={null}
ppio sandbox exec <sandbox-id> <command...>
```

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

```bash theme={null}
# Run a simple command
ppio sandbox exec <sandbox-id> "ls -l /tmp"

# Using the alias
ppio sandbox ex <sandbox-id> "python3 --version"
```

## Arguments

**\<sandbox-id>** `string` *required*

ID of the running sandbox to run the command in.

**\<command...>** `string` *required*

The command to execute. Multiple parts are quoted and joined into a single shell command.

## Options

**-b, --background** `boolean`

Runs the command in the background and returns immediately, after printing the process ID.

**-c, --cwd** `string`

Working directory to run the command in.

**-u, --user** `string`

Runs the command as the specified user.

**-e, --env** `string`

Sets an environment variable for the command, in `KEY=VALUE` form. Repeat the option to set several variables.

## Foreground execution

By default, the command runs in the foreground. Its standard output and standard error stream to the terminal in real time.

```bash theme={null}
# Run in a specific directory, as a specific user, with env vars
ppio sandbox exec <sandbox-id> \
  --cwd /home/user/app \
  --user root \
  --env LOG_LEVEL=debug \
  --env REGION=us-east \
  ./run.sh
```

## Background execution

Pass `--background` to start the command and return immediately without waiting for it to finish. The CLI prints the process ID and returns.

```bash theme={null}
ppio sandbox exec <sandbox-id> --background \
  "python3 -m http.server 3000"
```

## Pipe data into a command

Data piped into the command goes through standard input. The CLI streams it to the remote process and signals end-of-file when the input is exhausted, so tools such as `cat`, `wc` and `grep` terminate correctly.

```bash theme={null}
# Pipe local data into a command running in the sandbox
cat local-file.txt | ppio sandbox exec <sandbox-id> "wc -l"

# Redirect a file into the command
ppio sandbox exec <sandbox-id> "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 the template to pick up the latest sandbox version.

## Interrupt a command

Pressing Ctrl+C, or sending a termination signal, kills the remote process before the CLI exits.


## Related topics

- [Agent Sandbox errors](https://docs.ppio.ai/sandbox/errors.md)
- [ppio sandbox connect](https://docs.ppio.ai/sandbox/cli/connect.md)
- [ppio sandbox network](https://docs.ppio.ai/sandbox/cli/network.md)


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