relay-ops

name	relay-ops
description	Gateway (sub2api) day-to-day operations on the VPS: fix an INSUFFICIENT_BALANCE-style block (raise balance AND clear the cached auth snapshot), check/restore the nightly pg_dump backups, read usage/spend, reset the admin password, and keep the routing rule intact (a key's group platform must match its account platform). Use when the user hits a balance/credit error, asks about backups/restore, billing, or the gateway behaving wrong (misrouted requests, wrong model answering).
allowed-tools	Read, Bash, Agent, AskUserQuestion, TodoWrite

Gateway operations

Read CLAUDE.md (the gateway gotchas). Delegate all on-VPS execution to the relay-operator agent. Never print keys or the admin password.

INSUFFICIENT_BALANCE-style block (the #1 issue)

The gateway gates every request on the key-owner's wallet and caches auth (short TTL); the admin role does NOT bypass it. It needs two steps — a DB edit alone does nothing until the cached snapshot clears:

cd ~<vps-user>/sub2api/deploy
# 1) raise the balance (admin-UI "recharge" is cleanest, or:)
docker compose exec -T postgres psql -U sub2api -d sub2api \
  -c "UPDATE users SET balance=100000000 WHERE id=<owner_id>;"
# 2) invalidate the cached auth snapshot (or wait out its TTL):
docker compose exec -T redis redis-cli DEL apikey:auth:<sha256(apikey)>

Prefer the admin-UI recharge when the user can open the console — see the relay-admin-console skill.

Usage / spend

The bundled vps/cache-usage.sh --summary (24h rollup) / --watch (live). For the web view, use the relay-admin-console skill.

Backups

The nightly pg_dump timer writes to the backup dir and keeps a rolling window. Confirm the timer is active; restore by gunzip-ing the dump into postgres psql via docker compose exec.

Admin password

The initial password is printed once at first start (docker compose logs <gateway> | grep -i 'admin password'); change it during setup; if lost, reset via the DB.

Routing rule (don't break it)

A key's group platform must match its account platform (Anthropic-group key → real Claude; OpenAI-group key → GPT). A wrong-group key misroutes. If "the wrong model is answering", check the key's group, not the client.

Guardrails

• Never expose Postgres/Redis/the gateway beyond loopback. Never print secrets.
• Don't pkill -f gateway processes from an SSH one-liner — use container/compose controls or fuser -k <port>/tcp.