Skip to main content
POST
/
sandboxes
/
{sandbox_id}
/
commands
Run Command
curl --request POST \
  --url https://api.declaw.ai/sandboxes/{sandbox_id}/commands \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "cmd": "<string>",
  "background": true,
  "cwd": "<string>",
  "envs": {},
  "timeout": 123,
  "user": "<string>",
  "stdin": true
}
'
{
  "stdout": "<string>",
  "stderr": "<string>",
  "exit_code": 123,
  "pid": 123
}
Executes a shell command inside the sandbox VM via the envd daemon and returns the full stdout, stderr, and exit code once the process completes. For long-running processes, pass background: true to start the command without waiting. The API returns immediately with a PID that you can use with the wait and kill endpoints. For real-time output streaming, use the run-stream endpoint instead.

​
Path Parameters

​
sandbox_id
string
required
The sandbox identifier. Format: sbx-<8 chars>.

​
Request Body

​
cmd
string
required
The shell command to execute inside the sandbox.Example: "python3 script.py"
​
background
boolean
default:"false"
When true, start the command in the background and return immediately with a PID. Use wait to retrieve the result later.
​
cwd
string
Working directory for the command. Defaults to the envd default (typically /home/user).Example: "/home/user/project"
​
envs
object
Additional environment variables scoped to this command only (merged with sandbox-level envs).Example: { "DEBUG": "1" }
​
timeout
number
Per-command timeout in seconds. 0 means no timeout.Example: 30.0
​
user
string
Unix user to run the command as. Defaults to the envd default user.
​
stdin
boolean
default:"false"
Reserve a stdin pipe so you can send data later via send-stdin. Only meaningful when combined with background: true.

​
Response

When background is false (default), returns a CommandResult:
​
stdout
string
Full standard output produced by the command.
​
stderr
string
Full standard error output produced by the command.
​
exit_code
integer
Exit code returned by the process. 0 indicates success.
When background is true, returns a BackgroundProcess:
​
pid
integer
Process ID assigned to the background command.

​
Examples

​
Foreground command

curl -X POST https://api.declaw.ai/sandboxes/sbx-a1b2c3d4/commands \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "cmd": "echo hello" }'
Response
{
  "stdout": "hello\n",
  "stderr": "",
  "exit_code": 0
}

​
Background command

curl -X POST https://api.declaw.ai/sandboxes/sbx-a1b2c3d4/commands \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "cmd": "sleep 30", "background": true }'
Response
{
  "pid": 42
}

​
Error Responses

StatusCause
400Invalid request body
401Missing or invalid API key
404Sandbox not found
409Sandbox is paused — resume it before running commands
410Sandbox has been killed
502envd daemon inside the VM is unreachable
503Sandbox has no VM (no guest IP available)