Quickstart

Set up a relay, schedule, AI agent, and parallel routing. Pick whichever surface you want to drive it from.

New to beeps? Read Core Concepts first to understand how the pieces fit together.

Prerequisites

• A beeps account.
• For the SDK and MCP paths (and CI): an access token from Settings → Access Tokens (looks like bat_xxxxxxxx). The CLI can mint its own via beeps login.

Pick your surface

The same eight-step setup is available three ways. The CLI is the fastest path to your first alert. Pick it unless you have a reason not to.

CLI

Install + authenticate:

npm install -g @beepsdev/cli
beeps login

beeps login opens your browser; approve the code, pick your organization, and the CLI saves an org-scoped token to ~/.config/beeps/config.json. In CI (or if you prefer), skip it and set BEEPS_ACCESS_TOKEN with a token from Settings → Access Tokens — the env var takes precedence over the saved login.

Every command below captures the ids it creates into shell variables (using --json plus jq), so you can paste the whole flow top to bottom without copying ids around.

1. Create a relay

RELAY_ID=$(beeps relay create --name "production relay" \
  --external-key production::relay \
  --description "routes critical production incidents" \
  --json | jq -r '.id')

WEBHOOK_URL="https://hooks.beeps.dev/$(beeps webhook list --relay-id "$RELAY_ID" --json | jq -r '.[0].webhookKey')"

Creating a relay auto-generates a webhook; beeps webhook list is where its key lives. $WEBHOOK_URL is what you'll POST alerts to in step 8.

2. Create an on-call schedule

SCHEDULE_ID=$(beeps schedule create \
  --name "Primary On-Call" \
  --relay-id "$RELAY_ID" \
  --type weekly \
  --handoff-day monday \
  --handoff-time 09:00 \
  --external-key "primary::schedule" \
  --json | jq -r '.id')

startAt is omitted on purpose. beeps defaults it to now, so you can test alerts immediately.

3. Add team members

beeps schedule add-member --schedule-id "$SCHEDULE_ID" --email alice@example.com
beeps schedule add-member --schedule-id "$SCHEDULE_ID" --email bob@example.com

Members rotate in the order they're added.

4. Contact methods (one-time, in the dashboard)

Your signup email is auto-added as a verified contact method. To add SMS or another email, go to Settings → Profile in the dashboard. SMS requires verification via a confirmation text.

Stopping here is fine

If you don't need AI agents, skip to step 7 and create only the schedule_notify rule (the humans group).

5. Set up an AI agent integration

Create a Cursor API key at Dashboard → API Keys. For teams, prefer a service account key so the integration isn't tied to one person's account. beeps validates the key against Cursor's API when you create the integration, so a bad key fails here instead of on your first alert.

export CURSOR_API_KEY="cursor_api_key_here"
INTEGRATION_ID=$(beeps integration create \
  --provider cursor \
  --name "Cursor Agent" \
  --api-key-env CURSOR_API_KEY \
  --json | jq -r '.id')

6. Create parallel relay rules

# AI agent rule
beeps relay rule create --relay-id "$RELAY_ID" \
  --name "AI Agent Auto-Triage" \
  --rule-type agent \
  --group agents \
  --order 1 \
  --external-key agents::cursor \
  --config '{"agentType":"cursor","integrationId":"'"$INTEGRATION_ID"'","repository":"https://github.com/your-org/your-repo","autoCreatePr":true}'

# Human notify rule
beeps relay rule create --relay-id "$RELAY_ID" \
  --name "Notify On-Call Engineer" \
  --rule-type schedule_notify \
  --group humans \
  --order 1 \
  --external-key humans::primary \
  --config '{"scheduleId":"'"$SCHEDULE_ID"'"}'

Different groups (agents vs humans) run in parallel.

7. Verify

beeps relay list
beeps relay rule list --relay-id "$RELAY_ID"
beeps schedule on-call --schedule-id "$SCHEDULE_ID"

8. Fire a test alert

curl -X POST "$WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"title":"Test Alert","message":"Testing the on-call system","severity":"high"}'

You should see Cursor start triaging at the same time the on-call engineer gets notified.

beeps alert list --active

SDK

The CLI tab above is faster for first-time setup. Use the SDK when you want this in your application code or in a config-as-code file.

1. Install and initialize

npm

npm install @beepsdev/sdk

pnpm

pnpm add @beepsdev/sdk

bun

bun add @beepsdev/sdk

export BEEPS_ACCESS_TOKEN="bat_your_access_token_here"

Create beeps.config.ts:

import { BeepsClient } from "@beepsdev/sdk";

const client = new BeepsClient({
  accessToken: process.env.BEEPS_ACCESS_TOKEN,
});

2. Create a relay

const relay = await client.relay.create({
  name: "production relay",
  description: "routes critical production incidents",
  externalKey: "production::relay",
});

const [webhook] = await client.webhook.listByRelay(relay.id);
const webhookUrl = `https://hooks.beeps.dev/${webhook.webhookKey}`;

Creating a relay auto-generates a webhook; webhookUrl is what you'll POST alerts to in step 8.

Use externalKey for idempotency

Always set externalKey on relays, schedules, and rules. This makes your config safe to re-run without creating duplicates. Think of externalKey as a stable identifier you control, while id is generated by beeps.

