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

# Sandbox Processes

## Run a Command

`sandbox.exec(...)` to run a command in the sandbox.

<CodeGroup>
  ```typescript Node.js theme={null}
  const result = await sandbox.exec("node -v");

  console.log("Exit code:", result.exitCode);
  console.log("Stdout:", result.stdout.trim());
  console.log("Stderr:", result.stderr.trim());
  ```

  ```python Python theme={null}
  result = sandbox.exec("node -v")

  print(f"Exit code: {result.exit_code}")
  print(f"Stdout: {result.stdout.strip()}")
  print(f"Stderr: {result.stderr.strip()}")
  ```
</CodeGroup>

You can also pass request-scoped options on the same call:

<CodeGroup>
  ```typescript Node.js theme={null}
  const result = await sandbox.exec("pwd && echo $FOO && whoami", {
    cwd: "/tmp",
    env: {
      FOO: "bar",
    },
    timeoutMs: 5_000,
    runAs: "root",
  });
  ```

  ```python Python theme={null}
  result = sandbox.exec(
      "pwd && echo $FOO && whoami",
      cwd="/tmp",
      env={"FOO": "bar"},
      timeout_ms=5000,
      run_as="root",
  )
  ```
</CodeGroup>

## Start a Background Process

Use `sandbox.processes.start(...)` when you need to keep a process running:

<CodeGroup>
  ```typescript Node.js theme={null}
  const process = await sandbox.processes.start(
    "read line; echo stdout:$line; echo stderr:$line 1>&2",
    {
      runAs: "root",
    }
  );

  await process.writeStdin({
    data: "hello\n",
    eof: true,
  });

  const result = await process.wait();
  console.log(result.stdout);
  console.log(result.stderr);
  ```

  ```python Python theme={null}
  process = sandbox.processes.start(
      "read line; echo stdout:$line; echo stderr:$line 1>&2",
      run_as="root",
  )

  process.write_stdin(data="hello\n", eof=True)

  result = process.wait()
  print(result.stdout)
  print(result.stderr)
  ```
</CodeGroup>

## Get, List, and Signal Processes

Inspect running processes or control them later by ID:

<CodeGroup>
  ```typescript Node.js theme={null}
  const process = await sandbox.processes.start("sleep 30", {
    runAs: "root",
  });

  const fetched = await sandbox.getProcess(process.id);
  const listing = await sandbox.processes.list({
    status: "running",
    limit: 20,
  });

  await fetched.signal("TERM");
  const result = await fetched.wait();

  console.log(listing.data.map((entry) => entry.id));
  console.log(result.status);
  ```

  ```python Python theme={null}
  process = sandbox.processes.start("sleep 30", run_as="root")

  fetched = sandbox.get_process(process.id)
  listing = sandbox.processes.list(status="running", limit=20)

  fetched.signal("TERM")
  result = fetched.wait()

  print([entry.id for entry in listing.data])
  print(result.status)
  ```
</CodeGroup>

`result()` is a convenience alias for `wait()` on a process handle.

## Stream Process Output

Stream stdout and stderr as server-sent events:

<CodeGroup>
  ```typescript Node.js theme={null}
  const process = await sandbox.processes.start("echo stream-out; echo stream-err 1>&2");

  for await (const event of process.stream()) {
    if (event.type === "exit") {
      console.log("Exited with:", event.result.exitCode);
      break;
    }

    console.log(event.type, event.data);
  }
  ```

  ```python Python theme={null}
  process = sandbox.processes.start("echo stream-out; echo stream-err 1>&2")

  for event in process.stream():
      if event.type == "exit":
          print(f"Exited with: {event.result.exit_code}")
          break

      print(event.type, event.data)
  ```
</CodeGroup>

## Common Parameters

<ParamField path="command" type="string" required>
  Command to run inside the sandbox.
</ParamField>

<ParamField path="cwd" type="string">
  Working directory for the process.
</ParamField>

<ParamField path="env" type="object">
  Environment variables to inject into the process.
</ParamField>

<ParamField path="timeoutMs" type="number">
  Maximum runtime in milliseconds.
</ParamField>

<ParamField path="runAs" type="string">
  Run the command as a specific sandbox user, for example `root`.
</ParamField>

## Process Status Values

* `queued`
* `running`
* `exited`
* `failed`
* `killed`
* `timed_out`