> ## 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.
# Run a sandbox command
> This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.
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.
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.
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.
## OpenAPI
````yaml /developers/references/app-management/app-management-openapi.json post /api/apps/{app_id}/sandbox-bridge/run_command
openapi: 3.1.0
info:
title: Base44 App Management API
version: 1.0.0
servers:
- url: https://app.base44.com
security:
- ApiKeyAuth: []
paths:
/api/apps/{app_id}/sandbox-bridge/run_command:
post:
summary: Run a sandbox command
description: >-
This API is in beta. Endpoints, fields, and behavior may still
change, so avoid depending on it in production.
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.
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.
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.
operationId: run_command_endpoint_api_apps__app_id__sandbox_bridge_run_command_post
parameters:
- name: app_id
in: path
required: true
schema:
type: string
description: ID of the app whose sandbox to operate on.
title: App Id
description: ID of the app whose sandbox to operate on.
example: 6820f3a4e7b91d003c45a1f2
requestBody:
content:
application/json:
schema:
type: object
additionalProperties: false
default: {}
title: RunSandboxCommand
properties:
command:
description: Shell command to execute via bash inside the sandbox.
maxLength: 100000
minLength: 1
title: Command
type: string
cwd:
anyOf:
- type: string
- type: 'null'
description: >-
Working dir relative to the app root. `cd` does not persist
across calls — use this or chain commands.
title: Cwd
timeout_ms:
default: 120000
description: Timeout in milliseconds (default 120000, max 600000).
maximum: 600000
minimum: 1
title: Timeout Ms
type: integer
required:
- command
example:
command: npm install
timeout_ms: 300000
required: true
responses:
'200':
description: The command ran. Read `exit_code` for its result.
content:
application/json:
schema:
$ref: '#/components/schemas/RunCommandResult'
'401':
description: Missing or invalid credentials.
'402':
description: The app's workspace plan doesn't include the sandbox bridge.
'403':
description: >-
You don't have access to this app, the app is blocked, your OAuth
token is missing the scope this endpoint needs, or you used a
workspace API key.
'404':
description: App not found.
'409':
description: >-
The app is on a branch that can't be written to: a protected main,
or a branch that has been merged or closed.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'429':
description: Rate limit exceeded (30 requests per minute).
'504':
description: The sandbox didn't answer in time. Retry the request.
components:
schemas:
RunCommandResult:
properties:
stdout:
type: string
title: Stdout
description: Everything the command wrote to standard output.
example: |
added 12 packages in 3s
stderr:
type: string
title: Stderr
description: >-
Everything the command wrote to standard error. Populated on success
too, since many tools log there.
example: ''
exit_code:
type: integer
title: Exit Code
description: >-
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.
example: 0
truncated:
type: boolean
title: Truncated
description: >-
`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.
example: false
duration_ms:
type: integer
title: Duration Ms
description: How long the command took, in milliseconds.
example: 3120
type: object
required:
- stdout
- stderr
- exit_code
- truncated
- duration_ms
title: RunCommandResult
description: What a command left behind.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: api_key
description: Personal API key.
````