The signal marketplace for AI agents.
Herald is a managed signal routing service that connects publishers with AI agents. Features marketplace discovery, delivery guarantees, retries, and monetization.
Publisher → Herald API → Delivery (Agent/Webhook/Telegram) → Subscribers
Looking for something simpler? Check out ntfy-bridge — a lightweight local bridge from ntfy.sh to localhost. No server required.
# Clone
git clone https://github.com/starksama/herald.git && cd herald
# Start Postgres + Redis
docker compose up -d
# Run API (port 8080)
cargo run -p herald-api
# Run worker (separate terminal)
cargo run -p herald-workerAPI available at http://localhost:8080
# Health check
curl http://localhost:8080/health
# Register a publisher
curl -X POST http://localhost:8080/v1/publishers \
-H "Content-Type: application/json" \
-d '{"name": "My App", "website": "https://example.com"}'
# Response: {"id": "pub_xxx", "api_key": "hld_pub_xxx", ...}- API (
herald-api): REST endpoints for publishers and subscribers - Worker (
herald-worker): Async webhook delivery with retries - Database: PostgreSQL (persistent state + job queue via apalis)
- Redis: Rate limiting only
See ARCHITECTURE.md for detailed design.
POST /v1/publishers Register as publisher
POST /v1/channels Create channel
POST /v1/channels/:id/signals Push signal
GET /v1/channels/:id/stats Get stats
POST /v1/subscribers Register as subscriber
POST /v1/webhooks Register webhook endpoint
POST /v1/subscriptions Subscribe to channel
GET /v1/subscriptions List subscriptions
Signals are delivered to registered webhooks with HMAC signatures:
POST {your-webhook-url}
X-Herald-Signature: sha256=...
X-Herald-Timestamp: 1707379800
{
"event": "signal",
"channel_id": "ch_xxx",
"signal": { ... }
}
| Variable | Default | Description |
|---|---|---|
HERALD_DATABASE_URL |
- | PostgreSQL connection string |
HERALD_REDIS_URL |
- | Redis connection string |
HERALD_API_BIND |
0.0.0.0:8080 |
API listen address |
HERALD_HMAC_SECRET |
- | Secret for webhook signatures |
- SPEC.md — Product specification
- ARCHITECTURE.md — Technical design
- docs/api.md — Full API reference
- docs/openclaw.md — OpenClaw integration guide
MIT