Sandbox Configuration

The Python Sandbox defaults to 1 CPU, 128 MiB memory, Python 3.11, and a 600-second lifetime. Increase memory for package installation, browsers, or data processing.

from beam import Image, Sandbox

sandbox = Sandbox(
    cpu=2,
    memory="2Gi",
    image=Image(python_version="python3.11").add_python_packages(["requests"]),
    keep_warm_seconds=1800,
    env={"APP_ENV": "development"},
    secrets=["API_KEY"],
)

Create API_KEY with its approved credential hosts before starting this example:

beam secret create API_KEY "$REAL_API_KEY" --host api.example.com

Runtime secrets receive placeholders, substituted only in HTTPS headers to approved hosts. Existing secrets need host rules before binding. Use env for nonsecret configuration; manually passing a real key through env or a source file remains plaintext. Sandboxes do not inherit your workspace token. Explicit BETA9_TOKEN or BEAM_TOKEN secret bindings are plaintext opt-ins. See networking for credential-host and allowlist interactions. Add gpu, gpu_count, or pool for workloads that need suitable GPU capacity or a compute pool. Requesting a GPU does not install your application’s CUDA libraries; include those in the image.

Persistent Storage

Storage	Use
Sandbox filesystem	Temporary files; capture an image explicitly if you need a reusable filesystem
Volume	Shared files, datasets, model caches
CloudBucket	An existing S3-compatible bucket
DurableDisk	Single-writer state such as databases

from beam import CloudBucket, CloudBucketConfig, DurableDisk, Sandbox, Volume

sandbox = Sandbox(
    volumes=[
        Volume(name="documents", mount_path="/documents"),
        CloudBucket(
            name="my-data-bucket",
            mount_path="/bucket",
            config=CloudBucketConfig(
                access_key="AWS_ACCESS_KEY_ID",
                secret_key="AWS_SECRET_ACCESS_KEY",
                read_only=True,
            ),
        ),
    ],
    disks=[DurableDisk(name="workspace", size="10Gi", mount_path="/data")],
)

The bucket configuration’s access and secret key fields are Beam secret names, not plaintext credentials. Create those secrets and use a bucket your credentials can access. A durable disk has one writable attachment at a time.

Lifetime

keep_warm_seconds is the sandbox’s TTL, not an idle timeout that every command automatically resets. Use -1 for a sandbox that you will terminate explicitly. Running processes do not make a finite TTL unlimited.

from beam import Sandbox

sb = Sandbox(keep_warm_seconds=300).create()
try:
    sb.update_ttl(600)  # Reset the remaining TTL to 600 seconds.
    print(sb.process.run_code("print('hello')").stdout)
finally:
    sb.terminate()

Save the sandbox ID if you need to reconnect. Connecting to an existing sandbox does not create a replacement if it has already terminated.

Other capabilities

Use network controls for outbound restrictions and exposing ports, snapshots for restoring state, and Docker for nested container workloads. Exposed sandbox URLs are public; implement authentication in a service before exposing sensitive functionality. See the Python SDK reference for sandbox methods.

Start Here

Sandboxes

Virtual machines

Inference

Building Blocks

Container Images

Data and Storage

Scaling

Operations

Run in Your Cloud

Advanced Topics

Resources

Security

Sandbox Configuration

Persistent Storage

Lifetime

Other capabilities

​Persistent Storage

​Lifetime

​Other capabilities

Persistent Storage

Lifetime

Other capabilities