@bitmacro/relay-agent

Manage your Nostr relay without touching the terminal.

relay-agent is a REST API agent that runs on your relay server and translates HTTP requests into strfry CLI commands. It is part of the BitMacro Relay Manager ecosystem.

Quick Start

Via npx

npx @bitmacro/relay-agent --port 7800 --token your-secret-token

Use --version or --help to check version or CLI options.

Via Docker

Multi-arch image (amd64, arm64) at ghcr.io/bitmacro/relay-agent. Includes strfry binary. Mount your strfry data volume:

docker pull ghcr.io/bitmacro/relay-agent:latest
docker run -p 7800:7800 \
  -e RELAY_AGENT_TOKEN=your-secret-token \
  -v /path/to/strfry-db:/app/strfry-db \
  -v /path/to/whitelist.txt:/app/whitelist.txt \
  ghcr.io/bitmacro/relay-agent:latest

Or build locally: docker build -t relay-agent .

Multiple relays (v0.2): One agent, N relays via RELAY_INSTANCES. Use docker-compose.relay-agent.yml (fragment) or docker-compose.yml (standalone).

Server deployment (v0.2 multi-relay)

# 1. Clone relay-agent into a subdir next to your docker-compose.yml
git clone https://github.com/bitmacro/relay-agent.git relay-agent

# 2. Configure .env (single token for all relays)
echo "RELAY_AGENT_TOKEN=your-secret-token" >> .env

# 3. Build and start (requires relay_private, relay_public, relay_paid, network bitmacro in parent compose)
docker compose -f docker-compose.yml -f relay-agent/docker-compose.relay-agent.yml build relay-agent
docker compose -f docker-compose.yml -f relay-agent/docker-compose.relay-agent.yml up -d relay-agent

Prerequisites: nostr/{public,private,paid}/ must have strfry.conf, whitelist.txt, data/.

Operational Commands

v0.2 multi-relay

# Build and start
docker compose -f docker-compose.yml -f relay-agent/docker-compose.relay-agent.yml up -d --build relay-agent

# View logs
docker compose -f docker-compose.yml -f relay-agent/docker-compose.relay-agent.yml logs -f relay-agent

# Stop
docker compose -f docker-compose.yml -f relay-agent/docker-compose.relay-agent.yml stop relay-agent

Standalone (from relay-agent dir)

cd relay-agent && docker compose up -d

Smoke Test

# v0.2: health lists relay IDs and version
curl http://localhost:7810/health
# {"status":"ok","version":"0.2.0","relayIds":["public","private","paid"],...}

# v0.2: stats for a specific relay (replace TOKEN and relay id)
curl -H "Authorization: Bearer TOKEN" http://localhost:7810/private/stats

REST API Endpoints

v0.2 multi-relay (RELAY_INSTANCES set)

relayId = logical ID from RELAY_INSTANCES (e.g. public, private, paid). Must match agent_relay_id in relay_configs.

v0.1 single-relay (no RELAY_INSTANCES)

Query parameters for GET /events

Authentication

All endpoints except /health require:

Authorization: Bearer <your-token>

Environment Variables

v0.2 multi-relay

v0.1 single-relay

Compatibility

Architecture

relay-panel
    │  HTTP + JWT
    ▼
relay-api (Vercel)
    │  HTTP REST + Bearer JWT
    ▼
relay-agent (this repo)
    │  child_process spawn()
    ▼
strfry (local C++ process / LMDB)

The relay-agent is stateless — it has no database. State lives in Supabase, managed by relay-api. The relay-agent only translates HTTP calls into strfry CLI commands.

Troubleshooting

503 "relay unavailable"

1. Capture the error — run logs in one terminal, then curl in another:

   # v0.2
   docker compose -f docker-compose.yml -f relay-agent/docker-compose.relay-agent.yml logs -f relay-agent
   curl -H "Authorization: Bearer TOKEN" "http://localhost:7810/private/events?limit=3"

   The strfry stderr will appear in the logs.

2. LMDB "Resource temporarily unavailable" — relay and relay-agent share the same db. Increase maxreaders in your relay's strfry.conf (e.g. ./nostr/private/strfry.conf):

   dbParams {
     maxreaders = 512
   }

   Then restart the relay: docker restart relay_private

3. Verify db path — relay-agent mounts ./nostr/private/data:/app/nostr/private/strfry-db (strfry.conf uses db="./strfry-db/"). Your relay (relay_private) must use the same host path. Check your main docker-compose.yml:

   grep -A5 relay_private docker-compose.yml

4. Test strfry inside container (v0.2):

   docker compose -f docker-compose.yml -f relay-agent/docker-compose.relay-agent.yml run --rm relay-agent sh -c 'ls -la /app/nostr/private/strfry-db && /app/strfry --config /app/nostr/private/strfry.conf scan "{}" | head -3'

   If data.mdb is missing or strfry fails, fix the volume path.

Security

• Run on a private network. The relay-agent should run on the operator's server and never be exposed directly to the internet.
• Access is controlled by the relay-api, which proxies requests with a shared Bearer token.
• Use a strong, random token in production. Rotate it if compromised.

Contributing

See CONTRIBUTING.md for setup and PR guidelines.