> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fau.run/developer/llms.txt
> Use this file to discover all available pages before exploring further.

# Offline queue

> Deliver sealed requests when the Mac is asleep.

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).

```json theme={null}
{
  "method": "POST",
  "path": "/mcp",
  "headers": {
    "content-type": "application/json",
    "accept": "application/json, text/event-stream",
    "content-digest": "sha-256=:…:",
    "signature-input": "sig1=…",
    "signature": "sig1=:…:",
    "host": "<hostname>"
  },
  "body": "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{}}",
  "reply_pubkey": "<base64url 32-byte X25519 public key>"
}
```

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

```http theme={null}
POST https://relay.fau.run/v1/queue/<full-hostname>
Content-Type: application/json

{
  "envelope": "<base64url sealed box>",
  "reply_pubkey": "<base64url 32-byte X25519 public key>",
  "request_id": "<optional>"
}
```

`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`:

```json theme={null}
{ "request_id": "…", "expires_at": 1760000000 }
```

Generate `request_id` yourself and write it, the reply private key, user, hostname,
and tool to your [outstanding request store](https://docs.fau.run/developer/connect/outstanding-requests.md) **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

```http theme={null}
GET https://relay.fau.run/v1/queue/reply/<request_id>?wait=60
```

If the request was enqueued with `reply_pubkey`, the first response is `401`:

```json theme={null}
{ "error": "claim_required", "challenge": "<base64url sealed nonce>" }
```

Open `challenge` with your reply private key (`crypto_box_seal_open`). Retry:

```http theme={null}
GET https://relay.fau.run/v1/queue/reply/<request_id>
X-FAU-Queue-Claim: <base64url 16-byte nonce>
```

`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.

| Status | Meaning |
| - | - |
| `401` | Need (or refresh) a claim — body has `challenge` |
| `204` | Still pending (claim reusable until the answer is ready) |
| `200` | `{"envelope":"<base64url>"}` sealed to your `reply_pubkey` |
| `404` | Expired or unknown |

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

| Status | `error` |
| - | - |
| `400` | `bad_request` / `invalid_key` |
| `401` | `claim_required` |
| `404` | `not_found` |
| `413` | `too_large` |
| `429` | `rate_limited` |
| `507` | `queue_full` |

## Etiquette

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.