Sandboxes provide an isolated environment for running arbitrary python code, or processes interactively. It also supports basic file system operations, networking, and public preview URLs.

​
Features

  • Process Management: Execute commands and Python code with real-time output streaming
  • File System Operations: Upload, download, list, and manage files inside the sandbox environment programatically
  • Preview URLs: Dynamically expose ports behind SSL-terminated, authenticated endpoints
  • Persistent Sessions: Keep sandboxes running indefinitely or with custom timeouts
  • GPU Support: Run GPU-accelerated workloads

​
Quick Start

Create a sandbox, run some code, and see the results:

from beam import PythonVersion, Image, Sandbox

# Create a sandbox with the tools you need
sandbox = Sandbox(
    image=Image(python_version=PythonVersion.Python311).add_python_packages(["numpy", "pandas"])
)

# Launch it into the cloud
sb = sandbox.create()

# Run some code - this happens in the cloud, not on your machine!
result = sb.process.run_code("""
import numpy as np
import pandas as pd

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

# Do some analysis
print("Data shape:", df.shape)
print("Mean values:")
print(df.mean())
print("\\nCorrelation matrix:")
print(df.corr())
""")

print(result.result)

# Clean up - shut down the sandbox
sb.terminate()

This creates a remote environment with NumPy and Pandas, runs a data analysis script, and returns the results to your local machine. The computation happens in the cloud, not on your laptop.

​
Core Features

​
Process Management

Run Python code, shell commands, or start long-running processes:

# Run some Python code
result = sb.process.run_code("print('Hello from sandbox!')")
print(result)

# Execute arbitrary shell commands
process = sb.process.exec("ls", "-la", "/workspace")
print(process.logs.read())
process.wait()

# Expose a port to the internet
url = sb.expose_port(8000)
print(f"Try visiting: {url}")

# Start a web server in the background
server_process = sb.process.exec("python3", "-m", "http.server", "8000")

try:
    for line in server_process.logs:
        print(line, end="")
finally:
    sb.terminate()

​
File System Operations

Upload local files, download results, and manage your workspace:

# Upload local files to the sandbox
sb.fs.upload_file("my_script.py", "/workspace/my_script.py")

# Run it
result = sb.process.run_code("exec(open('/workspace/my_script.py').read())")

# Download a file from the sandbox to your local
sb.fs.download_file("/workspace/output.csv", "local_results.csv")

​
Dynamic Preview URLs

Expose ports to make your services accessible over the internet:

# Start a Flask app
process = sb.process.exec("python3", "app.py", cwd="/workspace")

# Expose it to the world
url = sb.expose_port(5000)
print(f"Your app is live at: {url}")

# Share this URL with your team for instant feedback

​
Key Concepts

​
SandboxInstance

When you create a sandbox, you get a SandboxInstance class that provides:

  • process: Run commands and code with real-time output
  • fs: Upload, download, and manage files
  • expose_port(): Make your services accessible to the internet
  • terminate(): Cleanup when you’re done

​
Lifecycle

  1. Create: Configure your environment (CPU, memory, packages, etc.)
  2. Launch: Start the sandbox with create()
  3. Use: Execute code, manage files, expose services
  4. Terminate: Clean up with terminate() (or let it auto-terminate)

​
What’s Next?

Now that you understand what Sandbox can do, let’s dive deeper into each capability: