# Run AI Gateway in production

Production deployment protects three independent assets: provider secrets,
consumer access and durable usage state.

## Use a stable master key

Generate the key once, store it in a secrets manager and inject it as
`RUNKU_AI_MASTER_KEY`. Back it up separately from the database. A database
backup without the matching master key cannot recover provider credentials.

Never log, commit or return the master key.

## Prefer PostgreSQL for product state

```yaml
# Production store for providers, encrypted secrets, consumers and usage state.
store:
  # PostgreSQL is recommended for production and multiple instances.
  driver: postgres
  # Dedicated DSN injected through the environment or a secrets manager.
  dsn: ${RUNKU_AI_STORE_DSN}
```

Use a dedicated database and least-privilege database user. Back up migrations,
providers, encrypted credentials, models, consumers, quotas and usage records.

SQLite remains valid for a single-node local deployment, but operational
backup and concurrency are the operator's responsibility.

## Terminate TLS

Expose `/v1/*`, `/auth/*` and `/portal/*` through HTTPS. Terminate TLS in the
gateway configuration or a trusted reverse proxy. Set `public_base_url` to the
same external HTTPS origin clients use.

## Separate credentials

- one admin key per operator or automation boundary;
- one consumer and key per person, team or workload;
- multiple provider credentials when rotation or failover is required;
- no shared provider credential on client machines.

Rotate by adding a replacement key, verifying traffic, then revoking the old
key. Do not overwrite all credential boundaries at once.

## Configure OIDC for administrators

Prefer customer-owned OIDC for human portal access. Google requires an ID token;
Entra uses an access-token JWT with a `/v2.0` issuer and API audience. API keys
remain useful for break-glass and automation.

## Monitor the service

At minimum monitor:

- `/healthz` availability;
- upstream errors and latency;
- quota rejections;
- cache hit rate and size;
- token and request usage by consumer/model;
- provider credential health;
- store availability and backup success.

Do not place raw prompts, completions, provider keys or consumer keys in an
external monitoring system.

## Recovery drill

Before production traffic, verify that you can:

1. restore the AI store into an isolated environment;
2. inject the matching `RUNKU_AI_MASTER_KEY`;
3. decrypt and use a test provider credential;
4. revoke a consumer key;
5. preserve usage audit and quota state;
6. start without any Runku Cloud dependency.