Skip to main content

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:

  1. Opens your browser to log in, if you have not yet.
  2. Asks for an organization, a project name, a stage and a service region. Press Enter to keep each default.
  3. Creates broods/index.ts with a starter agent.
  4. Pushes OPENAI_API_KEY from .env.local to your development stage.
  5. Syncs your resources and writes the runtime key to .env.local as BROODS_API_KEY, and the stage's user token signing secret as BROODS_USER_TOKEN_SECRET.
  6. 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:

broods/index.ts
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/:

index.ts
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.