Use with an agent

Beamd is designed for the way agents work: an agent spins up npm run dev, asks for a URL, and hands it back so a human (or another service) can review the result from anywhere. There are three ways an agent can drive Beamd, so pick by how the agent is built.

Three ways to drive it

Why the CLI is a first-class agent surface

MCP is the newest, most ergonomic option, but don't sleep on the CLI. Agents are fluent in command lines: there's an enormous amount of CLI usage in their training data, so beamd open 3000 --as api -d --json is something a model gets right zero-shot. Every command that matters takes --json and prints exactly one object, so the agent can parse the result deterministically:

beamd open 3000 --as api -d --json
# {"url":"https://api.beam.example.com", ...}

Use MCP when the agent speaks it. Reach for the CLI when it doesn't, or when you want the agent to script a multi-step flow.

Giving an agent credentials

An agent needs to know which edge and which token to use. Two clean options:

• A committed beamd.yaml pins the edge + scope + naming for the repo. It holds no token (safe to commit), so the agent inherits your login on your machine.
• A --config file with a workspace API key, for CI or a hosted agent that shouldn't use a human login. See Embed in your app and Auth & tokens.

Installing the skill

The quickest way to teach an agent Beamd is the Beamd skill. It covers the CLI workflow end to end: check the login, open a tunnel with --json, hand back the URL, target a team workspace, and close tunnels when the work is done.

npx skills add dynamismlabs/beamd

This uses the open skills installer, which supports Claude Code, Cursor, Codex and other agents that load skills. It installs into the current project by default. Add -g to install it for every project.

The skill is a single file, skills/beamd/SKILL.md in the CLI repo, so you can also copy it by hand into your agent's skills folder (for example .claude/skills/beamd/SKILL.md).

The skill uses your existing login, so run beamd login once first. For a team workspace, run beamd default <team>, or commit a beamd.yaml from beamd link --scope <team> so everyone on the repo lands in the same place.