Host a Web Service

There are three ways to serve HTTP on Beam: an ASGI app such as FastAPI (Hosting a Web Server), any Dockerfile or registry image (Deploy Containers), or a container defined in Python with Pod (Host a Web Service).

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:

Python

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.

Python

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.

Python

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:

Python

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.

When deploying a Pod, don’t forget to include the name field.

app.py

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

Pod URLs

Each exposed port gets its own URL, with the port number at the end of the hostname. The URL that beam deploy prints belongs to that one deploy:

◆ Exposed endpoints

    Port 8000: https://4f78aaae-f35c-4eb0-9236-cdd34509bad8-8000.app.beam.cloud

That URL changes every time you deploy, and stops working once its deploy is stopped. For a URL that always routes to the latest deploy, use the app name and ID instead:

https://[APP-NAME]-[APP-ID]-latest-[PORT].app.beam.cloud

https://[APP-NAME]-[APP-ID]-[PORT].app.beam.cloud also routes to the latest deploy, and -v[N]-[PORT] pins a version, as with endpoint versioning. Paths are passed through, so https://my-deployed-pod-9a65b5f-latest-8000.app.beam.cloud/docs reaches /docs in your container.

To look up the stable URL for a deployment, pass its ID from beam deployment list --format json to the deployment URL API:

curl 'https://app.beam.cloud/api/v1/deployment/[DEPLOYMENT-ID]/url' \
-H 'Authorization: Bearer [YOUR_AUTH_TOKEN]'

{ "url": "https://my-deployed-pod-9a65b5f-latest-8000.app.beam.cloud" }

Pods are public by default, so these URLs work without a token. If you set authorized=True, send an Authorization: Bearer header. You can also reach a deployed Pod by name at https://app.beam.cloud/pod/[APP-NAME]/latest/[PORT], which always requires a token.

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

There is no upper limit on the duration of a session.

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>.