3. Create a schedule

const schedule = await client.schedule.create({
  name: "Primary On-Call",
  relayId: relay.id,
  type: "weekly",
  handoffDay: "monday",
  handoffTime: "09:00", // UTC
  externalKey: "primary::schedule",
});

Omitting startAt is intentional. The schedule starts immediately, so you can test right away.

4. Add team members

await client.schedule.addMember(schedule.id, { email: "alice@example.com" });
await client.schedule.addMember(schedule.id, { email: "bob@example.com" });

Members rotate in the order they're added.

5. Contact methods (one-time, in the dashboard)

Signup email is auto-added as a verified contact method. Add SMS or extra emails at Settings → Profile.

6. AI agent integration

Create a Cursor API key at Dashboard → API Keys. For teams, prefer a service account key. beeps validates the key against Cursor's API at creation time.

const integration = await client.integration.create({
  name: "Cursor Agent",
  provider: "cursor",
  apiKey: process.env.CURSOR_API_KEY,
});

7. Create parallel relay rules

// AI agent
await client.relay.rules.create(relay.id, {
  name: "AI Agent Auto-Triage",
  externalKey: "agents::cursor",
  ruleType: "agent",
  group: "agents",
  order: 1,
  config: {
    agentType: "cursor",
    integrationId: integration.id,
    repository: "https://github.com/your-org/your-repo",
    autoCreatePr: true,
  },
});

// Human notify
await client.relay.rules.create(relay.id, {
  name: "Notify On-Call Engineer",
  externalKey: "humans::primary::schedule-notify",
  ruleType: "schedule_notify",
  group: "humans",
  order: 1,
  config: { scheduleId: schedule.id },
});

Different groups run in parallel.

8. Fire a test alert

POST to the webhookUrl from step 2:

curl -X POST https://hooks.beeps.dev/YOUR_WEBHOOK_KEY \
  -H "Content-Type: application/json" \
  -d '{"title":"Test Alert","message":"Testing","severity":"high"}'

For a full runnable config file (beeps.config.ts) and CI deploy via beeps relay apply, see Config as Code.

MCP

Drive setup from Claude Code, Codex, or any MCP-compatible client. Best when you live in your editor and don't want to context-switch.

Connect the MCP server

Claude Code

claude mcp add --transport http --scope user beeps https://mcp.beeps.dev/mcp

Codex

codex mcp add beeps --url https://mcp.beeps.dev/mcp
codex mcp login beeps --scopes "openid,profile,email,offline_access,beeps.tools.read,beeps.tools.write"

From here, just talk to your agent.

1. Create a relay

Create a relay called "production relay" with externalKey "production::relay".

The agent calls beeps_create_relay and reports back the relay id. The webhook key is deliberately never exposed through MCP (it's a credential) — grab the webhook URL for step 8 from Settings → Relays in the dashboard, or via the CLI: beeps webhook list --relay-id <rly_…>.

2. Create a schedule

Create a weekly schedule called "Primary On-Call" on the production relay,
handoff Monday at 09:00, externalKey "primary::schedule".

3. Add team members

Add alice@example.com and bob@example.com to the primary schedule.

4. Contact methods (one-time, in the dashboard)

Open Settings → Profile to add SMS or extra emails. Your signup email is already verified.

5. AI agent integration (one-time, outside MCP)

MCP can't create the Cursor credential. That's the only setup step that needs the CLI or dashboard. Create a Cursor API key at Dashboard → API Keys (a service account key is best for teams), then either:

export CURSOR_API_KEY="cursor_api_key_here"
beeps integration create --provider cursor --name "Cursor Agent" --api-key-env CURSOR_API_KEY --json

…or use Settings → Integrations → New integration in the dashboard. Either way, grab the returned integration id (int_…) so you can reference it in the next step.

6. Create parallel relay rules

On the production relay, create two rules in parallel:

1. An "agent" rule named "AI Agent Auto-Triage", group "agents", using my
   Cursor integration int_REPLACE_ME, repository
   "https://github.com/your-org/your-repo", autoCreatePr true.

2. A "schedule_notify" rule named "Notify On-Call Engineer", group "humans",
   pointing at the Primary On-Call schedule.

Different groups fire in parallel.

7. Verify

List the rules on the production relay and tell me who's on call right now.

8. Fire a test alert

curl -X POST https://hooks.beeps.dev/YOUR_WEBHOOK_KEY \
  -H "Content-Type: application/json" \
  -d '{"title":"Test Alert","message":"Testing","severity":"high"}'

Then back in your editor:

Show me active alerts.

Next steps

• Config as Code — check beeps.config.ts into your repo and deploy via beeps relay apply in CI.
• Relay Rules — escalation, webhooks, sequential vs parallel.
• Schedules — overrides, multiple rotations, secondary schedules.
• Agent Integrations — Devin, Cursor, OpenCode, AWS DevOps, Zup.
• Observability Integrations — Sentry, Datadog, Prometheus, generic webhooks.
• MCP Server — full tool list for ongoing alert triage from your editor.

Troubleshooting

• Alerts not appearing
• No one receiving notifications
• AI agent not responding
• Rules not executing