Execute Commands

Run shell commands inside sandboxes with full stdout/stderr capture, real-time streaming, and configurable timeouts.

Sandbox-specific operations use the sandbox proxy URL: https://<sandbox-id-or-name>.sandbox.tensorlake.aiFor named sandboxes, you can use the sandbox name in place of the ID — both in the proxy hostname and in CLI/API commands. For example, https://my-env.sandbox.tensorlake.ai/api/v1/processes and tl sbx exec my-env python main.py work the same as their ID-based equivalents. The proxy resolves the name to the underlying sandbox automatically.The command and 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.

Basic Execution

CLI
Python
TypeScript
HTTP

# Run in an existing sandbox — use the sandbox ID or name
tl sbx exec my-env python -c 'print("Hello from sandbox!")'

# Or create, run, and tear down in one step
tl sbx run python -c 'print("Hello from sandbox!")'

from tensorlake.sandbox import SandboxClient

client = SandboxClient()

with client.create_and_connect() as sandbox:
    result = sandbox.run("python", ["-c", "print('Hello from sandbox!')"])
    print(result.stdout)     # Hello from sandbox!
    print(result.exit_code)  # 0

const result = await sandbox.run("python", {
  args: ["-c", "print('Hello from sandbox!')"],
});

console.log(result.stdout);   // Hello from sandbox!
console.log(result.exitCode); // 0

# Start a Python process inside the sandbox
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": ["-c", "print(\"Hello from sandbox!\")"]
  }'

Response:

{
  "pid": 294,
  "status": "running",
  "exit_code": null,
  "signal": null,
  "stdin_writable": false,
  "command": "python",
  "args": ["-c", "print(\"Hello from sandbox!\")"],
  "started_at": 1773950042728,
  "ended_at": null
}

CLI Options

CLI
Python
TypeScript
HTTP

# Timeout is in seconds
tl sbx exec <sandbox-id> --timeout 10 python -c 'print("hi")'

# Run from a specific working directory
tl sbx exec <sandbox-id> --workdir /workspace python main.py

# Inject environment variables into a single command
tl sbx exec <sandbox-id> --env MODE=prod --env DEBUG=0 /bin/sh -lc 'printf "%s %s\n" "$MODE" "$DEBUG"'

# Keep the sandbox after a one-shot run so you can inspect it afterwards
tl sbx run --keep /bin/sh -lc 'echo KEEP_TEST && sleep 1'

A verified --env run printed prod 0. A verified --keep run ended with Sandbox <id> kept alive., and tl sbx ls --all then showed that sandbox as running.

# Run with a timeout, working directory, and per-command environment
result = sandbox.run(
    "python",
    ["main.py"],
    env={"MODE": "prod", "DEBUG": "0"},
    working_dir="/workspace",
    timeout=10,
)

const result = await sandbox.run("python", {
  args: ["main.py"],
  env: { MODE: "prod", DEBUG: "0" },
  workingDir: "/workspace",
  timeout: 10,
});

console.log(result.exitCode);

# Start a process with custom environment variables and working directory
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": ["main.py"],
    "env": {"MODE": "prod", "DEBUG": "0"},
    "working_dir": "/workspace"
  }'

Shell Commands

CLI
Python
TypeScript
HTTP

# Count Python files in /workspace with a pipe
tl sbx exec <sandbox-id> bash -c "ls -la /workspace | grep '.py' | wc -l"

# Redirect stdout and stderr to files
tl sbx exec <sandbox-id> bash -c "python script.py > output.txt 2> errors.txt"

# Chain setup and execution in one shell command
tl sbx exec <sandbox-id> bash -c "cd /workspace && pip install -r requirements.txt && python main.py"

with client.create_and_connect() as sandbox:
    # Pipes
    result = sandbox.run("bash", ["-c", "ls -la /workspace | grep '.py' | wc -l"])
    print(result.stdout)

    # Redirects
    sandbox.run("bash", ["-c", "python script.py > output.txt 2> errors.txt"])

    # Command chaining
    sandbox.run("bash", ["-c", "cd /workspace && pip install -r requirements.txt && python main.py"])

const count = await sandbox.run("bash", {
  args: ["-lc", "ls -la /workspace | grep '.py' | wc -l"],
});
console.log(count.stdout);

await sandbox.run("bash", {
  args: ["-lc", "python script.py > output.txt 2> errors.txt"],
});

await sandbox.run("bash", {
  args: [
    "-lc",
    "cd /workspace && pip install -r requirements.txt && python main.py",
  ],
});

# Use bash when you need pipes, redirects, or command chaining
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": "bash",
    "args": ["-c", "ls -la /workspace | grep .py | wc -l"]
  }'

Get Process Output

Python
TypeScript
HTTP
CLI

with client.create_and_connect() as sandbox:
    result = sandbox.run("python", ["-c", "print('hello')"])
    print(result.stdout)
    print(result.stderr)

import { ProcessStatus } from "tensorlake";

const proc = await sandbox.startProcess("python", {
  args: [
    "-c",
    "import sys; print('hello'); print('oops', file=sys.stderr)",
  ],
});

let info = await sandbox.getProcess(proc.pid);
while (info.status === ProcessStatus.RUNNING) {
  await new Promise((resolve) => setTimeout(resolve, 100));
  info = await sandbox.getProcess(proc.pid);
}

console.log((await sandbox.getStdout(proc.pid)).lines);
console.log((await sandbox.getStderr(proc.pid)).lines);
console.log((await sandbox.getOutput(proc.pid)).lines);

