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
}
'

import requests

url = "https://api.declaw.ai/sandboxes/{sandbox_id}/commands"

payload = {
    "cmd": "<string>",
    "background": True,
    "cwd": "<string>",
    "envs": {},
    "timeout": 123,
    "user": "<string>",
    "stdin": True
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    cmd: '<string>',
    background: true,
    cwd: '<string>',
    envs: {},
    timeout: 123,
    user: '<string>',
    stdin: true
  })
};

fetch('https://api.declaw.ai/sandboxes/{sandbox_id}/commands', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.declaw.ai/sandboxes/{sandbox_id}/commands",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'cmd' => '<string>',
    'background' => true,
    'cwd' => '<string>',
    'envs' => [
        
    ],
    'timeout' => 123,
    'user' => '<string>',
    'stdin' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.declaw.ai/sandboxes/{sandbox_id}/commands"

	payload := strings.NewReader("{\n  \"cmd\": \"<string>\",\n  \"background\": true,\n  \"cwd\": \"<string>\",\n  \"envs\": {},\n  \"timeout\": 123,\n  \"user\": \"<string>\",\n  \"stdin\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.declaw.ai/sandboxes/{sandbox_id}/commands")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"cmd\": \"<string>\",\n  \"background\": true,\n  \"cwd\": \"<string>\",\n  \"envs\": {},\n  \"timeout\": 123,\n  \"user\": \"<string>\",\n  \"stdin\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.declaw.ai/sandboxes/{sandbox_id}/commands")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"cmd\": \"<string>\",\n  \"background\": true,\n  \"cwd\": \"<string>\",\n  \"envs\": {},\n  \"timeout\": 123,\n  \"user\": \"<string>\",\n  \"stdin\": true\n}"

response = http.request(request)
puts response.read_body

{
  "stdout": "<string>",
  "stderr": "<string>",
  "exit_code": 123,
  "pid": 123
}

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
}
'

import requests

url = "https://api.declaw.ai/sandboxes/{sandbox_id}/commands"

payload = {
    "cmd": "<string>",
    "background": True,
    "cwd": "<string>",
    "envs": {},
    "timeout": 123,
    "user": "<string>",
    "stdin": True
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    cmd: '<string>',
    background: true,
    cwd: '<string>',
    envs: {},
    timeout: 123,
    user: '<string>',
    stdin: true
  })
};

fetch('https://api.declaw.ai/sandboxes/{sandbox_id}/commands', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.declaw.ai/sandboxes/{sandbox_id}/commands",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'cmd' => '<string>',
    'background' => true,
    'cwd' => '<string>',
    'envs' => [
        
    ],
    'timeout' => 123,
    'user' => '<string>',
    'stdin' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.declaw.ai/sandboxes/{sandbox_id}/commands"

	payload := strings.NewReader("{\n  \"cmd\": \"<string>\",\n  \"background\": true,\n  \"cwd\": \"<string>\",\n  \"envs\": {},\n  \"timeout\": 123,\n  \"user\": \"<string>\",\n  \"stdin\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.declaw.ai/sandboxes/{sandbox_id}/commands")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"cmd\": \"<string>\",\n  \"background\": true,\n  \"cwd\": \"<string>\",\n  \"envs\": {},\n  \"timeout\": 123,\n  \"user\": \"<string>\",\n  \"stdin\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.declaw.ai/sandboxes/{sandbox_id}/commands")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"cmd\": \"<string>\",\n  \"background\": true,\n  \"cwd\": \"<string>\",\n  \"envs\": {},\n  \"timeout\": 123,\n  \"user\": \"<string>\",\n  \"stdin\": true\n}"

response = http.request(request)
puts response.read_body

{
  "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

string

required

The sandbox identifier. Format: sbx-<8 chars>.

Request Body

string

required

The shell command to execute inside the sandbox.Example: "python3 script.py"

boolean

default:"false"

When true, start the command in the background and return immediately with a PID. Use wait to retrieve the result later.

string

Working directory for the command. Defaults to the envd default (typically /home/user).Example: "/home/user/project"

object

Additional environment variables scoped to this command only (merged with sandbox-level envs).Example: { "DEBUG": "1" }

number

Per-command timeout in seconds. 0 means no timeout.Example: 30.0

string

Unix user to run the command as. Defaults to the envd default user.

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:

string

Full standard output produced by the command.

string

Full standard error output produced by the command.

integer

Exit code returned by the process. 0 indicates success.

When background is true, returns a BackgroundProcess:

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" }'

from declaw import Sandbox

sbx = Sandbox.connect("sbx-a1b2c3d4", api_key="YOUR_API_KEY", domain="api.declaw.ai")
result = sbx.commands.run("echo hello")
print(result.stdout)    # hello\n
print(result.exit_code) # 0

import { Sandbox } from "@declaw/sdk";

const sbx = await Sandbox.connect("sbx-a1b2c3d4", {
  apiKey: "YOUR_API_KEY",
  domain: "api.declaw.ai",
});
const result = await sbx.commands.run("echo hello");
console.log(result.stdout);   // hello\n
console.log(result.exitCode); // 0

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

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

Restore Sandbox Run Command (Stream)

Sandbox API

Command API

Filesystem API

Volumes API

Run Command

Path Parameters

Request Body

Response

Examples

Foreground command

Background command

Error Responses

​Path Parameters

​Request Body

​Response

​Examples

​Foreground command

​Background command

​Error Responses

Path Parameters

Request Body

Response

Examples

Foreground command

Background command

Error Responses