| 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
docker compose exec -T postgres psql -U sub2api -d sub2api \
-c "UPDATE users SET balance=100000000 WHERE id=<owner_id>;"
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.
