Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.beam.cloud/llms.txt

Use this file to discover all available pages before exploring further.

The Sandbox provides process management through the process property. You can execute Python code, run shell commands, and manage long-running processes with real-time output streaming.

Running Python Code

Basic Code Execution

from beam import Sandbox, Image, PythonVersion

sandbox = Sandbox(image=Image(python_version=PythonVersion.Python311))
sb = sandbox.create()

# Run simple Python code
result = sb.process.run_code("print('Hello from sandbox!')")
print(result.result)  # Hello from sandbox!
print(f"Exit code: {result.exit_code}")  # 0

Complex Python Scripts

# Multi-line Python code
code = """
import numpy as np
import pandas as pd

# Generate sample data
data = np.random.randn(1000, 3)
df = pd.DataFrame(data, columns=['A', 'B', 'C'])

# Calculate statistics
stats = df.describe()
print("Data Statistics:")
print(stats)

# Save results
df.to_csv('/workspace/data.csv', index=False)
print("Data saved to /workspace/data.csv")
"""

response = sb.process.run_code(code)
print(response.result)

Error Handling

# Code with errors
response = sb.process.run_code("""
import nonexistent_module
print("This won't execute")
""")

print(f"Exit code: {response.exit_code}")  # Non-zero exit code
print(f"Error output: {response.result}")  # Error message

Executing Commands

Basic Command Execution

# Run a simple command
process = sb.process.exec("ls", "-la", "/workspace")

# Wait for completion
exit_code = process.wait()
print(f"Command completed with exit code: {exit_code}")

# Get all output
for line in process.logs:
    print(line, end="")

Shell Commands

# Use shell features
process = sb.process.exec("echo $HOME && pwd && whoami")

# Wait and get output
process.wait()
for line in process.logs:
    print(line, end="")

Working Directory

# Execute in specific directory
process = sb.process.exec("ls", "-la", cwd="/workspace")
process.wait()

# Create directory and work in it
sb.process.run_code("import os; os.makedirs('/workspace/myproject', exist_ok=True)")
process = sb.process.exec("touch", "test.txt", cwd="/workspace/myproject")

Environment Variables

# Set environment variables for command
env = {
    "DATABASE_URL": "postgresql://localhost/mydb",
    "DEBUG": "true",
    "API_KEY": "secret-key"
}

process = sb.process.exec("env", "|", "grep", "DATABASE", env=env)
process.wait()

Non-blocking Execution

Background Processes

# Start a long-running process without waiting
process = sb.process.run_code("""
import time
for i in range(10):
    print(f"Processing {i}...")
    time.sleep(1)
""", blocking=False)

print(f"Process started with PID: {process.pid}")

# Do other work while it runs
print("Process is running in background...")

# Check if still running
print(f"Exit code: {process.exit_code}")  # -1 if still running

# Wait for completion when ready
process.wait()
print("Process completed!")

Real-time Output Streaming

# Start process and stream output in real-time
process = sb.process.run_code("""
import time
for i in range(5):
    print(f"Step {i}: Processing...")
    time.sleep(1)
print("Done!")
""", blocking=False)

# Stream output as it happens
for line in process.logs:
    print(f"[REAL-TIME] {line}", end="")

Process Control

Process Management

# Start multiple processes
process1 = sb.process.exec("sleep", "30", blocking=False)
process2 = sb.process.exec("sleep", "60", blocking=False)

print(f"Process 1 PID: {process1.pid}")
print(f"Process 2 PID: {process2.pid}")

# List all running processes
for p in sb.process.list_processes():
    print(f"PID {p.pid}: {p.status()}")

# Kill specific process
process1.kill()
print("Process 1 killed")

# Get process by PID
specific_process = sb.process.get_process(process2.pid)
print(f"Process 2 status: {specific_process.status()}")

Process Status and Monitoring

# Start a process
process = sb.process.exec("sleep", "10", blocking=False)

# Monitor status
while True:
    exit_code, status = process.status()
    print(f"PID {process.pid}: Exit code {exit_code}, Status: {status}")

    if exit_code >= 0:
        print("Process completed")
        break

    time.sleep(1)

Process Output Streams

# Start process with output
process = sb.process.run_code("""
import sys
print("This goes to stdout")
print("This also goes to stdout", file=sys.stdout)
print("This goes to stderr", file=sys.stderr)
""", blocking=False)

# Read stdout
print("=== STDOUT ===")
for line in process.stdout:
    print(f"STDOUT: {line}", end="")

# Read stderr
print("=== STDERR ===")
for line in process.stderr:
    print(f"STDERR: {line}", end="")

# Read combined logs
print("=== COMBINED LOGS ===")
for line in process.logs:
    print(f"LOG: {line}", end="")

List running processes

# List running processes
processes = sb.process.list_processes()
for pid, process in processes.items():
    print(f"PID {process.pid}: {process.exit_code}")