herald¶

Central nervous system for the F3L1X ecosystem

Herald is the message broker, authentication gateway, and marketplace coordinator that enables realms to communicate securely.

What It Does¶

Herald acts as the intermediary for all realm-to-realm communication. When one realm needs to talk to another, it sends a message through herald. Herald handles routing, authentication, and payment verification automatically.

Think of herald as your local API gateway + message broker + auth server in one.

Key Capabilities¶

Message Routing¶

• WebSocket Channels: Real-time bidirectional communication between realms
• Redis Backend: Fast message queuing and pub/sub
• Request/Response Pattern: Synchronous messaging with automatic correlation

Authentication¶

• JWT Tokens: Secure authentication for all realm requests
• Device Flow OAuth: CLI/desktop app authentication without browser
• Token Validation: Automatic JWT verification on all WebSocket connections

Marketplace Gateway¶

• Tool Catalog: Exposes available MCP tools via REST API
• x402 Integration: Returns payment-required responses for paid tools
• Price Discovery: Dynamic pricing based on creator settings

Real-Time Status¶

• Health Monitoring: Broadcasts realm status updates
• Connection Tracking: Shows which realms are online
• Event Notifications: Alerts for system events

How It Works¶

For End Users¶

When you start F3L1X, herald starts automatically. You don't interact with herald directly - it runs in the background coordinating everything.

Example: When you click "Start" on a realm in the dashboard:
1. Dashboard sends message to herald
2. Herald authenticates your request
3. Herald routes command to target realm
4. Realm responds through herald
5. Dashboard receives status update

For Developers¶

If you're building a custom realm, you integrate with herald to join the network (example code shown for reference - implementation details are in the realm's actual codebase).

Accessing herald¶

Web Dashboard¶

URL: http://127.0.0.1:8014

The herald dashboard shows:
- Connected realms
- Message throughput
- Authentication logs
- Marketplace tool catalog

API Endpoints¶

WebSocket Endpoints¶

Common Use Cases¶

Use Case 1: Custom Realm Integration¶

Goal: Your custom realm needs to access doc-u-me search

1. Get JWT token from herald auth endpoint
2. Connect to herald WebSocket
3. Send message with target='doc-u-me', action='search'
4. Receive search results via WebSocket

Use Case 2: Tool Discovery¶

Goal: Browse available marketplace tools

1. Navigate to http://127.0.0.1:8014/api/tools/
2. View tool catalog with pricing
3. Click tool to see details and usage instructions

Use Case 3: Debugging Communication¶

Goal: Check if realms can communicate

1. Open herald dashboard at :8014
2. Check "Connected Realms" section
3. Verify target realm shows as online
4. Check message logs for errors

Important Notes¶

Port Conflicts¶

Herald MUST run on port 8014. Other realms expect to find it there. If port 8014 is in use, herald won't start and the ecosystem will be non-functional.

Security¶

• Never expose herald to the internet - it's designed for localhost only
• JWT tokens expire after 24 hours
• Client secrets should be in .env files, never committed to git

Dependencies¶

Herald requires:
- Redis (for message queuing)
- PostgreSQL (for tool catalog and user auth)
- Python 3.13+
- Django 6.0+

If Redis isn't running, herald will start but WebSocket communication will fail.

Troubleshooting¶

"Connection refused" errors¶

Symptom: Other realms can't connect to herald
Fix: Check if herald is running: curl http://127.0.0.1:8014/api/health/

JWT validation failures¶

Symptom: 401 Unauthorized responses
Fix: Regenerate token - they expire after 24 hours

Tool catalog is empty¶

Symptom: /api/tools/ returns empty list
Fix: Run python manage.py loadtools to populate catalog

Related Realms¶

• f3l1x-dashboard - Uses herald for realm control commands
• 402-payment - Integrates with herald for marketplace payments
• All custom realms - Should integrate with herald for inter-realm communication

Further Reading¶

• Building Custom Realms
• x402 Payment Protocol
• Authentication Guide