Skip to main content
Sandboxes are ultra-fast, Python-native environments for running any workload - with GPUs, networking, and persistent storage - in seconds.

​
Features

  • Ultra Fast Boot Times: Sandboxes cold boot in 1–3 seconds, even with dependencies included.
  • Image Caching: Beam caches dependencies in your base image, so subsequent sandboxes boot faster. You can also build custom images for each app.
  • Snapshots: Create Snapshots of the filesystem and restart Sandboxes from a previous state.
  • Preview URLs: Dynamically expose ports behind SSL-terminated, authenticated endpoints.
  • Session Management: Keep sandboxes running indefinitely, or configure them to shut down automatically after any period you choose.

​
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))

# 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("print('hello from the sandbox!')").result

print(result)

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

​
Running a Node.js server

You can run arbitrary code on Beam. It doesn’t need to be Python! For example, let’s run a Node server. We’ll track the startup time too: 
import time
from beam import Image, Sandbox

start = time.time()

# Create a sandbox on port 3000
sb = Sandbox(image=Image().from_registry("node:20")).create()
url = sb.expose_port(3000)

# Terminate sandbox after 5 minutes
sb.update_ttl(300)

# Run some code
sb.process.exec("sh", "-c", "npx http-server -p 3000 -c-1")

elapsed = time.time() - start
print(f"Node app running at: {url}")
print(f"Sandbox started in {elapsed:.2f} seconds")

​
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"Sandbox running here: {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}")

​
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: