Quickstart
Deploy an agent, chat with it, and call it from code. This takes about five minutes on the managed service at gateway.broods.app. To run Broods on your own AWS account instead, start with Self-hosting and come back here.
You need Bun 1.2+ or Node 22.15+, a Broods dashboard account, and a key for a model provider. This guide uses OpenAI.
1. Install
mkdir my-agents && cd my-agents
bun init -y
bun add broods ai
ai is the Vercel AI SDK. The broods types build on it. For the CLI alone, bun add -g broods or npm install -g broods is enough.
2. Add your model key
echo 'OPENAI_API_KEY="sk-..."' >> .env.local
3. Start the dev loop
bunx broods dev
The first run:
- Opens your browser to log in, if you have not yet.
- Asks for an organization, a project name, a stage and a service region. Press Enter to keep each default.
- Creates
broods/index.tswith a starter agent. - Pushes
OPENAI_API_KEYfrom.env.localto yourdevelopmentstage. - Syncs your resources and writes the runtime key to
.env.localasBROODS_API_KEY, and the stage's user token signing secret asBROODS_USER_TOKEN_SECRET. - Watches
broods/and live-tails warnings and errors.
✔ Created starter broods/
✔ Synced 2 resources to my-agents/development
✔ Wrote BROODS_API_KEY (bsk_…vK8s) to .env.local
✔ Wrote a new user token signing secret to BROODS_USER_TOKEN_SECRET in .env.local
The starter agent:
import { defineAgent, defineSandbox, env } from "broods";
// A Lambda sandbox: a fresh, ephemeral bash environment created per run.
export const lambdaSandbox = defineSandbox({
name: "lambda-sandbox",
provider: "lambda",
network: { mode: "deny-all" },
permissionMode: "bypass",
timeout: 60,
});
export const myAgent = defineAgent({
name: "my-agent",
provider: { openai: { apiKey: env("OPENAI_API_KEY") } },
model: { provider: "openai", modelId: "gpt-5.5" },
agent: { system: "You are a helpful assistant." },
sandboxes: [lambdaSandbox],
// Expose the public runtime endpoint (SSE/WebSocket) so the runtime key can
// reach this agent. Off by default: a private agent is only reachable via
// internal endpoints, channel webhooks or `broods run`.
publicAccess: true,
});
env("OPENAI_API_KEY") is a reference that the server resolves. The key never lands in your synced config. publicAccess: true lets the runtime key, which the SDK uses, reach this agent. broods run uses your login and works either way.
Leave broods dev running. Every save re-syncs.
4. Chat with it
In a second terminal:
bunx broods run my-agent "Write fib.py and run it"
This opens a chat in the terminal. Reasoning streams in, tool calls show as cards, and tools that need approval stop for y or n. Press Esc to leave. Redirect the output to a file to get plain text instead.
5. Call it from code
broods dev generates typed references in broods/_generated/:
import { BroodsClient, signUserToken } from "broods";
import { api } from "./broods/_generated/api";
// reads BROODS_API_KEY and BROODS_USER_TOKEN_SECRET from .env.local
const client = new BroodsClient({
userToken: await signUserToken({ userId: "me" }),
});
const result = await client.run(api.agents.myAgent, {
input: "What is the capital of France?",
});
console.log(result.text);
for await (const part of client.stream(api.agents.myAgent, {
input: "Tell me a story.",
})) {
if (part.type === "text-delta") process.stdout.write(part.text);
}
bun index.ts
A new agent requires a user token beside the runtime key. On a real site your server signs one per user, see Users behind the runtime key.
Other languages use the same endpoint over HTTP. See HTTP API.
6. Deploy to production
deploy does not push .env.local values, so set production secrets first:
bunx broods env set OPENAI_API_KEY --stage production
Then sync the same resources to your production stage once:
bunx broods deploy
The first deploy pins Production's region: eu-west-1 unless you pass --region. It cannot move afterwards. The first env set --stage production or deploy creates the Production stage, and the dashboard's stage menu then opens it directly instead of offering to initialize Production.
Check where you are pointed
A sync lands in an organization, a project and a stage. Run whoami to see all three before you write somewhere shared.
bunx broods whoami
Next
- Concepts explains how organizations, projects, stages, agents and keys fit together.
- Agents covers models, prompts, reasoning and structured output.
- Tools adds web search or an MCP server.
- Channels puts the agent in Slack or Telegram.
If your repo has CLAUDE.md, AGENTS.md, .claude/, .agent/ or .agents/, it already works with a coding agent, and broods dev also installs a Broods skill at .agents/skills/broods/ that teaches the agent the CLI and SDK. Your edits to it survive. Only broods init --force rewrites it.