Run Sandbox Execution

POST
/workspaces
/:workspace
/sandboxes
/:sandbox_id
/execs

Run a one-shot execution in the sandbox: command runs with the chosen runtime. Follow it with the exec status and log endpoints of the sandbox.

Info

Returns right away with an execution_id. For short commands that should return output in the response, use Execute Command.

Request

REQUIRED SCOPES

SANDBOX_USE

URL PARAMETERS

workspacerequiredstring

The human-readable ID of the workspace

Example: "my-company"

sandbox_idrequiredstring

The ID of the sandbox

Example: "sb-1234567890abcdef"

BODY PARAMETERS

commandrequiredstring

Command to execute in the sandbox

runtimestring enum

Runtime environment for command execution (default: BASH)

Allowed enum:

BASH,

JAVASCRIPT,

TYPESCRIPT,

PYTHON

Response

RESPONSE BODY

typestring enum

The type of the execution: COMMAND (a command in the target's language) or MCP (an operation on the integration's MCP server)

Allowed enum:

COMMAND,

MCP

urlread-onlystring

API endpoint to GET this object

html_urlread-onlystring

Web URL to view this object in Buddy.works

execution_idstring

The ID of the execution

target_idstring

The ID of the target

target_typestring enum

The type of the target

Allowed enum:

FTP,

SSH,

MATCH,

MATCH_ID,

VULTR,

DIGITAL_OCEAN,

UPCLOUD,

GIT,

ARTIFACT_VERSION,

GKE,

EKS,

AKS,

DOKS,

K8S_CLUSTER,

EC2,

AGENT,

SANDBOX,

MYSQL,

PROJECT_REPO,

POSTGRESQL,

MONGO,

MSSQL,

RDS_MSSQL,

CLICKHOUSE,

RDS_MYSQL,

RDS_POSTGRESQL

integrationstring

The hash ID of the integration the execution ran on (MCP executions)

sandboxstring

The ID of the sandbox the command ran in (sandbox executions)

runtimestring enum

The runtime the command ran with (sandbox executions)

Allowed enum:

BASH,

JAVASCRIPT,

TYPESCRIPT,

PYTHON

invokerMemberView

User/member reference

cancelled_byMemberView

User/member reference

proxy_target_idstring

The ID of the proxy target used to tunnel the connection

commandstring

The executed command; for an MCP execution the operation as canonical JSON

started_atstring

The date and time when the execution started

finished_atstring

The date and time when the execution finished

statusstring

The status of the execution. One of: INPROGRESS, SUCCESSFUL, FAILED, CANCELLED

failure_reasonstring

Platform-level reason a FAILED execution failed (absent for an ordinary non-zero exit): TIMEOUT (hard time cap reached), SPAWN_FAILED (execution could not be started), BASTION_FAILED (SSH bastion tunnel failed)

exit_codeinteger

The exit code of the executed command

bytes_outinteger

The size of the execution output in bytes

truncatedboolean

Indicates if the execution output was truncated

error_messagestring

The error message if the execution failed

log_urlstring

The URL to fetch the execution log

Last modified on Oct 27, 2026

Restart Start Sandbox

Examples

Sandbox command request Sandbox Python command request

Example: Sandbox command request


curl -X POST "https://api.buddy.works/workspaces/:workspace/sandboxes/:sandbox_id/execs" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "command": "ls -la"
}'

Example: Sandbox Python command request


curl -X POST "https://api.buddy.works/workspaces/:workspace/sandboxes/:sandbox_id/execs" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "runtime": "PYTHON",
  "command": "print('hello')"
}'

EXAMPLE RESPONSE
{
  "url": "https://api.buddy.works/workspaces/my-workspace/sandboxes/sb-1234567890abcdef/execs/5c2e8a14-3b7d-4f61-a9e0-6d4b1c8f2e73",
  "log_url": "https://api.buddy.works/workspaces/my-workspace/sandboxes/sb-1234567890abcdef/execs/5c2e8a14-3b7d-4f61-a9e0-6d4b1c8f2e73/log",
  "execution_id": "5c2e8a14-3b7d-4f61-a9e0-6d4b1c8f2e73",
  "sandbox": "sb-1234567890abcdef",
  "runtime": "BASH",
  "type": "COMMAND",
  "invoker": {
    "url": "https://api.buddy.works/workspaces/my-workspace/members/1",
    "id": 1,
    "name": "John Doe"
  },
  "command": "ls -la",
  "started_at": "2026-05-28T08:00:09.820Z",
  "status": "INPROGRESS"
}

STATUS
200 Execution accepted and started; row carries `status: RUNNING` until poll endpoints flip to terminal