> ## 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](/developers/app-code/local-development/bring-your-own-agent), the cloud environment that holds the app's code. 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`](/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`](/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`](/developers/references/cli/commands/login) again to start a session that has it.
</Note>

## 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](/developers/references/cli/commands/introduction#select-a-target-app). |
| `--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](/developers/references/cli/commands/introduction#json-output).                    |

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

## Output

The command returns JSON:

```
{
  "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.
</Warning>

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

* [Bring your own agent](/developers/app-code/local-development/bring-your-own-agent): How the sandbox works, and what you can change in it
* [`sandbox edit`](/developers/references/cli/commands/sandbox-edit): Apply exact string replacements to a file
* [`sandbox write`](/developers/references/cli/commands/sandbox-write): Create a new file in the sandbox
* [`sandbox checkpoint`](/developers/references/cli/commands/sandbox-checkpoint): Save a restore point before or after a set of changes