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

> Execute a command inside a sandbox and return the result synchronously.

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](/api-reference/command/wait) and [kill](/api-reference/command/kill) endpoints.

For real-time output streaming, use the [run-stream](/api-reference/command/run-stream)
endpoint instead.

## 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 inside the sandbox.

  Example: `"python3 script.py"`
</ParamField>

<ParamField body="background" type="boolean" default="false">
  When `true`, start the command in the background and return immediately with
  a PID. Use `wait` to retrieve the result later.
</ParamField>

<ParamField body="cwd" type="string">
  Working directory for the command. Defaults to the envd default (typically
  `/home/user`).

  Example: `"/home/user/project"`
</ParamField>

<ParamField body="envs" type="object">
  Additional environment variables scoped to this command only (merged with
  sandbox-level `envs`).

  Example: `{ "DEBUG": "1" }`
</ParamField>

<ParamField body="timeout" type="number">
  Per-command timeout in seconds. `0` means no timeout.

  Example: `30.0`
</ParamField>

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

<ParamField body="stdin" type="boolean" default="false">
  Reserve a stdin pipe so you can send data later via
  [send-stdin](/api-reference/command/send-stdin). Only meaningful when
  combined with `background: true`.
</ParamField>

## Response

When `background` is `false` (default), returns a `CommandResult`:

<ResponseField name="stdout" type="string">
  Full standard output produced by the command.
</ResponseField>

<ResponseField name="stderr" type="string">
  Full standard error output produced by the command.
</ResponseField>

<ResponseField name="exit_code" type="integer">
  Exit code returned by the process. `0` indicates success.
</ResponseField>

When `background` is `true`, returns a `BackgroundProcess`:

<ResponseField name="pid" type="integer">
  Process ID assigned to the background command.
</ResponseField>

## Examples

### Foreground command

<CodeGroup>
  ```bash cURL theme={null}
  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" }'
  ```

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

  ```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 result = await sbx.commands.run("echo hello");
  console.log(result.stdout);   // hello\n
  console.log(result.exitCode); // 0
  ```
</CodeGroup>

```json Response theme={null}
{
  "stdout": "hello\n",
  "stderr": "",
  "exit_code": 0
}
```

### Background command

<CodeGroup>
  ```bash cURL theme={null}
  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 }'
  ```
</CodeGroup>

```json Response theme={null}
{
  "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)             |