Overview

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 use Beam’s traditional Pythonic syntax.

This is especially useful when you want to bring your own container image or host generic webservers on Beam.

​

Running Arbitrary Code

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

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=0.0.0.0 --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 '{}'

​

Exposing Ports

You can expose ports to the outside world by specifying the ports you want to expose in the ports parameter.

ports accepts a list, so you can expose multiple ports too.

from beam import Image, Pod

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

​

Specifying Entry Points

An entry point is the command or script that the container runs when it starts. In Beam, you can interact with Pods using the CLI or the Python SDK.

​

CLI

Use the --entrypoint flag with the beam run command.

beam run \
  --image jupyter/base-notebook:latest \
  --entrypoint "start-notebook.py"

​

Python SDK

Use the entrypoint parameter in your Pod definition.

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:

​

CLI

Use the --env flag with beam run.

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

​

Python SDK

Use the env parameter in your Pod definition.

from beam import Image, Pod

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

​

Summary

Using Pod on Beam:

• Allows you to run arbitrary code in a serverless container.
• Supports both CLI (through beam run) and the Python SDK (through Pod objects).
• Makes it easy to specify entry points and environment variables to configure your workload.
• Provides logs and a unique URL so you can access your running service (like a Jupyter notebook).

Here’s an end-to-end example of how to run a Jupyter notebook server on Beam using the Python SDK:

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=0.0.0.0 --NotebookApp.token='' --NotebookApp.notebook_dir=/tmp"
    },
    entrypoint=["start-notebook.py"],
)

res = notebook.create()

print("✨ Notebook hosted at:", res.url)

You can run this command directly as a Python script.

python jupyter-server.py

Running this command will print the URL of the notebook server to the console.

=> Building image
=> Creating container
=> Container created successfully ===> pod-15fba0c6-3fe8-408e-a0f8-c99cf166dcc9-97b6207e
=> Invocation details

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

✨ Notebook hosted at: https://15fba0c6-3fe8-408e-a0f8-c99cf166dcc9-8888.app.beam.cloud