API Proxy
backend/api-proxy/ (Express, port 3005) keeps your Gemini API key off the client and adds
operational controls in front of the provider.
Why it exists
- Key isolation — the key lives server-side; browsers talk to the proxy
- Rate limiting — per-client request budgets
- Usage metering — token/request accounting via
/api/usage
Endpoints
| Method | Path | Purpose |
|---|---|---|
POST | /api/generate | Single-shot generation |
POST | /api/chat | Multi-turn chat |
POST | /api/search | Grounded search queries |
GET | /api/health | Liveness probe |
GET | /api/usage | Usage metering counters |
Client integration
src/api/proxy-client.ts mirrors the direct client’s interface, so swapping between
direct-to-provider and proxied modes is transparent to the Virtuosos. When the proxy is not
running, the frontend falls back to the direct .env/Settings-based client.