@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.7","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

strfry.conf vs relay-agent (v0.2)

The agent runs strfry with cwd = dirname(strfryDb). The db = … line in strfry.conf is resolved relative to that directory.

• In each relay’s strfry.conf, use:

  db = "./data/"

• In RELAY_INSTANCES, set strfryDb to the LMDB directory inside the agent container, e.g.:

  "/app/nostr/<relayId>/data"

  where <relayId> matches your logical id (public, private, paid). Mount the host folder to that path (see docker-compose.relay-agent.yml).

Then ./data/ resolves to /app/nostr/<relayId>/data — the same files the relay uses if the host nostr/<relayId>/data is mounted consistently.

Relay containers (strfry relay) often use working_dir: /app and mount the same host data/ at /app/data, still with db = "./data/". That is a different in-container path but the same host directory as the agent mount.

Breaking change: Older setups used db = "./strfry-db/" and strfryDb ending in strfry-db. Migrate to db = "./data/" and strfryDb ending in /data, and align Docker volume targets on both the agent and relay services.

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 Stale reader slots (after crashes / SIGABRT) can still wedge the relay until cleared. Stop every container that mounts that LMDB directory (relay_* + relay-agent), then on the host (path = host dir that contains data.mdb):

   # Debian/Ubuntu: lmdb-utils provides mdb_stat — not mdb_reader_check
   sudo mdb_stat -e -rr /home/server/nostr/public/data

   Double -r checks the reader table and removes stale entries. Then start the relay container(s), then relay-agent.

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.
Issues and PRs are welcome — bug fixes, UI improvements, and new relay-agent integrations.

This project is maintained by BitMacro.

Contributors

License

MIT. See LICENSE.