Configuration Reference

Knull uses a YAML-based configuration file. It supports environment variable substitution using ${VAR_NAME} or $VAR_NAME syntax.

Top-Level Schema

database:   # Persistence settings
gateways:   # Listener settings
models:     # Backend LLM settings
apiKeys:    # Client authentication
policies:   # Budget and access rules
mcp:        # Model Context Protocol settings
redis:      # (Optional) HA state settings

Gateways

Defines the ports Knull listens on for AI traffic.

Field	Type	Description
`name`	string	Unique name for the gateway.
`port`	int	Port to listen on (default: `1975`).

Models (AIServiceBackend)

Defines the backend LLM providers.

Field	Type	Description
`id`	string	Unique identifier used by clients in the `model` field.
`provider`	string	One of: `azure`, `openai`, `anthropic`, `aws_bedrock`, `aws_anthropic`, `gcp_vertex`, `cohere`, `openai_compatible`.
`endpoint`	string	The base URL or hostname of the provider.
`apiKey`	string	(Optional) API key for authentication.
`backendName`	string	(Optional) Custom backend name for routing.
`awsRegion`	string	Required for `aws_*` providers.
`awsAccessKey`	string	AWS Access Key.
`awsSecretKey`	string	AWS Secret Key.
`assumeRoleArn`	string	(Optional) IAM Role ARN to assume for Bedrock access.
`gcpProject`	string	Required for `gcp_*` providers.
`gcpLocation`	string	Required for `gcp_*` providers.
`gcpAccessToken`	string	GCP Access Token.
`alias`	string	(Optional) Maps a client-side model name to this backend.
`schema`	object	(Optional) Custom API schema configuration.
`auth`	object	(Optional) Backend authentication policy.

Versioned API Schema

Customize how Knull communicates with the backend.

models:
  - id: gemini-openai
    provider: openai_compatible
    endpoint: ai.google.dev
    schema:
      name: OpenAI
      prefix: /v1beta/openai

Field	Type	Description
`name`	string	Schema name (e.g., `OpenAI`, `Anthropic`).
`prefix`	string	(Optional) URL prefix for the API (e.g., `/v1beta/openai`).
`version`	string	(Optional) API version identifier.

API Keys

Defines keys used by your applications to authenticate with Knull.

apiKeys:
  - id: team-alpha
    keyVal: sk-knull-alpha-xxxxxx
    name: "Alpha Team Key"
    owner: "alpha@example.com"

Policies

Maps API Keys to Models and sets budgets.

Field	Type	Description
`id`	string	Unique policy ID.
`apiKeyId`	string	Reference to an `apiKeys.id`.
`modelId`	string	Reference to a `models.id`.
`allow`	boolean	Set to `false` to block access.
`budgetLimit`	int	Max tokens allowed for this key/model pair.

Full Example

database:
  type: sqlite
  path: "./knull.db"
 
gateways:
  - name: public-gw
    port: 1975
 
models:
  - id: gpt-4o
    provider: azure
    endpoint: ${AZURE_HOST}
    apiKey: ${AZURE_KEY}
  - id: claude-3-5
    provider: anthropic
    apiKey: ${ANTHROPIC_KEY}
 
apiKeys:
  - id: app-1
    keyVal: sk-knull-app1-secret
 
policies:
  - id: app1-gpt4
    apiKeyId: app-1
    modelId: gpt-4o
    budgetLimit: 50000

Features Providers