Configuration | Routeplane Docs

A self-hosted gateway reads three things at startup: an environment for the listen port and provider credentials, a virtual-key registry that maps your keys to those credentials, and a set of optional config files for routing policies, prompts, and agents. Everything has a sensible default, the only thing you must supply is at least one provider key.

Environment variables

Variable	Purpose
`PORT`	Port the gateway listens on. Default `8080`.
`OPENAI_API_KEY`	OpenAI credential, referenced from the key registry as `env:OPENAI_API_KEY`.
`ANTHROPIC_API_KEY`	Anthropic credential.
`GEMINI_API_KEY`	Google Gemini credential.
`AZURE_OPENAI_API_KEY`	Azure OpenAI credential. Paired with the four `AZURE_OPENAI_*` settings below.
`AZURE_OPENAI_ENDPOINT`	Azure OpenAI resource endpoint.
`AZURE_OPENAI_DEPLOYMENT`	Deployment name to target.
`AZURE_OPENAI_API_VERSION`	API version string.
`AZURE_OPENAI_REGION`	Region, also used as a residency signal for sovereign routing.
`RP_KEYS_FILE`	Path to the virtual-key registry. Default `configs/keys.json`.
`RP_KEYS_JSON`	The key registry inline as a JSON string, useful when a platform injects config as an env var instead of a file.
`RP_ROUTING_POLICIES_FILE`	Path to saved routing policies. Default `configs/routing-policies.json`.
`RP_PROMPTS_FILE`	Path to the prompt registry. Default `configs/prompts.json`.
`RP_AGENTS_FILE`	Path to the agent registry. Default `configs/agents.json`.

Advanced & platform variables. The gateway also reads variables for runtime feature flags (UNLEASH_*), managed identity (IDENTITY_ENDPOINT, Entra JWKS), and the control-plane port. These are for the managed/platform deployment and are not required to self-host the data plane, leave them unset.

The virtual-key registry

Callers never send a provider key. They send a Routeplane virtual key (rp_-prefixed) in the x-routeplane-api-key header; the registry resolves it to the real provider credentials, the tenant, the tier, and any per-key guardrails. Provider keys are referenced indirectly with env: so secrets stay in the environment, not in the JSON.

jsonconfigs/keys.json

{
  "keys": [
    {
      "name": "Default Development Key",
      "routeplane_key": "rp_dev_REPLACE_ME",
      "provider_keys": {
        "openai": "env:OPENAI_API_KEY",
        "anthropic": "env:ANTHROPIC_API_KEY",
        "gemini": "env:GEMINI_API_KEY",
        "azure_openai": "env:AZURE_OPENAI_API_KEY"
      }
    }
  ]
}

A key can carry more than credentials. The optional fields let one registry serve multiple tenants and tiers:

tenant_id, attributes usage and isolates state per tenant.
tier and capability_overrides, the entitlement seam: features are config, not forks. See Authentication.
guardrails, per-key before_request / after_request checks (regex or webhook, each with an action like observe or deny). See Guardrails.

The image bundles configs/keys.example.json with worked examples of all of these, use it as your starting point, then mount your own keys.json over it.

Optional config files

The image bundles an .example.json for each under configs/; mount your own over it, or point the matching RP_*_FILE variable at a path you mount in:

File	Defines
`configs/keys.json`	Virtual keys → providers, tenants, tiers, per-key guardrails. Required.
`configs/routing-policies.json`	Saved declarative routing configs, referenceable by name. See Routing configs.
`configs/prompts.json`	Versioned, labelled prompts for the prompt registry.
`configs/agents.json`	Agent definitions for agent-scoped governance.

Keep secrets out of version control. .env and configs/keys.json are git-ignored by default. Commit the .example.json files, never the real ones.