AI Gateway YAML configuration

The AI Gateway YAML file configures process bootstrap. Providers, credentials, models, projects, consumers, quotas and usage records live in the product store and are managed through the portal or CLI.

Complete shape

# Public HTTP listener and externally reachable gateway URL.
server:
  # Local TCP port for API and portal traffic.
  port: 8088
  # Base URL advertised to clients and used for generated configuration.
  public_base_url: https://ai.example.com

# Private AI Gateway state: providers, encrypted credentials, models,
# consumers, quotas and usage metadata.
store:
  # PostgreSQL is recommended for production and shared deployments.
  driver: postgres
  # Dedicated store DSN supplied through the environment.
  dsn: ${RUNKU_AI_STORE_DSN}

# Optional exact-response cache; never stores provider credentials.
cache:
  exact:
    # Enable deterministic response reuse.
    enabled: true
    # Expiration for chat responses and embeddings.
    default_ttl: 1h
    embeddings_ttl: 168h
    # Prevent cached responses from crossing consumer boundaries.
    isolation: consumer
    # Cache only deterministic temperature-zero requests.
    only_temperature_zero: true

# Upstream request behavior.
proxy:
  # Maximum provider/model attempts before returning an error.
  failover_max_attempts: 3

# Optional OIDC verification for administrative and portal access.
auth:
  # Require authenticated access where the configured policy applies.
  enabled: true
  oidc:
    # Trusted issuer, required audience and public portal PKCE client.
    issuer: https://login.example.com/realms/company
    audience: runku-ai
    portal_client_id: runku-ai-portal

server

server.port

TCP port used by the gateway, admin API and embedded portal. The default example uses 8088.

server.public_base_url

Canonical external URL shown in portal snippets and IDE plugin instructions. Do not include a trailing slash. Use the HTTPS URL clients can actually reach, not an internal container address.

Cursor cannot use a loopback or private base URL for Agent BYOK because its cloud path blocks private targets. Configure a public HTTPS URL for Cursor.

store

Exactly one store driver is active.

SQLite

# Embedded private store for evaluation and small single-node deployments.
store:
  # SQLite requires no external database server.
  driver: sqlite
  # Persist this file across restarts and include it in backups.
  path: data/runku-ai.db

Use SQLite for a laptop, evaluation or a single-process installation. Back up the database file together with the master key.

PostgreSQL

# Production private store for gateway configuration and usage state.
store:
  # PostgreSQL supports shared and multi-instance operation.
  driver: postgres
  # Dedicated secret DSN; this is not an upstream LLM provider URL.
  dsn: ${RUNKU_AI_STORE_DSN}

Both SQLite and PostgreSQL stores are implemented for AI Gateway. Prefer PostgreSQL for production-oriented deployments and provide the DSN through the environment rather than committing it to YAML.

The AI store is Runku's own state database; it is unrelated to customer databases connected through MCP Forge.

cache.exact

The cache is optional. It must not be treated as durable usage state.

proxy

proxy.failover_max_attempts is the global fallback attempt count. A model may define its own failover policy in stored catalog state; model-specific values take precedence.

auth

auth.enabled controls whether OIDC SSO is offered. Admin and consumer keys continue to work independently of OIDC.

# Google OIDC verification and browser portal login.
auth:
  # Require verified authentication.
  enabled: true
  oidc:
    # Google's canonical issuer.
    issuer: https://accounts.google.com
    # OAuth client ID expected in the token audience.
    audience: <oauth-client-id>
    # Public PKCE client used by the portal.
    portal_client_id: <oauth-client-id>
    # Prefer the identity token for Google's portal login flow.
    prefer_id_token: true

OIDC verifies humans accessing the admin surface. It does not define consumers, models or quotas. See Google Workspace and Entra ID and Keycloak and generic OIDC.

Environment variables

Validation and failure behavior

Runku fails startup on unknown YAML fields, invalid durations, unusable stores or missing critical secrets. Correct configuration errors instead of removing security controls to make startup succeed.