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

# Execute Command

> Run a shell command inside a sandbox

## Path Parameters

<ParamField path="id" type="string" required>
  Sandbox ID.
</ParamField>

## Request Body

If the sandbox is paused, the endpoint attempts to wake it before executing the command.

<ParamField body="command" type="string" required>
  Command to execute.
</ParamField>

<ParamField body="timeout" type="number">
  Timeout in milliseconds.
</ParamField>

<ParamField body="cwd" type="string">
  Working directory. Defaults to `/workspace` when omitted.
</ParamField>

<ParamField body="env" type="object">
  Additional environment variables for this command.
</ParamField>

## Response

<ResponseField name="stdout" type="string">
  Standard output.
</ResponseField>

<ResponseField name="stderr" type="string">
  Standard error.
</ResponseField>

<ResponseField name="exitCode" type="number">
  Process exit code.
</ResponseField>

<ResponseField name="executionTime" type="number">
  Execution time in milliseconds when available.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.runtools.ai/v1/sandboxes/sandbox-abc123/exec \
    -H "X-API-Key: $RUNTOOLS_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "command": "npm test",
      "timeout": 120000,
      "cwd": "/workspace"
    }'
  ```

  ```typescript SDK theme={null}
  const result = await sandbox.exec('npm test', {
    timeout: 120000,
    cwd: '/workspace',
  });

  console.log(result.exitCode, result.stdout, result.stderr);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "data": {
      "stdout": "Tests passed\n",
      "stderr": "",
      "exitCode": 0,
      "executionTime": 2341
    }
  }
  ```
</ResponseExample>