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
}Command API
Run Command
Execute a command inside a sandbox and return the result synchronously.
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
When
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.0string
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
Whenbackground 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.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) |