Core Concepts

How Beam Works

Beam runs three kinds of compute in one workspace, with shared secrets, storage, and billing:

Virtual machines are persistent Linux machines. You create them by name, and they keep their disk until you remove them.
Sandboxes are disposable environments that your code creates at runtime, uses, and terminates.
Deployed apps are functions, endpoints, task queues, and pods. Beam packages your code or image into a container, scales it with traffic, and can scale it to zero.

Beam’s serverless runtime is powered by the open-source Beta9 orchestrator. Serverless containers scale within your autoscaler settings and workspace limits. Reserved machines and always-on configurations have different lifecycles; see pricing.

Most examples below use the CLI or the Python SDK, which provides Beam’s decorator programming model. The JavaScript and TypeScript SDK creates and operates VMs and sandboxes and calls deployed endpoints.

Virtual Machines

A VM is a persistent computer for you or your agent: a named Linux machine with its own kernel, systemd, SSH, and a durable root disk. Installed packages, files, and services survive a stop and start, and pausing saves RAM and running processes too. Use VMs for coding-agent dev boxes, desktop automation, and agents that keep state between sessions. Learn more about VMs.

beam vm new devbox
beam vm exec devbox -- uname -a

# Pause after five idle minutes; wake on the next request
beam vm update devbox --ttl 300 --idle-action pause --auto-resume

A VM keeps running until you stop, pause, or remove it, or until its idle timeout puts it to sleep. VMs run on CPUs; for GPU work, use a sandbox or a deployed app. Use a VM when the environment should outlive the task, as with a dev box, a desktop, or an agent that picks up where it left off. Use a sandbox when each task should start clean and be thrown away, when you fan out many short-lived copies from one snapshot, or when the code needs a GPU. The comparison table covers the differences in lifecycle, storage, and networking.

Sandboxes

A sandbox is a disposable environment for running code: a container your code creates at runtime to start processes, read and write files, expose ports, and snapshot its filesystem or memory to fork it. Use sandboxes for untrusted or agent-generated code, RL rollouts, and short-lived GPU tasks. Learn more about Sandboxes.

from beam import Sandbox

sb = Sandbox(cpu=1, memory="1Gi").create()
print(sb.process.run_code("print('hello')").stdout)

snapshot_id = sb.snapshot_memory()  # fork it later with create_from_memory_snapshot()
sb.terminate()

Unlike endpoints and task queues, a sandbox isn’t deployed. Your code creates it at runtime and terminates it when it’s done, or the sandbox’s TTL expires.

Functions

You can run functions on the cloud, either once, or on a schedule. Learn more about Functions.

Functions

One-off Python functions, like training runs, scraping, or batch jobs.

from beam import function

@function()
def handler():
    return {}

if __name__ == "__main__":
    # Runs locally
    handler.local()
    # Runs on the cloud
    handler.remote()

Scheduled Jobs

Functions that run based on a schedule you specify.

from beam import schedule

@schedule(when="0 0 * * *")
def handler():
    return {}

if __name__ == "__main__":
    # Runs locally
    handler.local()
    # Runs on the cloud
    handler.remote()

Run Your Function

You’ll run your functions like a normal Python function: python app.py. Even though it feels like the code is running locally, it’s running on a container in the cloud.

Endpoints

You can also deploy synchronous and asynchronous web endpoints. Learn more about Endpoints and Task Queues. To call a model without deploying one, use hosted models.

Endpoints

Synchronous REST API endpoints with a configurable request timeout.

from beam import endpoint

@endpoint(name="quickstart")
def handler():
  return {}

Task Queues

Asynchronous REST API endpoints, for heavier tasks that take a long time to run.

from beam import task_queue

@task_queue(name="quickstart")
def handler():
  print(48393 * 39383)

Testing Your Code (Optional)

Beam provides a temporary cloud environment to test your code.
These environments hot-reload with your code changes. You can test your workflow end-to-end before deploying to production.

beam serve app.py:handler

Deploying to Production

When you’re ready to deploy a persistent endpoint, you’ll use beam deploy:

beam deploy app.py:handler

A schedule starts recurring execution after you deploy it with beam deploy app.py:handler; calling .remote() runs one invocation. Cron schedules use UTC.

Apps, deployments, and containers

An app groups related versions. A deployment is a version of a workload’s code and configuration. A container is a running instance of that version; an active deployment can have zero containers while idle. A task records an invocation. A stub ID identifies a workload configuration and is distinct from the deployment and container IDs. Stacks group apps. References connect their environment variables to database credentials, secrets, or another app’s URL. Databases run as stateful services with durable disks.

Web Services

You can also bring your own container and host web services, like Jupyter Notebooks, Node.js apps, and much more. Learn more about Pods.

Pods

Run a container with HTTP or TCP ingress, or without ports for background work. For Dockerfiles and registry images, start with the container guide.

from beam import Pod

pod = Pod(
  name="my-pod",
  cpu=2,
  memory="1Gi",
  ports=[8000],
  entrypoint=["python", "-m", "http.server", "--bind", "::", "8000"],
)

# Run the container as an API
pod.deploy()

Start Here

Virtual Machines

Sandboxes

Inference

Building Blocks

Container Images

Data and Storage

Scaling

Operations

Run in Your Cloud

Advanced Topics

Resources

Security

Core Concepts

How Beam Works

Virtual Machines

Sandboxes

Functions

Functions

Scheduled Jobs

Run Your Function

Endpoints

Endpoints

Task Queues

Testing Your Code (Optional)

Deploying to Production

Apps, deployments, and containers

Web Services

Pods

​How Beam Works

​Virtual Machines

​Sandboxes

​Functions

Functions

Scheduled Jobs

Run Your Function

​Endpoints

Endpoints

Task Queues

Testing Your Code (Optional)

Deploying to Production

​Apps, deployments, and containers

​Web Services

Pods

How Beam Works

Virtual Machines

Sandboxes

Functions

Endpoints

Apps, deployments, and containers

Web Services