Skip to main content
POST
/
sandboxes
/
{sandbox_id}
/
commands
/
stream
Run Command (Stream)
curl --request POST \
  --url https://api.declaw.ai/sandboxes/{sandbox_id}/commands/stream \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "cmd": "<string>",
  "cwd": "<string>",
  "envs": {},
  "timeout": 123,
  "user": "<string>"
}
'
Executes a command inside the sandbox and streams its output to the client in real-time using Server-Sent Events (SSE). The response has Content-Type: text/event-stream. Use this endpoint when you want to display output incrementally as the command runs, rather than waiting for it to complete.

​
Path Parameters

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

​
Request Body

​
cmd
string
required
The shell command to execute.Example: "for i in 1 2 3; do echo $i; sleep 0.5; done"
​
cwd
string
Working directory for the command.
​
envs
object
Additional environment variables scoped to this command.
​
timeout
number
Per-command timeout in seconds.
​
user
string
Unix user to run the command as.

​
Response

The response has Content-Type: text/event-stream. Each SSE event carries a JSON payload. The stream terminates when the command exits.

​
SSE Event Format

event: stdout
data: {"stream":"stdout","data":"1\n"}

event: stdout
data: {"stream":"stdout","data":"2\n"}

event: exit
data: {"exit_code":0}
The stream proxies SSE events directly from the envd daemon inside the VM, so the exact event format may include additional fields.

​
Example

from declaw import Sandbox

sbx = Sandbox.connect("sbx-a1b2c3d4", api_key="YOUR_API_KEY", domain="api.declaw.ai")

for event in sbx.commands.run_stream("for i in 1 2 3; do echo $i; sleep 0.5; done"):
    if event.stream == "stdout":
        print(event.data, end="")

​
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