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

# sandbox run

> Run a shell command in an app's remote sandbox

Run a shell command inside an app's [sandbox](https://docs.base44.com/developers/app-code/sandbox/overview.md). Use it to install packages, run a build, check types, run tests, or make changes the file commands cannot, such as deleting a file. There's no dedicated command for that, so reach for the shell instead, for example `base44 sandbox run "rm src/old-page.jsx"` to delete a file. The same goes for creating an empty file, which [`sandbox write`](https://docs.base44.com/developers/references/cli/commands/sandbox-write) rejects, so use `base44 sandbox run "touch notes.txt"` there too.

The command runs from the app root unless you pass `--cwd`. `sandbox` commands don't require a local project. Target an app by passing [`--app-id`](https://docs.base44.com/developers/references/cli/commands/introduction#select-a-target-app), setting the `BASE44_APP_ID` environment variable, or running the command from a linked project if you have one.

> [!NOTE]
>
> This command needs the `sandbox:write` permission. The CLI requests it when you sign in, and an existing session cannot gain it afterwards. If the command fails with an authorization error, run [`base44 login`](https://docs.base44.com/developers/references/cli/commands/login) again to start a session that has it.

## Usage

```bash theme={null}
base44 sandbox run <command...>
```

Quote the command so it reaches the sandbox as one string. This matters whenever the command has flags of its own, because an unquoted `-l` or `--force` is read as a flag for `base44` instead of being passed through:

```bash theme={null}
base44 sandbox run "ls -la" --cwd src
```

## Arguments

| Argument | Description | Required |
| - | - | - |
| `<command...>` | The shell command to run. Quote it to keep it as one command. | Yes |

## Flags

| Flag | Description |
| - | - |
| `--app-id <id>` | Target the specified app. Defaults to the app linked in the current project. See [Select a target app](https://docs.base44.com/developers/references/cli/commands/introduction.md#select-a-target-app). |
| `--branch <name>` | [Target a branch](https://docs.base44.com/developers/references/cli/commands/introduction.md#target-a-branch) of the app by exact name. Defaults to `main`. |
| `--cwd <path>` | Working directory, relative to the app root. Defaults to the app root. |
| `--timeout-ms <n>` | Timeout in milliseconds. Defaults to `120000`, maximum `600000`. |
| `--json` | Keep stdout to just the JSON result, without the interactive status line. See [JSON output](https://docs.base44.com/developers/references/cli/commands/introduction.md#json-output). |

A command still running past its timeout is stopped and fails with `TIMEOUT`.

## Output

The command returns JSON:

```json theme={null}
{
  "stdout": "> build\n> vite build\n\nbuilt in 3.42s\n",
  "stderr": "",
  "exitCode": 0,
  "truncated": false,
  "durationMs": 3608
}
```

| Field | Description |
| - | - |
| `stdout` | The command's standard output. |
| `stderr` | The command's standard error output. |
| `exitCode` | Exit code of the command inside the sandbox. This is what tells you whether it worked. |
| `truncated` | `true` when `stdout` or `stderr` exceeded its own cap of roughly 1 MB and was cut short. Each stream is capped independently, so total output can reach roughly 2 MB. |
| `durationMs` | How long the command took, in milliseconds. |

> [!WARNING]
>
> The CLI exits `0` whenever it reached the sandbox successfully, no matter what the command itself returned. A failing build or a failing test suite still gives you exit code `0`. Read `exitCode` from the output to tell whether the command succeeded.

## Working directory

Each command runs in its own shell, so a `cd` does not carry over to the next one. Set the directory with `--cwd`, or chain the commands together:

```bash theme={null}
base44 sandbox run "cd src && npm run build"
```

## See also

* [Cloud sandbox](https://docs.base44.com/developers/app-code/sandbox/overview.md): How the sandbox works, and what you can change in it
* [`sandbox edit`](https://docs.base44.com/developers/references/cli/commands/sandbox-edit): Apply exact string replacements to a file
* [`sandbox write`](https://docs.base44.com/developers/references/cli/commands/sandbox-write): Create a new file in the sandbox
* [`sandbox checkpoint`](https://docs.base44.com/developers/references/cli/commands/sandbox-checkpoint): Save a restore point before or after a set of changes


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