> ## Documentation Index
> Fetch the complete documentation index at: https://docs.declaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Command (Stream)

> Execute a command and stream stdout/stderr in real-time via Server-Sent Events.

Executes a command inside the sandbox and streams its output to the client in
real-time using [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/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

<ParamField path="sandbox_id" type="string" required>
  The sandbox identifier. Format: `sbx-<8 chars>`.
</ParamField>

## Request Body

<ParamField body="cmd" type="string" required>
  The shell command to execute.

  Example: `"for i in 1 2 3; do echo $i; sleep 0.5; done"`
</ParamField>

<ParamField body="cwd" type="string">
  Working directory for the command.
</ParamField>

<ParamField body="envs" type="object">
  Additional environment variables scoped to this command.
</ParamField>

<ParamField body="timeout" type="number">
  Per-command timeout in seconds.
</ParamField>

<ParamField body="user" type="string">
  Unix user to run the command as.
</ParamField>

## 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

<CodeGroup>
  ```python Python theme={null}
  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="")
  ```

  ```typescript TypeScript theme={null}
  import { Sandbox } from "@declaw/sdk";

  const sbx = await Sandbox.connect("sbx-a1b2c3d4", {
    apiKey: "YOUR_API_KEY",
    domain: "api.declaw.ai",
  });

  const stream = await sbx.commands.runStream(
    "for i in 1 2 3; do echo $i; sleep 0.5; done"
  );
  for await (const event of stream) {
    if (event.stream === "stdout") {
      process.stdout.write(event.data);
    }
  }
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.declaw.ai/sandboxes/sbx-a1b2c3d4/commands/stream \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Accept: text/event-stream" \
    -d '{ "cmd": "for i in 1 2 3; do echo $i; sleep 0.5; done" }' \
    --no-buffer
  ```
</CodeGroup>

## 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                                     |