Quickstart

Run your first function on Beam in a few minutes. Follow For Humans if you’re setting things up by hand, or For Agents if you’re a coding agent working on a user’s behalf.

For Humans

Set up

Create a free account at platform.beam.cloud — you’ll get $30 in free credit. Copy your token from Settings → API Keys, then install the SDK and authenticate:

uv tool install beam-client

beam configure default --token YOUR_TOKEN

This saves your credentials to ~/.beam/config.ini — without them, the next command will stop and prompt you instead of running your code. See Installation for Homebrew, Windows, and the TypeScript SDK.

Run a function in the cloud

The simplest way to run code on Beam is to add the @function decorator to any Python function. Save this to app.py:

app.py

from beam import function


@function(cpu=1, memory="1Gi")
def square(x: int):
    return {"result": x**2}


if __name__ == "__main__":
    print(square.remote(x=12))

Run it like any other Python file:

python app.py

Beam syncs your code, launches a container, runs the function, and streams the result back to your shell:

=> Building image
=> Using cached image
=> Syncing files
=> Files synced
=> Running function: <app:square>
{'result': 144}
=> Function complete

The container spins up in seconds, runs your code, and shuts itself down. No idle costs, no infrastructure to clean up.

Deploy a web endpoint

To turn your code into a live web API, swap @function for @endpoint. We’ll include numpy in the image to show how easily you can add Python packages.

Image() defines your container environment. You can add Python packages, system dependencies, or even custom Dockerfiles.
@endpoint turns your function into a real, live web API that runs in the cloud.

app.py

from beam import endpoint, Image


@endpoint(
    name="quickstart",
    cpu=1,
    memory="1Gi",
    image=Image().add_python_packages(["numpy"]),
)
def predict(**inputs):
    x = inputs.get("x", 256)
    return {"result": x**2}

Deploy it to the cloud:

beam deploy app.py:predict

Call the API

When the deploy finishes, Beam prints your endpoint URL along with a ready-to-run curl command. Replace YOUR_TOKEN with your token and use the URL from your deploy output:

curl -X POST 'https://app.beam.cloud/endpoint/quickstart' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"x": 12}'

import { beamOpts, Deployments } from "@beamcloud/beam-js";

beamOpts.token = process.env.BEAM_TOKEN!;
beamOpts.workspaceId = process.env.BEAM_WORKSPACE_ID!;

const deployment = await Deployments.get({
  name: "quickstart",
  stubType: "endpoint/deployment",
});

const response = await deployment.call({ x: 12 });
console.log(response);

Either way, you’ll get back:

{ "result": 144 }

For Agents

For coding agents setting up Beam on a user’s behalf. There’s no programmatic sign-up: ask the user for a token from Settings → API Keys. Everything else is non-interactive — using the same app.py examples above:

uv tool install beam-client

# saves credentials to ~/.beam/config.ini; in ephemeral environments and CI,
# exporting BEAM_TOKEN works without any config file
beam configure default --token "$BEAM_TOKEN"

python app.py                # run a @function remotely; prints the result
beam deploy app.py:predict   # deploy an @endpoint; prints the endpoint URL
beam deployment list         # confirm the deployment is live

The docs are machine-readable: fetch llms.txt for an index of every page, append .md to any docs URL for raw Markdown, or connect the docs MCP server at https://docs.beam.cloud/mcp. See Using Beam Docs with AI Tools.

What Next?

Here are some other things you can try:

Start Here

Customizing Container Images

Managing Data

Scaling & Performance

Sandboxes

Endpoints and Web Servers

Task Queues

One-Off Functions

Hosting Containers

Advanced Topics

Self-Hosting

Resources

Security

For Humans

For Agents

What Next?

​For Humans

​For Agents

​What Next?

For Humans

For Agents

What Next?