You can specify exactly what resources and environment you need, similar to any other Beam container. You control CPU, memory, GPU, Python packages, and more. Here’s how to configure it for a few different use cases.

​
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

​
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 environmental variables inside the Sandbox:

sandbox = Sandbox(secrets=["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
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: