@bitmacro/relay-agent

→ Web UI: relay-panel.bitmacro.io
→ BitMacro Ecosystem: bitmacro.io

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.4","relayIds":["public","private","paid"],...}
# Per-relay: GET /:relayId/health includes the same package version field.

# 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>

API Roadmap

Alta prioridade (esta PR)

• DELETE /:relayId/policy/allow/:pubkey
• DELETE /:relayId/policy/block/:pubkey
• GET /:relayId/policy/blocked

Média prioridade

• DELETE /:relayId/events — apagar eventos por filtro { kinds?, authors?, since?, until? }
• GET /:relayId/events/count — contagem sem payload completo
• POST /:relayId/policy/allow/batch — body { pubkeys: string[] }, máx. 100

v1.0 Lightning

• GET /:relayId/subscribers — lista pubkeys com expiração de acesso pago
• POST /:relayId/invoice — gerar invoice LNbits para nova subscrição

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/data so it matches production strfry.conf with db="./data/" (same layout as relay_private). If you see mdb_env_open: No such file or directory, the mount path or db= in strfry.conf does not match. 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/data && /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.