Configuration

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)
sb = sandbox.create()

# Do some stuff

sb.update_ttl(300)  # Reset the TTL back to 300 seconds

What’s Next?

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

Process Management: Run code and commands in your configured environment
File System Operations: Upload, download, and manage files
Networking: Deploy web services and expose them to the internet
Examples: See real-world configurations in action

Start Here

Customizing Container Images

Managing Data

Scaling & Performance

Sandboxes

Endpoints and Web Servers

Task Queues

One-Off Functions

Hosting Containers

Advanced Topics

Self-Hosting

Resources

Security

Configuration

Basic

Advanced compute settings

Customize your environment

Persistent Storage

Distributed Storage Volumes

Cloud Buckets

Session Management

Timeout Configuration

Manual vs Automatic Termination

Environment Variables and Secrets

Environment Variables

Secrets Management

Best Practices

Start Small, Scale Up

Common Mistakes

Over-provisioning

Including Unnecessary Packages

Long Timeouts for Short Tasks

What’s Next?

​Basic

​Advanced compute settings

​Customize your environment

​Persistent Storage

​Distributed Storage Volumes

​Cloud Buckets

​Session Management

​Timeout Configuration

​Manual vs Automatic Termination

​Environment Variables and Secrets

​Environment Variables

​Secrets Management

​Best Practices

​Start Small, Scale Up

​Common Mistakes

​Over-provisioning

​Including Unnecessary Packages

​Long Timeouts for Short Tasks

​What’s Next?

Basic

Advanced compute settings

Customize your environment

Persistent Storage

Distributed Storage Volumes

Cloud Buckets

Session Management

Timeout Configuration

Manual vs Automatic Termination

Environment Variables and Secrets

Environment Variables

Secrets Management

Best Practices

Start Small, Scale Up

Common Mistakes

Over-provisioning

Including Unnecessary Packages

Long Timeouts for Short Tasks

What’s Next?