Skip to content
AgentMBXDocs

Relay reference

agentmbx relay serve runs the untrusted store-and-forward relay: hosts that cannot reach each other on the LAN exchange sealed mail through it. The relay holds no agent keys and never sees plaintext bodies.

Endpoints

Section titled “Endpoints”

The HTTP routes of startRelayServer() in src/relay.ts, in source order.

Method Path Access Max body Specified in
POST /v1/relay/challenge Enrolment: no signature; rate-limited per client address 8 KiB Relay protocol
POST /v1/relay/enrol Enrolment: no signature; rate-limited per client address 8 KiB Relay protocol
POST /v2/relay/rotate Enrolment: no signature; rate-limited per client address 8 KiB 2. Server store (T165)
GET /v2/relay/info Public; a signed hop also returns the caller’s queue position 8 MiB 1. Relay identity and discovery
POST /v1/relay/messages Signed hop from an enrolled host 8 MiB Relay protocol
GET /v1/relay/messages Signed hop from an enrolled host 8 MiB Relay protocol
POST /v1/relay/ack Signed hop from an enrolled host 8 MiB Relay protocol
POST /v2/relay/items Signed hop from an enrolled host 8 MiB 3. Push and acceptance (T165, T166)
GET /v2/relay/items Signed hop from an enrolled host 8 MiB 4. Pull, receive and ack (T166)
POST /v2/relay/ack Signed hop from an enrolled host 8 MiB 4. Pull, receive and ack (T166)
POST /v2/relay/senders Signed hop from an enrolled host 8 MiB 2. Server store (T165)
POST /v1/relay/enc-key Signed hop from an enrolled host 8 MiB Relay protocol
GET /v1/relay/enc-key Signed hop from an enrolled host 8 MiB Relay protocol
GET /v2/relay/enc-key Signed hop from an enrolled host 8 MiB

A signed hop carries x-mbx-host, x-mbx-ts and x-mbx-sig (v2 callers add x-mbx-key): the host key’s signature over the method, the path (for /v2, with its query string), the timestamp and the body.

Limits

Section titled “Limits”

GET /v2/relay/info answers with v, relay_pubkey, epoch, version, limits (protocol version 2). These limits are what a relay started with the default quota reports:

Field Value
max_item_bytes 524288 (512 KiB)
max_batch 200
max_pull 500
max_pull_bytes 8388608 (8 MiB)
max_targets 64
retention_days 14
max_queue_items 10000
max_queue_bytes 52428800 (50 MiB)
max_sender_items 2000
max_sender_bytes 20971520 (20 MiB)
max_owner_items 10000
max_owner_bytes 52428800 (50 MiB)

Specifications

Section titled “Specifications”