Relay API

WebSocket relay server for Position-Independent-Agent and Command Center. Pairs agents with relays 1:1 for transparent bidirectional message forwarding.

relay agent command center

Authentication

All endpoints except GET / and /agent require a token. Currently accepted but not validated — any non-empty value works.

HTTP: Authorization: Bearer <token>
WebSocket: Sec-WebSocket-Protocol: access_token, <token>

401{ "error": "unauthorized", "message": "Missing or invalid token" }

Endpoints

GET /

API documentation (this page).

https://relay.nostdlib.workers.dev/

GET /status AUTH

Live status of all connected agents, relays, and event listeners. Returns StatusResponse.

https://relay.nostdlib.workers.dev/status

POST /disconnect-all-agents AUTH

Disconnect all connected agents and their paired relays. Returns the count and IDs of disconnected agents.

https://relay.nostdlib.workers.dev/disconnect-all-agents

returns: { "disconnected": number, "agentIds": string[] }

WS /agent

Agent WebSocket connection. Server assigns a unique ID and broadcasts agent_connected to all event listeners.

wss://relay.nostdlib.workers.dev/agent

send: any — forwarded to paired relay
receive: any — forwarded from paired relay

WS /relay/:agentId AUTH

Relay WebSocket with exclusive 1:1 pairing to the specified agent.

wss://relay.nostdlib.workers.dev/relay/{agentId}

send: any — forwarded to paired agent
receive: any — forwarded from paired agent

404{ "error": "agent_not_found", "agentId": "..." }

409{ "error": "agent_already_paired", "agentId": "...", "pairedRelayId": "..." }

WS /events AUTH

Live event feed. Sends a snapshot of all agents on connect, then real-time events.

wss://relay.nostdlib.workers.dev/events

On connect: { "type": "agents", "agents": AgentStatus[] }

agent_connected{ agent: AgentStatus }
agent_disconnected{ agentId: string }
agent_paired{ agentId: string, relayId: string }
agent_unpaired{ agentId: string, relayId: string }

Types

AgentMetadata

Connection metadata collected from the Cloudflare request.

Field	Type	Description
ip	string	Client IP address
country	string	ISO country code
city	string	City name
region	string	Region / state
continent	string	Continent code (NA, EU, ...)
timezone	string	IANA timezone
postalCode	string	Postal / ZIP code
latitude	string	Geographic latitude
longitude	string	Geographic longitude
asn	number	Autonomous System Number
asOrganization	string	AS organization name
userAgent	string	Client User-Agent header
requestPriority	string	Request priority hint
tlsVersion	string	TLS version (e.g. TLSv1.3)
httpVersion	string	HTTP protocol (e.g. h2)

AgentStatus

Agent connection state. Extends AgentMetadata. Returned in /status and /events.

Field	Type	Description
id	string	Unique agent identifier
connectedAt	number	Connection timestamp (Unix ms)
paired	boolean	Whether a relay is currently paired
pairedRelayId	string \| null	Paired relay ID
messagesForwarded	number	Total messages forwarded
lastActiveAt	number	Last activity timestamp (Unix ms)
...plus all AgentMetadata fields

RelayStatus

Relay connection state. Returned in /status.

Field	Type	Description
id	string	Unique relay identifier
connectedAt	number	Connection timestamp (Unix ms)
pairedAgentId	string	ID of the paired agent

EventListenerStatus

Event listener connection state. Returned in /status.

Field	Type	Description
id	string	Unique listener identifier
connectedAt	number	Connection timestamp (Unix ms)
ip	string	Client IP address
country	string	ISO country code
city	string	City name
region	string	Region / state
continent	string	Continent code
timezone	string	IANA timezone
asn	number	Autonomous System Number
asOrganization	string	AS organization name
userAgent	string	Client User-Agent header
tlsVersion	string	TLS version
httpVersion	string	HTTP protocol

StatusResponse

Response from GET /status.

Field	Type	Description
agents	{ count, connections: AgentStatus[] }	Connected agents
relays	{ count, connections: RelayStatus[] }	Connected relays
eventListeners	{ count, connections: EventListenerStatus[] }	Connected event listeners

Heartbeat

Clients send ping text frames; the server auto-responds pong (works during hibernation)
Server sends ping every 30s to all connections
Clients with no activity for 60s are considered dead and disconnected

Constraints

Each agent can have at most one relay at a time
Connecting to /relay/:agentId returns 404 if the agent doesn't exist
Connecting to /relay/:agentId returns 409 if the agent already has an active relay