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.

CPU capacity tier

CPU workloads can choose a capacity tier:

Tier	Behavior
Spot	Uses spare capacity and may be interrupted with 30 seconds’ notice.
Shared	Shared vCPUs, not preemptible. Up to 8 vCPU / 16 GiB.
Performance	No CPU sharing, not preemptible.

See current rates. New accounts default to Performance, and workloads opt into Shared or Spot; omitting the tier keeps an existing account’s default. When Performance capacity is full, Performance workloads may run on Shared hosts, still with no CPU sharing. GPU workloads and private pools keep their own pricing and placement. Tiered VMs and VM-backed sandboxes require at least 1 vCPU / 1 GiB. Ordinary containers support fractional resources. Requires beam-client >= 0.2.236 or @beamcloud/beam-js >= 1.1.7. Python: Sandbox(cpu_tier="shared", cpu=2, memory="2Gi"). JavaScript: new Sandbox({ name: "dev", cpuTier: "shared", cpu: 2, memory: "2Gi" }). Spot sandboxes terminate when reclaimed. Persistent mounts survive; process state and temporary files do not. VM-backed sandboxes use at least 1 vCPU / 1 GiB; omitted memory defaults to 1 GiB for a tiered VM-backed sandbox. Explicit requests below the minimum are rejected.

Persistent Storage

Storage is not billed yet. Planned pricing is $0.0001 per GB-hour of data stored, with no free allowance.This will use the same usage credits as compute and cover retained VM disk, volume, and snapshot data, including while compute is stopped. Empty disk capacity, shared base images, and internal copies are excluded. 1 GB = 1 billion bytes.

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

Virtual Machines

Sandboxes

Inference

Building Blocks

Container Images

Data and Storage

Scaling

Operations

Run in Your Cloud

Advanced Topics

Resources

Security

Sandbox Configuration

CPU capacity tier

Persistent Storage

Lifetime

Other capabilities

​CPU capacity tier

​Persistent Storage

​Lifetime

​Other capabilities

CPU capacity tier

Persistent Storage

Lifetime

Other capabilities