Sandbox Configuration

Resources, images, storage, secrets, and lifetime

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 the API_KEY workspace secret before starting this example. Use secrets for credentials and env for nonsecret configuration. A plaintext value in a source file remains in that file even when passed as an environment variable.

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.