Pod provides a way to run arbitrary code on Beam. It’s an abstraction that lets you deploy a serverless container as a service, without the need to refactor your code to Beam’s Pythonic syntax.

This is especially useful when you want to bring your own container image or host generic webservers on Beam. It can be used for a variety of use cases, such as:

• Running arbitrary code in a serverless container.
• Hosting Jupyter Notebooks and Streamlit apps.
• Executing untrusted user code in a secure environment.
• Running a test suite in a CI/CD pipeline on a remote container.

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

​

Running Arbitrary Code

You can run arbitrary code inline by specifying a container image, environment variables, and entry point directly from the command line.

​

Jupyter Notebooks

For example, the following command spins up a Jupyter notebook server on Beam:

beam run --image jupyter/base-notebook:latest --ports 8888 \
  --env NOTEBOOK_ARGS="--ip=:: --NotebookApp.token='' --NotebookApp.notebook_dir=/tmp" \
  --entrypoint "start-notebook.py"

When you run this command, Beam will build the container image, sync the files, and start the container. It will then print the URL of the notebook server to the console.

curl -X POST 'https://15fba0c6-3fe8-408e-a0f8-c99cf166dcc9-8888.app.beam.cloud' \
-H 'Connection: keep-alive' \
-H 'Content-Type: application/json' \
-d '{}'

​

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"],
)

​

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()

​

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

​

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