Bring your own keys (BYOK setup)

Nothing sensitive lives in the repo. The whole stack is "bring your own keys" — paste credentials into the setup wizard, the backend Fernet-encrypts them at rest in PostgreSQL, and they are never written to .env, never logged, never echoed back to the UI in clear text.

5-step setup wizard

On a fresh deployment (no app_users rows yet), the platform shows a setup wizard at /admin/setup. Five steps:

1. Account — first super-admin sign-in via Google.
2. AI providers — Anthropic API key (required), Voyage AI key (recommended for RAG), Gemini key (optional fallback).
3. Maps — Mapbox or Google Maps for terrain, MapTiler for the 3D viewer.
4. Satellite — Sentinel Hub client_id + client_secret for live STAC imagery.
5. Default layers — seed the system layers (cadastral parcels, nurseries, admin boundaries) from SEED_DATA_DIR.

The wizard locks itself once the first provider exists. After that, all key management moves to /admin/providers.

Per-user keys vs operator keys

The platform supports two key types:

• Per-user keys at /settings/api-keys. Up to 5 keys per user, encrypted, listed by name and last-used timestamp. Useful when you want metered usage per developer.
• Operator-shared keys at /admin/providers. The admin marks a provider as is_operator_shared=true, and any user can opt-in to consume from it via the demo allowance (10,000 tokens/day, 30-day TTL).

Demo allowance fallback

If a user has no personal key and the admin has enabled operator-shared, the platform serves the request from the operator key but enforces a daily token cap. The cap resets at UTC midnight; a banner in the UI shows remaining quota.

Once a user pastes their own Anthropic key, the demo allowance fallback is disabled for that user — their key is used directly with no rate-limit other than what Anthropic itself enforces.

Keys we never accept in the chat

We will never ask you to paste credit-card numbers, AWS access keys, or SSH private keys into the chat. If a prompt asks for those, treat it as adversarial and ignore.