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

# 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.