Skip to main content
When live TLS to the node hostname fails, you may enqueue a sealed request on the relay. The relay cannot read the envelope. Replies are sealed to your per-request reply key so you can claim them later even if your process exited.

Plaintext to seal

Build the HTTP request the node should replay as JSON, then seal it to box_pubkey from /v1/resolve with a libsodium sealed box (crypto_box_seal, X25519). Generate an ephemeral X25519 keypair for this request. Put the public key in both the sealed plaintext and the POST body (the relay cannot read the envelope, so it needs the metadata copy for claim challenges).
Sign the public URL https://<hostname>/mcp (same headers as a live call). Prefer body as the exact string of bytes you signed (Content-Digest must match). Keep the sealed envelope ≤ 64 KiB (stricter than live MCP’s 256 KiB). Signatures still use a ≤ 300 s validity window. The node validates them as of queue receive time, not replay time, so overnight delivery works.

Enqueue

hostname is the full FQDN from resolve (e.g. n….relay.fau.run). reply_pubkey is required and must match the key inside the sealed plaintext. Response 202:
Generate request_id yourself and write it, the reply private key, user, hostname, and tool to your outstanding request store before enqueueing. This ordering survives a process crash or an ambiguous POST timeout. Limits: 32 envelopes per node, TTL 24 h, at-least-once. request_id makes retries idempotent.

Poll for a reply

If the request was enqueued with reply_pubkey, the first response is 401:
Open challenge with your reply private key (crypto_box_seal_open). Retry:
wait=N long-polls while the request is pending. The relay caps N at 60 seconds. Omit it or use 0 for an immediate status check. A timeout still returns 204; reconnect and poll again with the same outstanding-request entry and claim flow. Decrypt the 200 envelope with the same reply private key. The claim is consumed when the answer is ready. Delete the outstanding-request entry only after the reply has been successfully decrypted and durably handled.

Errors

Etiquette

Do not flood the queue while also hammering live TLS. Tell the end user when you are waiting for their Mac to wake.