Pod provides a way to run serverless containers on the cloud. It enables you to quickly launch a container as an HTTPS server that you can access from a web browser.

Pods run in isolated containers, allowing you to run untrusted code safely from your host system.

This can be used for a variety of use cases, such as:

• Hosting GUIs, like Jupyter Notebooks, Streamlit or Reflex apps, and ComfyUI
• Testing code in an isolated environment as part of a CI/CD pipeline
• Securely executing code generated by LLMs

…and much more (if you’ve got a cool use case, let us know!)

​

Launching Cloud Containers

Containers can be launched programmatically through the Python SDK, or with the Beam CLI.

For example, the following code is used to launch a cloud-hosted Jupyter Notebook:

from beam import Image, Pod

notebook = Pod(
    image=Image(base_image="jupyter/base-notebook:latest"),
    ports=[8888],
    cpu=1,
    memory=1024,
    env={
        "NOTEBOOK_ARGS": "--ip=:: --NotebookApp.token='' --NotebookApp.notebook_dir=/tmp"
    },
    entrypoint=["start-notebook.py"],
)

nb = notebook.create()

print("✨ Container hosted at:", nb.url)

When this code is executed, Beam will launch a container and expose it as a publicly available HTTPS server:

$ python app.py

=> Building image
=> Using cached image
=> Syncing files
=> Creating container
=> Container created successfully ===> pod-2929b184-b445-4f23-abc6-7c4b151001da-ec86d9ac

✨ Container hosted at: https://2929b184-b445-4f23-abc6-7c4b151001da-8888.app.beam.cloud

​

Accessing Containers via HTTP

You can then enter this URL in the browser to interact with your hosted container instance:

​

Securely Executing Untrusted Code

Beam’s containers are launched in isolated environments from your host system, making it safe to execute untrusted or LLM-generated code.

​

Parameters

Pods can be heavily customized to fit your needs.

​

Using Custom Images

You can customize the container image using the Image object. This can be customized with Python packages, shell commands, Conda packages, and much more.

from beam import Image, Pod

pod = Pod(
    image=Image(base_image="jupyter/base-notebook:latest"),
    entrypoint=["start-notebook.py"],
)

​

Specifying Entry Points

An entry point is the command or script that will run when the container starts. You can interact with Pods using the CLI or the Python SDK.

from beam import Image, Pod

pod = Pod(
    image=Image(base_image="jupyter/base-notebook:latest"),
    entrypoint=["start-notebook.py"],
)

pod.create()

​

Passing Environment Variables

You can pass environment variables into your container for credentials or other parameters. Like entry points, environment variables can be defined in both the CLI or the Python SDK:

from beam import Image, Pod

Pod(
    image=Image(base_image="jupyter/base-notebook:latest"),
    env={"NOTEBOOK_ARGS": "--ip=:: --NotebookApp.token='' --NotebookApp.notebook_dir=/tmp"},
    entrypoint=["start-notebook.py"],
)

​

Deploying a Pod

Pods can be deployed as persistent endpoints using the beam deploy command.

from beam import Pod

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

beam deploy app.py:pod

​

Terminating a Pod

Pod instances can be terminated directly using the terminate() method.

Alternatively, you can terminate the container the Pod is running on by using the beam container stop <container-id> command.

from beam import Pod

# Initialize a pod
notebook = Pod()

# Launch the pod
notebook.create()

# Terminate the pod
notebook.terminate()

​

Lifecycle

​

Timeouts

Pods are serverless and automatically scale-to-zero.

By default, pods will be terminated after 10 minutes without any active connections to the hosted URL or until the process exits by itself. Making a connection request (i.e. accessing the URL in your browser) will keep the container alive until the timeout is reached.

You can set a custom timeout by passing the keep-warm-seconds parameter when creating a pod. By specifying -1, the pod will not spin down to due inactivity, and will remain up until either the entrypoint process exits, or you explicitly stop the container.

Keep Alive for 5 minutes

beam run --image jupyter/base-notebook:latest --keep-warm-seconds 300

Keep Alive Indefinitely

beam run --image jupyter/base-notebook:latest --keep-warm-seconds -1

​

List Running Pods

You can list all running Pods using the beam container list command.

$ beam container list

  ID                                                  Status    Stub ID                                Deployment ID   Scheduled At    Uptime
 ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  pod-58a38dba-8b7b-4db3-b002-436c6d9b4858-a613eecd   RUNNING   58a38dba-8b7b-4db3-b002-436c6d9b4858                   5 seconds ago   4 seconds

  1 items

You can kill any container by running beam container stop <container-id>.