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

For agents that use installable skills, add the Beamd skill (via your skills tool) or drop in the raw skill file, and point it at your edge with a .beamd or env. The skill is a thin wrapper over the same CLI commands documented here.