Sign in

Run a sandbox command

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Runs a shell command inside the app's sandbox with bash and returns its output.

Every sandbox-bridge endpoint runs against the app's live sandbox, the same filesystem the Base44 builder edits, so a change here is visible in the builder immediately.

A command that exits non-zero still answers 200. Read exit_code to tell a failed command from a failed request, and expect stderr to carry output on success too, since many tools log there.

Each call starts in the app root unless you set cwd, and cd does not carry over between calls, so chain directory changes inside one command instead. The default timeout is 120000 ms and the maximum is 600000 ms; a command that outruns its timeout answers 504. Output is capped at 1 MB per stream, and truncated tells you when that happened.

This endpoint is limited to 30 requests per minute per app, its own budget rather than one shared with the other sandbox-bridge endpoints.

<Warning>A write is committed, not checkpointed. Only checkpoints appear in the builder's version history, and a Restore or Revert there rolls the app back to the last checkpoint and discards everything written after it. Call Create a sandbox checkpoint when you finish a unit of work and before you stop.</Warning>

<Note>The sandbox bridge needs a Builder plan or higher on the app's workspace, and answers 402 below that. Workspace API keys are not authorized and are rejected with a 403, and it is unavailable for agent apps. A personal API key works as-is. An OAuth access token needs the sandbox:write scope.</Note>

<Tip>Every error response carries a stable extra_data.code alongside the human-readable message. Branch on the code rather than on the message text or the status.</Tip>

post/api/apps/{app_id}/sandbox-bridge/run_command

Path parameters

app_idstring required

ID of the app whose sandbox to operate on.

ID of the app whose sandbox to operate on.

Request body

branch_idstring nullable

Optional Base44 branch ID. Omit to operate on main.

commandstring required

Shell command to execute via bash inside the sandbox.

cwdstring nullable

Working dir relative to the app root. cd does not persist across calls — use this or chain commands.

timeout_msinteger

Timeout in milliseconds (default 120000, max 600000).

Response

The command ran. Read exit_code for its result.

stdoutstring required

Everything the command wrote to standard output.

stderrstring required

Everything the command wrote to standard error. Populated on success too, since many tools log there.

exit_codeinteger required

The command's exit status. 0 means success. A non-zero status is still a 200 from this endpoint: the command ran and failed, which is not a request error.

truncatedboolean required

true when the output hit the 1 MB cap and was cut short. stdout and stderr are each capped, and either one hitting it sets this.

duration_msinteger required

How long the command took, in milliseconds.

Example response

{
  "stdout": "added 12 packages in 3s\n",
  "duration_ms": 3120
}

Changes

Changed in 2 of the 14 revisions of this API.2