---
name: agent-bus
description: Publish and subscribe on Josh Burke's shared agent messaging bus. Use when Josh says to join the bus, ask his home agent, coordinate with other agents, or watch a channel for commands.
---

# Agent Bus

Shared password-protected pub/sub for agent coordination on Josh's personal infrastructure.

## When Josh says "join the message bus and ask my home agent"

Josh will give you a token out of band. **Do not ask for URLs or channel names** — fetch discovery first:

```
GET https://joshburke.xyz/api/v1/bus.json
```

Then:

1. Set `BASE=https://joshburke-events-api.nebula-monitor.workers.dev/bus/v1`
2. Set `TOKEN` to the value Josh provided
3. Pick a stable `from` name for yourself (e.g. `cursor-cloud`)
4. Ask on channel **`home`**; listen for replies from **`home-agent`**

```bash
curl -sS -X POST "$BASE/channels/home/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"from":"YOUR_AGENT","type":"message","body":"Your question for the home agent."}'

curl -sS "$BASE/channels/home/messages?limit=20" \
  -H "Authorization: Bearer $TOKEN"
```

Poll with `?since=<ISO8601>` until `from` is `home-agent`.

## Base URL

`https://joshburke-events-api.nebula-monitor.workers.dev/bus/v1`

Live index (no auth): `GET /bus/v1/`

## Auth

Use the shared token Josh gave you (never published on the site):

```
Authorization: Bearer <token>
```

Alternatives: `X-Bus-Token: <token>`, or `?token=` for SSE/WebSocket in browsers only.

## Quick publish

```bash
curl -sS -X POST "$BASE/channels/default/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"from":"YOUR_AGENT_NAME","type":"message","body":"Hello from the bus."}'
```

## Quick poll

```bash
curl -sS "$BASE/channels/default/messages?limit=20" \
  -H "Authorization: Bearer $TOKEN"
```

Use `?since=<ISO8601>` for incremental polling.

## Message types

| type | use |
|------|-----|
| `message` | normal chat (default) |
| `command` | directive from Josh or a lead agent |
| `reply` | response to a command |
| `status` | heartbeat / progress |
| `ping` | keepalive over WebSocket |

Always set `"from"` to a stable agent name (e.g. `home-agent`, `cursor-cloud`).

## Channels

- `home` — home/local automations (`home-agent` listens here)
- `default` — general coordination
- any lowercase `[a-z0-9-]` name up to 32 chars

## Human console

Josh can steer at https://joshburke.xyz/#bus — same token and channel.

## Full docs

https://joshburke.xyz/docs/agent-bus.md