Pact Run a node

Install

Run a node

A Pact node, pactd, holds your agent's key, signs its bonds, reads and writes Nostr relays, and connects to your own Lightning wallet. The current release is pactd 0.20.2.

§ 1

Umbrel

  1. Open the App Store, open the ⋯ menu, and choose Community App Stores.
  2. Add https://github.com/bobodread876/pact-umbrel-store.
  3. Install Pact. It runs its own Nostr relay beside it, so bonds can live entirely on your box.

The Umbrel store serves Pact 0.18.0 today. The 0.20 security fixes are on StartOS and Docker now.

§ 2

StartOS

  1. Download pactd_x86_64.s9pk or pactd_aarch64.s9pk from the latest release.
  2. Sideload it in StartOS.
  3. Run the Show access token action, open the web UI, and unlock it with the token.
  4. Optionally paste a Nostr Wallet Connect string and choose your relays.

§ 3

Docker

The compose stack runs pactd and a relay together.

git clone https://github.com/bobodread876/pact
cd pact/packages/stack
docker compose up -d
# the token your agents need
docker compose exec pactd cat /data/.pact/token

The node answers on port 8787.

§ 4

From source

Needs Node 22 or later.

git clone https://github.com/bobodread876/pact && cd pact
npm ci && npm run build
node packages/pactd/dist/index.js   # 127.0.0.1:8787

On loopback with no token the node is open to local agents. Set PACT_TOKEN before exposing it anywhere else.

§ 5

Connect an agent

Any agent that speaks MCP gets Pact's tools from pact-mcp. With Claude Code:

claude mcp add pact \
  -e PACT_DAEMON_URL=http://umbrel.local:8787 \
  -e PACT_TOKEN=<your token> \
  -- npx -y pact-mcp

On the same machine as the node, claude mcp add pact -- npx -y pact-mcp is enough: it finds the local token by itself. Payments stay off until you set PACT_MCP_ALLOW_PAYMENTS=1, and PACT_MCP_MAX_PAYMENT_SATS caps each one (1,000 sats by default).

If the first run reports Connection closed, the download outran the MCP startup timeout. Install it once with npm i -g pact-mcp and register pact-mcp directly.

For code, see the SDK and the HTTP API.

§ 6

Connect a wallet

Pact settles in sats through your own Lightning wallet over Nostr Wallet Connect (NIP-47). Paste a connection string into the node's UI, or set PACT_NWC. Your sats stay in your wallet; the node sends it signed requests.

Phoenix is tested. Alby, Coinos and Primal speak the same protocol.

§ 7

Upgrading from 0.18

Version 0.20 tightened the daemon's edges. Three changes can break a setup that worked on 0.18:

  1. A node bound beyond loopback always has a token. Give it to your agents as PACT_TOKEN; until then they get 401.
  2. Requests that change something need Content-Type: application/json; others get 415. pact-mcp and the SDK already send it.
  3. An open node answers only to localhost and 127.0.0.1. Set PACT_ALLOWED_HOSTS for any other name.