> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.astropods.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.astropods.com/_mcp/server.

# NATS JetStream binding

This page shows how to build an AMP broker on [NATS JetStream](https://docs.nats.io/nats-concepts/jetstream). It is informative: a broker may use any backend that meets the specification.

## Mapping

| AMP                   | NATS JetStream                                                                                                                                                                                                                          |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Participant inbox     | Subject `amp.<ns>.inbox.<name>`, one durable consumer per participant                                                                                                                                                                   |
| Job queue             | Stream `AMP_TASKS_<ns>` with work-queue retention on subjects `amp.<ns>.job.<job>`                                                                                                                                                      |
| Offer and claim       | A pull consumer per job; the session gateway fetches one message per free slot                                                                                                                                                          |
| Lease                 | Consumer `AckWait` = `lease_s`. The session gateway sends an in-progress ack (`+WPI`) on `claim` and on each heartbeat. Each one restarts the full `AckWait`                                                                            |
| Re-offer after expiry | Redelivery after `AckWait`. Leave `MaxDeliver` unlimited: a declined offer (`Nak`) also counts as a delivery, so `MaxDeliver` cannot stand for `max_attempts`                                                                           |
| Exhausted attempts    | The task store counts `attempt`. At `max_attempts`, the session gateway terminates the message (`AckTerm`) and moves the task to `failed`. The max-deliveries advisory fires only on the next pull and leaves the message in the stream |
| Topic                 | Stream `AMP_TOPICS_<ns>` with limits retention, one consumer per subscriber; replay with a start time or sequence                                                                                                                       |
| Registry              | KV bucket `AMP_REGISTRY_<ns>` with `LimitMarkerTTL`, one key per participant with a per-key TTL. A heartbeat republishes the key with a `Nats-TTL` header; a plain put removes the TTL. Watchers see a purge when a key expires         |
| Task store            | KV bucket `AMP_TASK_STATE`, one key per task, with history. Each update sets the last revision, so two claims cannot both succeed                                                                                                       |
| Authentication        | Auth callout: validate the participant's credential and issue a scoped user JWT                                                                                                                                                         |
| Address permission    | Publish and subscribe permissions in that JWT                                                                                                                                                                                           |
| Federation            | Superclusters (gateways) between regions, or leaf nodes                                                                                                                                                                                 |

## What NATS does not provide

| Requirement                             | Where it lives                                                                                                                                                                        |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Lease ownership                         | JetStream accepts an ack from an earlier lease holder and removes the task. The session gateway checks the lease in the task store before it acks, and returns `lease_lost` otherwise |
| Broker-set `from`                       | The session gateway stamps it from the authenticated identity before publishing                                                                                                       |
| Job eligibility and least-loaded choice | The session gateway, using the registry                                                                                                                                               |
| Rate limits and budgets                 | A policy service on the publish path                                                                                                                                                  |
| Envelope validation                     | The session gateway, against the JSON Schema                                                                                                                                          |

## Shape of a broker

```text
participant ── WebSocket or gRPC ──► session gateway ──► NATS JetStream
                                         │
                                  auth callout · policy service
```

The session gateway terminates AMP sessions, translates frames to NATS operations, and enforces the parts of the specification NATS does not.

## Next steps

* [Specification](/amp/specification): the behavior a broker must provide
* [Schemas](/amp/schemas): the frames a session gateway validates