sandbox run

Run a shell command inside an app’s sandbox, 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 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, setting the BASE44_APP_ID environment variable, or running the command from a linked project if you have one.

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 again to start a session that has it.

Usage

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:

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

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.

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:

base44 sandbox run "cd src && npm run build"

Get Started

Commands

Usage

Arguments

Flags

Output

Working directory

See also

​Usage

​Arguments

​Flags

​Output

​Working directory

​See also

Usage

Arguments

Flags

Output

Working directory

See also