Sandboxes are configurable cloud environments. You control CPU, memory, GPU, dependencies, environment variables, and storage so each sandbox can be customized exactly to your needs.

​
Basic

Start with the simplest configuration: 
from beam import Sandbox, Image

# Default: 1 CPU, 128MB RAM, Python 3.11
sandbox = Sandbox()
sb = sandbox.create()
This gives you a minimal environment that works well for simple scripts and running untrusted code. For most real work, you’ll want to customize the resources.

​
Advanced compute settings

You can increase CPU, memory, or assign a GPU - depending on your use case: 
# Simple scripts, web scraping
sandbox = Sandbox(cpu=1.0)

# Data processing, API development
sandbox = Sandbox(cpu=2.0, memory="16Gi")

# Machine learning, complex analysis, rendering
sandbox = Sandbox(cpu=4.0, memory="16Gi", gpu="A10G")

​
Customize your environment

See the Images section for more information on how to customize the runtime.

​
Persistent Storage

Beam supports two types of persistent storage: fast distributed volumes and cloud buckets you already manage.

​
Distributed Storage Volumes

Mount fast storage volumes to persist files between sessions: 
from beam import Volume

# Mount a storage volume to your sandbox
volume = Volume(name="documents", mount_path="/workspace/documents")

sandbox = Sandbox(volumes=[volume])
Use volumes when you:
  • Are working on a project that spans multiple sessions
  • Need to share data between different sandbox instances
  • Want to keep work safe even if sandbox crashes

​
Cloud Buckets

For large datasets or team sharing, you can use your own buckets: 
from beam import CloudBucket

# Connect to your S3 bucket
bucket = CloudBucket(
    bucket_name="my-data-bucket",
    mount_path="/data"
)

sandbox = Sandbox(volumes=[bucket])
Use cloud buckets for:
  • Sensitive data
  • Connecting existing object storage
  • Long-term data storage in your own infrastructure

​
Session Management

​
Timeout Configuration

Set timeouts to control costs: 
# Quick tasks (testing, simple scripts)
sandbox = Sandbox(keep_warm_seconds=1800)  # 30 minutes

# Development sessions
sandbox = Sandbox(keep_warm_seconds=3600)  # 1 hour

# Long-running tasks (training, processing)
sandbox = Sandbox(keep_warm_seconds=7200)  # 2 hours

# Manual termination only
sandbox = Sandbox(keep_warm_seconds=-1)
Start with shorter timeouts and increase as needed. You can always create a new sandbox if you need more time.

​
Manual vs Automatic Termination

# Auto-terminate after 1 hour
sandbox = Sandbox(keep_warm_seconds=3600)

# Manual termination only (you control when it stops)
sandbox = Sandbox(keep_warm_seconds=-1)
Use manual termination for:
  • Long-running training jobs
  • Collaborative development sessions
  • When you need to pause and resume work

​
Environment Variables and Secrets

​
Environment Variables

Pass configuration to your applications: 
sandbox = Sandbox(
    env={
        "DATABASE_URL": "postgresql://user:pass@host:5432/db",
        "API_KEY": "your-api-key",
        "DEBUG": "true",
        "ENVIRONMENT": "development"
    }
)
Environment variables are good for:
  • Keeping sensitive data out of your code
  • Configuring applications for different environments
  • Sharing configuration across team members

​
Secrets Management

You can attach secrets to your sandbox using Beam’s secret management system - they will be exposed as environment variables inside the Sandbox: 
sandbox = Sandbox(secrets=["OPENAI_API_KEY"])
You add secrets using the Beam CLI: 
$ beam secret create OPENAI_API_KEY ASIAY34FZKBOKMUTVV7A

=> Created secret with name: 'OPENAI_API_KEY'
Use secrets for:
  • Database passwords
  • API keys and tokens
  • Private keys and certificates

​
Best Practices

​
Start Small, Scale Up

# Start with minimal resources
sandbox = Sandbox(cpu=1.0, memory="1Gi")

# If you need more power, create a new sandbox
powerful_sandbox = Sandbox(cpu=4.0, memory="8Gi")
You only pay for what you use. Start small and scale up as needed.

​
Common Mistakes

​
Over-provisioning

# Don't do this for simple scripts
sandbox = Sandbox(cpu=8.0, memory="32Gi", gpu="A10G")  # Overkill!
Start with minimal resources and scale up as needed.

​
Including Unnecessary Packages

# Don't include packages you don't need
from beam import PythonVersion
image = Image(python_version=PythonVersion.Python311).add_python_packages([
    "flask", "django", "fastapi", "tornado", "bottle"  # Pick one!
])
Only include packages you actually use.

​
Long Timeouts for Short Tasks

# Don't set 2-hour timeout for 5-minute tasks
sandbox = Sandbox(keep_warm_seconds=7200)  # Wasteful!
Try to match timeout to expected task duration. You can always extend the timeout dynamically like so: 
sandbox = Sandbox(keep_warm_seconds=300)

# Do some stuff

sandbox.update_ttl(300) # Reset TTL back to 300 seconds

​
What’s Next?

Now that you understand configuration, let’s put it to work: