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

# Run commands in a sandbox

> Execute shell commands inside a sandbox with sync or streaming output.

Run any shell command inside a sandbox using `sandbox.commands.run()`.

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  import { Sandbox } from "@superserve/sdk"

  const sandbox = await Sandbox.create({
    name: "data-analyzer",
    fromTemplate: "superserve/python-3.11",
  })
  const result = await sandbox.commands.run("python analyze.py")
  console.log(result.stdout)
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  from superserve import Sandbox

  sandbox = Sandbox.create(name="data-analyzer", from_template="superserve/python-3.11")
  result = sandbox.commands.run("python analyze.py")
  print(result.stdout)

  sandbox.kill()
  ```
</CodeGroup>

<Note>
  This page covers `run()`. If you need to send input to a process while it runs, like a REPL, [`spawn()`](/commands/sessions) keeps the session open instead.
</Note>

<Note>
  Using `AsyncSandbox`? The same methods are there, awaitable. See the [Sandbox reference](/sdk-reference/sandbox).
</Note>

## Handling exit codes

`run()` doesn't throw on a non-zero exit code. Check `exitCode` on the result yourself.

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  const result = await sandbox.commands.run("exit 42")
  if (result.exitCode !== 0) {
    console.error(`Command failed: ${result.stderr}`)
  }
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  result = sandbox.commands.run("exit 42")
  if result.exit_code != 0:
      print(f"Command failed: {result.stderr}")
  ```
</CodeGroup>

## Working directory and environment

Pass `cwd` and `env` to control the execution context.

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  const result = await sandbox.commands.run("python script.py", {
    cwd: "/app",
    env: { PORT: "3000", DEBUG: "1" },
    timeoutMs: 60_000,
  })
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  result = sandbox.commands.run(
      "python script.py",
      cwd="/app",
      env={"PORT": "3000", "DEBUG": "1"},
      timeout_seconds=60,
  )
  ```
</CodeGroup>

<Note>
  Watch the units: TypeScript takes `timeoutMs` (milliseconds), Python takes `timeout_seconds` (seconds).
</Note>

## Timeouts

Pass a timeout to kill a command that runs longer than you expect.

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  const result = await sandbox.commands.run("sleep 100", {
    timeoutMs: 5_000,
  })
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  result = sandbox.commands.run("sleep 100", timeout_seconds=5)
  ```
</CodeGroup>

For longer commands, [stream the output](/commands/streaming) as it runs. To send input to a process while it runs, [open a session](/commands/sessions).