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

# Process Management

> Start, monitor, and manage background processes in sandboxes

Start long-running services, stream their output, send signals, and manage process lifecycles inside sandboxes.

<Note>
  Process operations use the sandbox proxy URL: `https://<sandbox-id-or-name>.sandbox.tensorlake.ai`

  Named sandboxes can use the sandbox name in place of the ID in the proxy hostname. The process APIs documented here run on the management URL on port `9501`, which always requires authentication. Unauthenticated proxy access applies only to exposed user ports.
</Note>

## Start a Background Process

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from tensorlake.sandbox import Sandbox


    sandbox = Sandbox.create()
        # Start a background process
        proc = sandbox.start_process("python", ["-m", "http.server", "8080"])
        print(f"PID: {proc.pid}")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const proc = await sandbox.startProcess("python", {
      args: ["-m", "http.server", "8080"],
    });

    console.log(`PID: ${proc.pid}`);
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    # Run a command in the background using shell syntax
    tl sbx exec <sandbox-id> bash -c "python -m http.server 8080 &"
    ```
  </Tab>

  <Tab title="HTTP">
    ```bash theme={null}
    curl -X POST https://<sandbox-id>.sandbox.tensorlake.ai/api/v1/processes \
      -H "Authorization: Bearer $TL_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "command": "python",
        "args": ["-m", "http.server", "8080"]
      }'
    ```

    **Response** (`201 Created`):

    ```json theme={null}
    {
      "pid": 42,
      "status": "running",
      "command": "python",
      "args": ["-m", "http.server", "8080"],
      "stdin_writable": false,
      "started_at": 1710000000000
    }
    ```

    **Request options:**

    ```json theme={null}
    {
      "command": "python",
      "args": ["-m", "http.server", "8080"],
      "env": {"PORT": "8080"},
      "working_dir": "/workspace",
      "stdin_mode": "pipe",
      "stdout_mode": "capture",
      "stderr_mode": "capture"
    }
    ```
  </Tab>
</Tabs>

## List Processes

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    # List is available via the process manager
    procs = sandbox.list_processes()
    for p in procs:
        print(f"PID {p.pid}: {p.status}")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const processes = await sandbox.listProcesses();
    for (const proc of processes) {
      console.log(`PID ${proc.pid}: ${proc.status}`);
    }
    ```
  </Tab>

  <Tab title="HTTP">
    ```bash theme={null}
    curl https://<sandbox-id>.sandbox.tensorlake.ai/api/v1/processes \
      -H "Authorization: Bearer $TL_API_KEY"
    ```

    **Response:**

    ```json theme={null}
    {
      "processes": [
        {
          "pid": 42,
          "status": "running",
          "command": "python",
          "args": ["-m", "http.server", "8080"],
          "stdin_writable": false,
          "started_at": 1710000000000
        }
      ]
    }
    ```
  </Tab>
</Tabs>

## Stream Process Output

Monitor process output in real time as it produces stdout/stderr:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    sandbox = Sandbox.create()
        proc = sandbox.start_process("python", ["-c", """
    import time
    for i in range(10):
        print(f"Processing item {i+1}/10")
        time.sleep(1)
    """])

        # Stream output line by line
        for event in sandbox.follow_output(proc.pid):
            print(event.line, end="")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const proc = await sandbox.startProcess("python", {
      args: [
        "-c",
        "import time\nfor i in range(3):\n print(f'Processing item {i+1}/3')\n time.sleep(1)",
      ],
    });

    for await (const event of sandbox.followOutput(proc.pid)) {
      console.log(event.line);
    }
    ```
  </Tab>

  <Tab title="HTTP">
    ```bash theme={null}
    # Follow combined output via SSE
    curl -N https://<sandbox-id>.sandbox.tensorlake.ai/api/v1/processes/<pid>/output/follow \
      -H "Authorization: Bearer $TL_API_KEY"
    ```

    **SSE stream:**

    ```
    event: output
    data: {"line":"Processing item 1/10\n","timestamp":1710000000000,"stream":"stdout"}

    event: output
    data: {"line":"Processing item 2/10\n","timestamp":1710000001000,"stream":"stdout"}

    event: eof
    data: {}
    ```
  </Tab>
</Tabs>

## Send Signals

Send POSIX signals to running processes:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import signal

    sandbox = Sandbox.create()
        proc = sandbox.start_process("python", ["-m", "http.server", "8080"])

        # Gracefully stop the process
        sandbox.send_signal(proc.pid, signal.SIGTERM)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    await sandbox.sendSignal(proc.pid, 15);
    ```
  </Tab>

  <Tab title="HTTP">
    ```bash theme={null}
    # Send SIGTERM (15)
    curl -X POST https://<sandbox-id>.sandbox.tensorlake.ai/api/v1/processes/<pid>/signal \
      -H "Authorization: Bearer $TL_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"signal": 15}'

    # Send SIGKILL (9)
    curl -X POST https://<sandbox-id>.sandbox.tensorlake.ai/api/v1/processes/<pid>/signal \
      -H "Authorization: Bearer $TL_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"signal": 9}'
    ```
  </Tab>
</Tabs>

## Kill a Process

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    sandbox.send_signal(proc.pid, signal.SIGKILL)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    await sandbox.killProcess(proc.pid);
    ```
  </Tab>

  <Tab title="HTTP">
    ```bash theme={null}
    curl -X DELETE https://<sandbox-id>.sandbox.tensorlake.ai/api/v1/processes/<pid> \
      -H "Authorization: Bearer $TL_API_KEY"
    ```
  </Tab>
</Tabs>

## Write to Stdin

Send input to a running process with stdin in pipe mode:

```typescript theme={null}
import { StdinMode } from "tensorlake";

const proc = await sandbox.startProcess("python", {
  args: ["-i"],
  stdinMode: StdinMode.PIPE,
});

await sandbox.writeStdin(
  proc.pid,
  new TextEncoder().encode("print('hello')\n"),
);

await sandbox.closeStdin(proc.pid);
```

```bash theme={null}
# Start a process with stdin pipe
curl -X POST https://<sandbox-id>.sandbox.tensorlake.ai/api/v1/processes \
  -H "Authorization: Bearer $TL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "python", "args": ["-i"], "stdin_mode": "pipe"}'

# Write to stdin
curl -X POST https://<sandbox-id>.sandbox.tensorlake.ai/api/v1/processes/<pid>/stdin \
  -H "Authorization: Bearer $TL_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary "print('hello')\n"

# Close stdin
curl -X POST https://<sandbox-id>.sandbox.tensorlake.ai/api/v1/processes/<pid>/stdin/close \
  -H "Authorization: Bearer $TL_API_KEY"
```

## Learn More

<CardGroup cols={3}>
  <Card title="Commands" icon="terminal" href="/sandboxes/commands">
    Execute commands in sandboxes.
  </Card>

  <Card title="Lifecycle" icon="arrows-spin" href="/sandboxes/lifecycle">
    Sandbox states, resources, and timeouts.
  </Card>

  <Card title="Networking" icon="globe" href="/sandboxes/networking">
    Control internet access and outbound destinations.
  </Card>
</CardGroup>