# Get stdout
curl https://<sandbox-id>.sandbox.tensorlake.ai/api/v1/processes/<pid>/stdout \
  -H "Authorization: Bearer $TL_API_KEY"

# Get stderr
curl https://<sandbox-id>.sandbox.tensorlake.ai/api/v1/processes/<pid>/stderr \
  -H "Authorization: Bearer $TL_API_KEY"

# Get combined output
curl https://<sandbox-id>.sandbox.tensorlake.ai/api/v1/processes/<pid>/output \
  -H "Authorization: Bearer $TL_API_KEY"

Combined output response:

{
  "pid": 297,
  "lines": ["hello", "oops"],
  "line_count": 2
}

Interactive Shell

CLI
Python
TypeScript
HTTP

# Open an interactive shell in the sandbox
tl sbx ssh <sandbox-id>

# Use a custom shell
tl sbx ssh <sandbox-id> --shell /bin/sh

with client.create_and_connect() as sandbox:
    pty = sandbox.create_pty(
        command="/bin/bash",
        rows=24,
        cols=80,
    )

    pty.send_input("pwd\nexit\n")
    print(pty.wait())

const pty = await sandbox.createPty({
  command: "/bin/bash",
  rows: 24,
  cols: 80,
});

await pty.sendInput("pwd\nexit\n");
console.log(await pty.wait());

# 1. Create a PTY session
curl -X POST https://<sandbox-id>.sandbox.tensorlake.ai/api/v1/pty \
  -H "Authorization: Bearer $TL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "/bin/bash", "rows": 24, "cols": 80}'

Response:

{
  "session_id": "LYtJOrxE9Kz3bphPUDzuX",
  "token": "<pty-session-token>"
}

# 2. Connect via WebSocket
wscat -c "wss://<sandbox-id>.sandbox.tensorlake.ai/api/v1/pty/<session-id>/ws?token=<token>"

tl sbx ssh requires an interactive terminal and automatically resumes a suspended sandbox before opening the PTY session. For the full programmatic PTY flow, including the READY handshake, binary WebSocket opcodes, and clean shutdown, see PTY Sessions.

Error Handling

CLI
Python
TypeScript
HTTP

# The CLI prints stderr and returns a non-zero exit code on failure
tl sbx exec <sandbox-id> python -c "import nonexistent_module"

with client.create_and_connect() as sandbox:
    result = sandbox.run("python", ["-c", "import nonexistent_module"])

    if result.exit_code != 0:
        print(f"Command failed with exit code {result.exit_code}")
        print(f"stderr: {result.stderr}")

const result = await sandbox.run("python", {
  args: ["-c", "import nonexistent_module"],
});

if (result.exitCode !== 0) {
  console.log(`Command failed with exit code ${result.exitCode}`);
  console.log(`stderr: ${result.stderr}`);
}

# Check the exited process status
curl https://<sandbox-id>.sandbox.tensorlake.ai/api/v1/processes/<pid> \
  -H "Authorization: Bearer $TL_API_KEY"

Process status response:

{
  "pid": 305,
  "status": "exited",
  "exit_code": 1,
  "signal": null,
  "stdin_writable": false,
  "command": "python",
  "args": ["-c", "import nonexistent_module"],
  "started_at": 1773950228855,
  "ended_at": 1773950228866
}

stderr response:

{
  "pid": 305,
  "lines": [
    "Traceback (most recent call last):",
    "  File \"<string>\", line 1, in <module>",
    "ModuleNotFoundError: No module named 'nonexistent_module'"
  ],
  "line_count": 3
}

Streaming Output

Stream stdout/stderr in real time for long-running commands using Server-Sent Events:

CLI
Python
TypeScript
HTTP

tl sbx exec streams combined output to your terminal while the process runs.

with client.create_and_connect() as sandbox:
    # Start a long-running process
    proc = sandbox.start_process("python", ["-c", """
import time
for i in range(5):
    print(f"Step {i+1}/5")
    time.sleep(1)
"""])

    # Stream output as it arrives
    for event in sandbox.follow_output(proc.pid):
        print(event.line, end="")

const proc = await sandbox.startProcess("python", {
  args: [
    "-c",
    "import time\nfor i in range(5):\n print(f'Step {i+1}/5')\n time.sleep(1)",
  ],
});

for await (const event of sandbox.followOutput(proc.pid)) {
  process.stdout.write(event.line);
}

# Follow stdout via SSE
curl -N https://<sandbox-id>.sandbox.tensorlake.ai/api/v1/processes/<pid>/stdout/follow \
  -H "Authorization: Bearer $TL_API_KEY"

# 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":"Step 1/2","timestamp":1773950220162,"stream":"stdout"}

event: output
data: {"line":"Step 2/2","timestamp":1773950220162,"stream":"stdout"}

event: eof
data: {}

Learn More

Processes

Manage background processes.

File Operations

Read, write, and copy files.

Lifecycle

Sandbox states, resources, and timeouts.

Overview

Guides

Use Cases

Basic Execution

CLI Options

Shell Commands

Get Process Output

Interactive Shell

Error Handling

Streaming Output

Learn More

Processes

File Operations

Lifecycle

Overview

Guides

Use Cases

​Basic Execution

​CLI Options

​Shell Commands

​Get Process Output

​Interactive Shell

​Error Handling

​Streaming Output

​Learn More

Processes

File Operations

Lifecycle

Basic Execution

CLI Options

Shell Commands

Get Process Output

Interactive Shell

Error Handling

Streaming Output

Learn More