Core Concepts

How Beam Works

Beam packages your code into a container and runs it on compute in the cloud. Beam’s 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.

The examples below use the Python SDK, which provides Beam’s decorator programming model. The TypeScript SDK offers programmatic access for creating sandboxes and calling deployed endpoints.

Sandboxes

A sandbox is a computer for an agent: a container you drive from code to start processes, read and write files, expose ports, and snapshot its filesystem or memory to fork it. Use sandboxes to give agents a machine to work in, and for development environments and RL rollouts. 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

Sandboxes

Virtual machines

Inference

Building Blocks

Container Images

Data and Storage

Scaling

Operations

Run in Your Cloud

Advanced Topics

Resources

Security

Core Concepts

How Beam Works

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

​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

Sandboxes

Functions

Endpoints

Apps, deployments, and containers

Web Services