Run your first governed message.

Before you start

PigeonMQ currently requires Node.js 22 or newer. The examples below use the Node.js client, but the broker itself exposes Pigeon Protocol v1 over HTTP + JSON.

1. Install PigeonMQ

npm install pigeonmq

2. Start the broker

npx pigeon broker start

The local broker listens on http://localhost:8787 by default.

curl http://localhost:8787/health

A healthy broker should return a successful health response before you continue.

3. Authenticate and negotiate a contract

The client presents a credential and requests the subjects it needs. The broker resolves the principal and returns only the communication scope permitted by policy.

import { PigeonClient } from "pigeonmq";

const pigeon = new PigeonClient({
  url: "http://localhost:8787",
  token: "checkout-token"
});

await pigeon.connect(["payments.authorize"]);

The resulting contract is short-lived and bound to the authenticated principal. It does not let the client invent identity or permissions.

4. Publish a governed message

Publishing under a valid contract still triggers message admission. The broker can evaluate intent, schema, region, classification, sensitive data and idempotency before the message proceeds.

const result = await pigeon.request(
  "payments.authorize",
  {
    merchantId: "m",
    orderId: "order_42",
    amount: 42.5,
    currency: "GBP",
    paymentToken: "tok"
  },
  {
    intent: "authorize_payment",
    idempotencyKey: "order_42:authorize",
    classification: "pci",
    region: "uk"
  }
);

console.log(result.status); // accepted

5. Understand the broker path

credential
    ↓
authenticated principal
    ↓
communication contract
    ↓
message envelope
    ↓
identity → intent → schema → region → data → idempotency
                                              ↓
                              allow | deny | quarantine

The contract establishes session authority. The admission chain decides whether this specific operation may proceed.

6. See a blocked message

A permitted producer can still violate policy. If the message carries a forbidden sensitive field, crosses a region boundary, fails schema validation or otherwise falls outside the contract and subject policy, the broker can stop it before receiver processing.

identity        ✓
intent          ✓
schema          ✓
region          ✓
data             ✕  forbidden sensitive field

QUARANTINE
receiver does not receive the message

7. Run the built-in walkthrough

npm run demo

The repository walkthrough covers authorised communication, duplicate suppression, unauthorised producers and sensitive-field quarantine.

8. Useful CLI commands

Where to go next