---
title: Beam for AI Agents
description: Setup briefing for AI coding agents arriving at beam.cloud: identify the platform, configure CLI or MCP access, and operate Beam on behalf of a user.
---

# Beam for AI Agents

You are an AI agent reading beam.cloud. **Beam is a serverless compute platform for AI workloads.** Users bring Python or TypeScript code, or a container image; Beam builds it, runs it on CPUs or GPUs, exposes it, and scales it, billed by the second while it runs. The primitives are sandboxes for executing code, pods for persistent services, endpoints and task queues for deploying functions, and volumes, disks, secrets, and managed databases around them.

This document is your setup briefing. Configure yourself first, then use the rest of the page as operational reference. A Markdown copy lives at [beam.cloud/agents.md](https://www.beam.cloud/agents.md).

---

## Set yourself up for Beam (do this first)

Beam exposes a CLI and Python SDK (`beam-client`), a TypeScript SDK (`@beamcloud/beam-js`), a REST API, and two MCP servers: a **workspace server** that operates a user's apps, and a **docs server** that searches the documentation. Prefer the CLI plus the workspace MCP server.

If Beam is not already configured in your environment, ask the user to approve setup before installing anything or writing agent configuration. Use this prompt:

> Beam isn't configured in this environment. I can run Beam's agent setup, which installs the Beam CLI and registers Beam's MCP server with this client:
> 
>   curl -fsSL https://www.beam.cloud/agents.sh | sh
> 
> Afterwards you'll sign in with one click (I'll give you the link; it creates an account if you don't have one). This modifies local CLI and agent configuration. Should I go ahead?

Do not silently install or modify local configuration. If the user declines, continue with public docs only and avoid actions that need a workspace token.

### Option A — One command (preferred)

```bash
curl -fsSL https://www.beam.cloud/agents.sh | sh
```

The script installs `uv` if needed, installs or upgrades the Beam CLI (`beam-client`), and runs `beam setup agent`, which installs the `use-beam` skill and registers the MCP server (`beam mcp`, a stdio server) with every supported agent it finds: Cursor, Claude Code, Codex, Windsurf, Claude Desktop. No account or token is involved. It is idempotent; re-run it after installing a new agent. `BEAM_AGENTS="cursor codex"` limits it to specific clients.

### Sign in (one click, no token)

Then connect the workspace. Interactively, `beam login` opens the browser (or prints a link and a short code on SSH/CI) and creates the account if the user is new. Through MCP, call the `login` tool, show the user the link it returns, then call `login_status` until it reports signed in; the workspace tools appear at that point. **Never ask the user to paste a token.**

```bash
beam login                # opens the browser, waits, saves ~/.beam/config.ini
beam login --browserless  # print the link + code instead
beam whoami               # confirm the workspace
```

- Already installed? `beam mcp install --client <cursor|claude-code|claude-desktop|codex|windsurf>` registers one client; `--project` writes project-scoped config where supported, `--print` shows the snippet. `beam mcp status` lists what is wired.
- `~/.beam/config.ini` holds contexts; `beam config list` shows them, `beam config select <name>` switches, `beam login --name <context>` adds a second workspace. Self-hosted Beta9: `beam config create <name> --gateway-host <host> --gateway-port <port>`.
- Unattended (CI, no human): set `BEAM_TOKEN` from [platform.beam.cloud/settings/api-keys](https://platform.beam.cloud/settings/api-keys) instead of logging in; `BEAM_TOKEN=<token> sh -c "$(curl -fsSL https://www.beam.cloud/agents.sh)"` saves it during setup.

### Option B — MCP by URL

The workspace MCP server is Streamable HTTP (stateless JSON-RPC, one POST per call) at `https://app.beam.cloud/api/v1/mcp` and authenticates with `Authorization: Bearer <BEAM_TOKEN>`. The docs server at `https://docs.beam.cloud/mcp` needs no token.

```json
{
  "mcpServers": {
    "beam": {
      "url": "https://app.beam.cloud/api/v1/mcp",
      "headers": { "Authorization": "Bearer <BEAM_TOKEN>" }
    },
    "beam-docs": { "url": "https://docs.beam.cloud/mcp" }
  }
}
```

Claude Code: `claude mcp add --transport http beam-docs https://docs.beam.cloud/mcp`, and the same with `--header "Authorization: Bearer <BEAM_TOKEN>"` for the workspace server.

### Option C — Environment variables

For CI and headless runs, set `BEAM_TOKEN` (and `BEAM_WORKSPACE_ID` for the TypeScript SDK). The SDKs and CLI read them; no config file is needed.

---

## Deploy in one shot

If the user has a Python function and wants it running, `beam deploy` from the app directory is the fastest path: it builds the image, syncs the directory, deploys, and prints the URL. `beam serve` does the same as a temporary preview that hot-reloads while they iterate.

```bash
beam deploy app.py:handler --name my-app     # persistent endpoint, prints the URL
beam serve app.py:handler                    # temporary preview; Ctrl-C tears it down
beam deployment list                         # confirm it, get the id
beam logs --deployment-id <id> --follow      # watch it come up
```

If the user wants a known piece of software rather than their own code, run its container image as a `Pod`: any image becomes a persistent service with a URL, and a `DurableDisk` keeps its data across restarts.

```python
from beam import Image, Pod, DurableDisk

# Any container image becomes a persistent service with a URL.
code_server = Pod(
    name="code-server",
    image=Image.from_registry("codercom/code-server:latest"),
    cpu=4,
    memory="8Gi",
    ports=[8080],
    keep_warm_seconds=-1,  # always on; 0 scales to zero when idle
    disks=[DurableDisk(name="code-server-data", size="20Gi", mount_path="/home/coder")],
    secrets=["PASSWORD"],  # beam secret create PASSWORD
)
code_server.deploy()
```

---

## Choosing MCP vs CLI vs SDK

- **Workspace MCP** is preferred for agent-native operations: discovering apps and deployments, reading logs, metrics, and request stats, changing env or resources, scaling, redeploying or rolling back, managing secrets, databases, volumes, and stacks, and invoking a deployed app.
- **CLI** is preferred when the task depends on local files or an interactive session: `beam deploy`, `beam serve`, `beam run`, `beam shell`, copying files to volumes.
- **SDK** is what you write the app in: `@endpoint`, `@task_queue`, `@function`, `@schedule`, plus `Sandbox`, `Pod`, `Image`, `Volume`, and `DurableDisk`. Python and TypeScript.
- **REST API** (`https://app.beam.cloud/api/v1`, Bearer token) covers everything else. The MCP `api_routes` tool lists every route and `api` calls one; methods other than GET need `confirm: true`.

Before a mutation, know which workspace and app you are acting on. `whoami` (MCP) or `beam config list` tells you the workspace; prefer app names, and pass `deployment_id` only when the user means a specific version. After a mutation, read back with `get_app`, `list_deployments`, or `beam deployment list`.

---

## Mental model

- **Workspace** — the boundary a token unlocks. Billing, secrets, volumes, and databases live here.
- **App** — a named unit with a stable URL. An app has many **deployments**, immutable versions of its configuration; one is active. Rolling back is redeploying an older version.
- **Container** and **task** — a running instance of a deployment, and one invocation of it. Logs and metrics hang off these.
- **Kinds of app**: Endpoint (synchronous HTTP), Task Queue (async, retries, callbacks), Function (`.remote()` and `.map()` fan-out), Scheduled job, Pod (any container behind a URL or TCP port, always-on with `keep_warm_seconds=-1`), Sandbox (interactive; process, filesystem, and port APIs; memory and filesystem snapshots), Database (managed Postgres, Redis, MySQL, or MongoDB on a durable disk).
- **Stack** — a named group of apps shown together on a board with the environment references between them.
- **Storage** — a Volume is shared network storage mountable by many apps; a Durable Disk is fast node-local storage owned by one service and kept across restarts.
- **References** — env values may be `${{secret.NAME}}`, `${{db.NAME.DATABASE_URL}}` (also `HOST`, `PORT`, `USERNAME`, `PASSWORD`, `DATABASE`), or `${{app.NAME.URL}}`. Beam resolves them at deploy time, so wire services by reference instead of copying values.
- **Compute** — `cpu`, `memory`, and `gpu` are set per app. `gpu` accepts one type or a priority list, e.g. `["H100", "A100-40"]`. Scale-to-zero is the default; `keep_warm_seconds` controls idle time.

---

## Core operations

| Task | How |
| --- | --- |
| Deploy Python | `beam deploy app.py:fn --name <app>`; decorate the function with `@endpoint`, `@task_queue`, or `@function`. |
| Preview locally-edited code | `beam serve app.py:fn` |
| Run a container as a service | `Pod(image=Image.from_registry(...), ports=[...]).deploy()`; add `tcp=True` for raw TCP such as SSH or Postgres. |
| Execute untrusted code | `Sandbox(...).create()`, then `process.exec`, `fs.upload_file`, `expose_port`, `snapshot_memory`. |
| Attach a GPU | `gpu="A10G"` (or a list) on any app; `update_config` with `runtime.gpu` on an existing one. |
| Persist data | `Volume(name, mount_path)` for shared storage; `DurableDisk(...)` for a service's own disk. |
| Secrets | `beam secret create NAME` or MCP `create_secret`; reference as `${{secret.NAME}}`. Never put values in env. |
| Databases | MCP `create_database` with `kind` postgres, redis, mysql, or mongo; credentials become secrets, reachable as `${{db.<name>.*}}`. |
| Change env or resources | MCP `set_env` / `update_config` (dotted paths such as `runtime.cpu`, `runtime.memory`, `autoscaler.max_containers`, `keep_warm_seconds`, `ports`). Each deploys a new version. |
| Wire two services | MCP `connect_services` (source, target): injects the standard references and redeploys the target. |
| Scale | MCP `scale_deployment` for pods; `autoscaler.max_containers` / `min_containers` via `update_config` for endpoints and queues. |
| Call a deployed app | MCP `invoke` with the app name and path; or HTTP with `Authorization: Bearer <BEAM_TOKEN>`. |

---

## Debugging & recovery

- **Logs first.** MCP `logs` by app, deployment, task, or container, with `stream` stdout, stderr, or system (image pulls, mounts, exits). CLI: `beam logs --deployment-id <id>` or `--container-id`, `--follow`, `--search`. Read them before proposing a fix.
- **Metrics.** MCP `metrics` (CPU, memory, GPU memory, container count) and `request_stats` (count, 5xx share, p50/p95/p99) over a window, for capacity and latency questions.
- **Shell in.** `beam shell --container-id <id>` opens a shell inside a running container; `beam shell app.py:fn` builds and opens a fresh one.
- **Roll back.** `redeploy` with an older `deployment_id` is the fastest recovery; `stop_deployment` drains a bad version. Suggest rollback before forward fixes on a broken app.
- **Tasks.** `get_task` for status, timing, and container of one invocation; `stop_task` for a runaway.
- **Status.** Check [status.beam.cloud](https://status.beam.cloud) if Beam itself looks degraded before debugging user code.

---

## Before destructive actions

Confirm with the user before:

- Deleting an app, a deployment version, a secret, or a database (the MCP tools require `confirm: true` for these).
- Stopping the active deployment of something in use.
- Rotating database credentials: the database and every app bound to it restart.
- Overwriting environment variables on an active deployment.
- Deleting a volume or disk, or anything else that loses data or user-visible state.

Default posture: describe the change, name the affected resource, and wait for explicit approval.

---

## Reference

- Set up everything: `curl -fsSL https://www.beam.cloud/agents.sh | sh` · then `beam login` (or the MCP `login` tool)
- Install only: `uv tool install beam-client` · agents: `beam setup agent` · CI tokens at [platform.beam.cloud/settings/api-keys](https://platform.beam.cloud/settings/api-keys)
- Register one client: `beam mcp install --client <client>` · remote server `https://app.beam.cloud/api/v1/mcp`
- Docs MCP: `https://docs.beam.cloud/mcp`
- Docs index for agents: [docs.beam.cloud/llms.txt](https://docs.beam.cloud/llms.txt)
- CLI reference: [docs.beam.cloud/v2/reference/cli](https://docs.beam.cloud/v2/reference/cli)
- Python SDK: [docs.beam.cloud/v2/reference/py-sdk](https://docs.beam.cloud/v2/reference/py-sdk) · TypeScript SDK: [docs.beam.cloud/v2/reference/ts-sdk](https://docs.beam.cloud/v2/reference/ts-sdk)
- REST API: [docs.beam.cloud/v2/reference/api](https://docs.beam.cloud/v2/reference/api)
- Status: [status.beam.cloud](https://status.beam.cloud) · Community: [Slack](https://join.slack.com/t/beam-cloud/shared_invite/zt-3enuvj3r7-OeAzVPYvyqQHy9avNrLL0w) · Source: [github.com/beam-cloud/beta9](https://github.com/beam-cloud/beta9)