Quickstart

Set up the full human on-call loop: a relay that receives alerts, a schedule with you on it, and a test alert that beeps your phone. Then wire in AI agents as a next step.

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

Prerequisites

• A beeps account.
• Node.js 20+ and npm.
• For the CLI tab: curl and jq (used to capture ids between steps).
• 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 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 and saves an org-scoped token to ~/.config/beeps/config.json. In CI, set BEEPS_ACCESS_TOKEN instead (it takes precedence).

Steps capture ids into shell variables so you can paste top to bottom — if running as a script, start with set -euo pipefail.

1. Make sure beeps can reach you

Your signup email is already verified. Add your phone for the channel that wakes you up:

beeps contact-method add --transport sms --value +15555550100

Reply YES to the verification text (unverified numbers never receive alerts — check with beeps contact-method list).

2. Create a relay

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

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

Creating a relay auto-generates the webhook you’ll POST alerts to in step 6.

3. 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')
echo "$SCHEDULE_ID" # → sch_xxxxxxxxxxxx

startAt defaults to now, so you can test immediately.

4. Put yourself on call

beeps schedule add-member --schedule-id "$SCHEDULE_ID"   # → member added: <your user id>

No --email means you. Teammates must be org members first (invite via Settings → Members), then add with --email alice@example.com. Members hand off in the order added.

5. Route alerts to the schedule

beeps relay rule create --relay-id "$RELAY_ID" \
  --name "Notify On-Call Engineer" \
  --rule-type schedule_notify \
  --external-key humans::primary \
  --config '{"scheduleId":"'"$SCHEDULE_ID"'"}'   # → rule created: rr_...

beeps schedule on-call --schedule-id "$SCHEDULE_ID"   # confirm it's you

6. 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"}'

Expected response:

{"success":true,"alertsCreated":1,"alertIds":["alr_..."]}

A 401 means $WEBHOOK_URL is wrong (re-run step 2’s webhook list). Within seconds, your phone buzzes with a link to the alert.

7. Respond like it’s real

ALERT_ID=$(beeps alert list --active --json | jq -r '.[0].id')
beeps alert on-it --alert-id "$ALERT_ID"     # acknowledges + stops escalation
beeps alert resolve --alert-id "$ALERT_ID"   # closes it

That’s the loop your team will live in.

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="YOUR_ACCESS_TOKEN"

Create setup.ts (a one-off script — distinct from config-as-code’s declarative beeps.config.ts):

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

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

2. Make sure beeps can reach you

Your signup email is already verified. Add SMS:

const contactMethod = await client.contactMethod.create({
  transport: "sms",
  value: "+15555550100",
});

The verification text sends automatically — reply YES.

3. 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}`;
console.log({ relayId: relay.id, webhookUrl });

Use externalKey for idempotency

externalKey is a stable id you control — setting it on relays, schedules, and rules makes the script safe to re-run without duplicates.

4. Create a schedule and put yourself on it

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

await client.schedule.addMember(schedule.id, {});

{} adds the token’s user — you. For teammates (org members only): { email: "alice@example.com" }.

5. Route alerts to the schedule

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

Run it — the output includes your webhookUrl for the next step:

npx tsx setup.ts

6. 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"}'

Expected response (a 401 means the webhook key is wrong):

{"success":true,"alertsCreated":1,"alertIds":["alr_..."]}

Your phone buzzes. Close the loop from the SDK:

const [alert] = await client.alert.listActive();
await client.alert.onIt(alert!.id);
await client.alert.resolve(alert!.id);

To manage this declaratively in CI, 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. Make sure beeps can reach you (one-time, outside MCP)

Your signup email is already verified. Add SMS via Settings → Profile, or beeps contact-method add --transport sms --value +15555550100 (reply YES to the text).

2. Create a relay

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

The webhook key is never exposed through MCP (it’s a credential) — grab the webhook URL for step 5 from the relay card on the Dashboard, or beeps webhook list --relay-id <RELAY_ID>.

3. Create a schedule and put yourself on it

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

4. Route alerts to the schedule

On the production relay, create a "schedule_notify" rule named
"Notify On-Call Engineer" pointing at the Primary On-Call schedule.
Then list the rules and tell me who's on call right now.

5. 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"}'

Expected response (a 401 means the webhook key is wrong):

{"success":true,"alertsCreated":1,"alertIds":["alr_..."]}

Your phone buzzes. Back in your editor:

Show me active alerts. Mark me as on-it for the test alert, then resolve it.

Next steps

Add an AI agent responder

Alerts can route to AI agents alongside your schedule — an agent starts triaging and opening a fix PR in the same seconds your phone buzzes. Each guide takes ~5 minutes and ends with an agent rule running in parallel with the one you just made: Cursor, Devin, Claude, Codex, OpenCode, or AWS DevOps.

Everything else

• Relay Rules — timed escalation with --delay, --repeat policies, sequential vs parallel groups.
• Config as Code — check a declarative beeps.config.ts into your repo and deploy via beeps relay apply in CI.
• Schedules — overrides, multiple schedules, secondary coverage.
• Observability Integrations — Sentry, Datadog, Prometheus, Axiom, and custom 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