Schema Reference

The live schema is published at https://schema.vikat.ai. Add "$schema": "https://schema.vikat.ai" to your config.json for IDE autocomplete and inline validation.

This page is a concise reference for every top-level key in config.json. Click the Guide links for full field-by-field documentation.

Top-Level Keys

Key	Type	Description	Guide
`$schema`	string	Schema URL for IDE validation. Set to `"https://schema.vikat.ai"`	-
`version`	integer	Compatibility switch for empty allow-list arrays. Omit for current v2 semantics.	`version`
`source_of_truth`	string	Startup reconciliation mode for DB-backed `config.json`: `"split"` or `"config.json"`	Source of Truth
`encryption_key`	string	Optional AES-256 key (derived via Argon2id). Accepts `env.VAR` prefix and is also read from `VIKAT_ENCRYPTION_KEY`. If omitted, data is stored in plaintext.	Client
`client`	object	Worker pool, logging, CORS, auth enforcement, header filtering, MCP, compat shims	Client
`providers`	object	LLM provider API keys, network settings, concurrency	Providers
`governance`	object	Admin auth, virtual keys, budgets, rate limits, routing rules, customers, teams	Governance
`guardrails_config`	object	Content moderation providers and CEL-based rules (enterprise only)	Guardrails
`access_profiles`	array	Access profile templates for enterprise RBAC/governance controls (enterprise only)	Enterprise Governance
`cluster_config`	object	Cluster mode settings: gossip, peers, and auto-discovery backends (enterprise only)	Cluster
`config_store`	object	Configuration database backend - SQLite, PostgreSQL, or disabled (file-only mode)	Storage
`logs_store`	object	Request/response log database - SQLite, PostgreSQL + optional S3/GCS offload	Storage
`vector_store`	object	Vector database for semantic cache - Weaviate, Redis, Qdrant, Pinecone, Valkey	Storage
`plugins`	array	Opt-in plugins: `semantic_cache`, `otel`, `datadog`, custom	Plugins
`framework`	object	Model pricing catalog URL and sync interval	Framework
`mcp`	object	MCP server and tool configuration	-
`websocket`	object	WebSocket / Realtime API connection pool tuning	WebSocket
`auth_config`	object	Deprecated - use `governance.auth_config`	Client

`version`

Controls how empty arrays in allow-list fields (models, allowed_models, key_ids, tools_to_execute) are interpreted:

Value	Behaviour
`2` (default, v1.5.0+)	Empty array = deny all; `["*"]` = allow all
`1` (v1.4.x compat)	Empty array = allow all

Omitting version uses v2 semantics. Set "version": 1 only if you are migrating from v1.4.x and need the old behaviour temporarily.

`source_of_truth`

Controls how config.json is reconciled with the config store at startup.

Value	Behaviour
`"split"` (default)	File-backed rows seed or update the config store by hash, while unchanged file-backed rows preserve UI/API edits
`"config.json"`	Explicitly present file sections are authoritative and replace matching DB state on startup

Missing and empty sections behave differently when source_of_truth is "config.json". A missing section leaves DB rows untouched; a present empty section is authoritative and can prune matching DB rows.

{
  "source_of_truth": "config.json",
  "plugins": []
}

The example above makes the plugins section present and empty, so stored plugins are removed on startup. See Source of Truth & Reconciliation for section-by-section behavior.

`client`

Controls the worker pool, logging pipeline, security, and SDK shims. All fields are optional.

Field	Type	Default	Description
`initial_pool_size`	integer	`300`	Pre-allocated goroutines per provider queue
`drop_excess_requests`	boolean	`false`	Return HTTP 503 (with `Retry-After: 1`) when queue is full
`enable_logging`	boolean	`true`*	Persist request/response logs (`*` auto-enabled when `logs_store` is set)
`disable_content_logging`	boolean	`false`	Strip message content from logs
`log_retention_days`	integer	`365`	Days to retain log entries
`logging_headers`	array	`[]`	HTTP headers to capture in log metadata
`enforce_auth_on_inference`	boolean	`false`	Require a virtual key on every `/v1/*` request
`allowed_origins`	array	`["*"]`	CORS allowed origins
`allow_direct_keys`	boolean	`false`	Let callers bypass the key pool with `x-vikat-direct-key: true` + a raw provider key
`max_request_body_size_mb`	integer	`100`	Maximum request body in MB
`whitelisted_routes`	array	`[]`	Routes that bypass auth middleware
`allowed_headers`	array	`[]`	Additional headers permitted for CORS/WebSocket
`required_headers`	array	`[]`	Headers that must be present on every request
`header_filter_config`	object	-	`allowlist` / `denylist` for `x-vikat-eh-*` forwarded headers
`prometheus_labels`	array	`[]`	Custom labels for all Prometheus metrics
`compat`	object	-	SDK compatibility shims (`should_drop_params`, `convert_text_to_chat`, etc.)
`mcp_agent_depth`	integer	`10`	Max tool-call recursion depth
`mcp_tool_execution_timeout`	integer or string	`30`	Per-tool execution timeout in seconds (integer = seconds, string = Go duration like ”30s”, “2m”)
`mcp_tool_sync_interval`	integer	`10`	Tool sync interval in minutes (`0` = disabled)
`mcp_disable_auto_tool_inject`	boolean	`false`	Disable automatic MCP tool injection
`async_job_result_ttl`	integer	`3600`	TTL for async job results in seconds
`disable_db_pings_in_health`	boolean	`false`	Exclude DB connectivity from `/health`
`routing_chain_max_depth`	integer	`10`	Max routing rule chain evaluation depth
`mcp_external_client_url`	string \| EnvVar	-	Public base URL used as `redirect_uri` against upstream MCP OAuth providers; supports `"env.MY_VAR"`

Full documentation: Client Configuration.

`providers`

Keyed by provider name. Each entry contains a keys array and optional network_config, concurrency_and_buffer_size, proxy_config. Supported provider keys: openai, anthropic, azure, bedrock, vertex, gemini, mistral, groq, cohere, perplexity, xai, cerebras, deepseek, openrouter, nebius, fireworks, parasail, huggingface, replicate, ollama, vllm, sgl, elevenlabs, runway. Full documentation: Provider Setup.

`governance`

Seeds governance resources at startup. All sub-keys are optional arrays.

Sub-key	Description
`auth_config`	Admin username/password auth for the dashboard
`virtual_keys`	Scoped API tokens with provider/model allowlists
`budgets`	Spend caps in USD over a rolling window
`rate_limits`	Request and token rate limits
`customers`	Customer entities (attach budgets/rate limits)
`teams`	Team entities (attach to customers, budgets, rate limits)
`routing_rules`	CEL-based dynamic provider/model routing
`pricing_overrides`	Scoped per-model pricing overrides
`model_configs`	Per-model rate limit and budget configurations

Full documentation: Governance.

`guardrails_config`

Enterprise-only. Two sub-keys: guardrail_providers (array) and guardrail_rules (array). Full documentation: Guardrails.

`access_profiles`

Enterprise-only. Defines access profile templates that can later be attached to roles/users.

{
  "access_profiles": [
    {
      "name": "platform-default",
      "description": "Default platform profile",
      "is_active": true,
      "tags": ["platform", "default"],
      "provider_configs": [
        {
          "provider_name": "openai",
          "all_models_allowed": false,
          "allowed_models": ["gpt-4o", "gpt-4o-mini"]
        }
      ],
      "mcp_servers": [
        { "mcp_server_id": "github" }
      ],
      "mcp_tool_overrides": [
        { "mcp_client_id": "github", "tool_name": "create_pull_request", "action": "include" }
      ]
    }
  ]
}

`cluster_config`

Enterprise-only clustering settings for multi-node deployments.

Sub-key	Description
`enabled`	Enables cluster mode
`region`	Region label used by enterprise clustering
`peers`	Static peer list (`host:port`)
`gossip`	Gossip/memberlist port + liveness thresholds
`discovery`	Auto-discovery configuration (`kubernetes`, `dns`, `udp`, `consul`, `etcd`, `mdns`)

Full documentation: Cluster.

`config_store`, `logs_store`, `vector_store`

Storage backends. Each has enabled (boolean), type (string), and config (object).

Store	Types
`config_store`	`"sqlite"`, `"postgres"`
`logs_store`	`"sqlite"`, `"postgres"` (+ optional `object_storage` for LLM and MCP logs)
`vector_store`	`"weaviate"`, `"redis"`, `"qdrant"`, `"pinecone"` (`"redis"` also covers Valkey-compatible endpoints)

Full documentation: Storage.

`framework`

Controls model pricing catalog sync and the live model-list refresh:

{
  "framework": {
    "pricing": {
      "pricing_url": "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json",
      "pricing_sync_interval": 86400,
      "model_list_refresh_interval": 3600
    }
  }
}

Field	Default	Description
`pricing.pricing_url`	LiteLLM catalog	URL of a model pricing JSON file
`pricing.pricing_sync_interval`	`86400`	Pricing datasheet sync interval in seconds (minimum: `3600`)
`pricing.model_list_refresh_interval`	`3600`	Live model-list refresh interval in seconds (minimum: `300`, maximum: `2592000`)

Two intervals, two catalogs

The gateway keeps two separate views of “which models exist”:

Pricing datasheet (pricing_sync_interval): the static price/capability table fetched from pricing_url. A sync that cannot reach the URL serves the cached database rows or the datasheet bundled in the binary instead; that is logged as such and retried about 15 minutes later rather than after a full interval, so a node whose egress comes back picks up the real datasheet quickly.
Live model lists (model_list_refresh_interval): a snapshot of each configured provider’s own GET /v1/models, taken per key at boot and whenever a provider or key is created or updated. This is what the dashboard, bare-model provider resolution and virtual-key “all models” gating read. It is re-fetched in the background every model_list_refresh_interval seconds, so a model a provider starts listing becomes routable within one interval instead of after the next key edit or restart. A provider whose list endpoint fails keeps its previous snapshot (it is never emptied), and each cycle logs one line naming the providers refreshed, failed and skipped and any model ids that appeared. Values below 300 are clamped to 300 and values above 2592000 (30 days) to 2592000, each with a warning; 0 or absent means 3600.

Both intervals are editable at runtime from Settings → Model Settings (or PUT /api/config); a change takes effect without a restart. To refresh on demand:

POST /api/models/refresh re-fetches every provider’s live model list now and returns per-provider counts plus the ids that were new ({"refreshed": 3, "failed": 0, "skipped": 1, "new_models": ["anthropic/claude-opus-5"], "providers": [...]}).
POST /api/pricing/force-sync (the Force Sync Now button) syncs the pricing datasheet and then runs the same live model-list refresh.

`websocket`

Optional tuning for the WebSocket gateway (Responses API WebSocket mode, Realtime API). WebSocket is always enabled.

{
  "websocket": {
    "max_connections_per_user": 100,
    "transcript_buffer_size": 100,
    "pool": {
      "max_idle_per_key": 50,
      "max_total_connections": 1000,
      "idle_timeout_seconds": 600,
      "max_connection_lifetime_seconds": 7200
    }
  }
}

Field	Default	Description
`max_connections_per_user`	`100`	Max concurrent WebSocket connections per user
`transcript_buffer_size`	`100`	Transcript entries buffered for Realtime API mid-session fallback
`pool.max_idle_per_key`	`50`	Max idle upstream connections per provider/key
`pool.max_total_connections`	`1000`	Max total idle upstream connections
`pool.idle_timeout_seconds`	`600`	Evict idle connections after this many seconds
`pool.max_connection_lifetime_seconds`	`7200`	Max lifetime of any upstream connection

Minimal Valid Config

{
  "$schema": "https://schema.vikat.ai",
  "encryption_key": "env.VIKAT_ENCRYPTION_KEY",
  "providers": {
    "openai": {
      "keys": [
        { "name": "primary", "value": "env.OPENAI_API_KEY", "models": ["*"], "weight": 1.0 }
      ]
    }
  },
  "config_store": { "enabled": false }
}

Platform specific guides

Config as Code

Enterprise Deployment

Common setup instructions

Schema Reference

Top-Level Keys

`version`

`source_of_truth`

`client`

`providers`

`governance`

`guardrails_config`

`access_profiles`

`cluster_config`

`config_store`, `logs_store`, `vector_store`

`framework`

Two intervals, two catalogs

`websocket`

Minimal Valid Config

​Top-Level Keys

​version

​source_of_truth

​client

​providers

​governance

​guardrails_config

​access_profiles

​cluster_config

​config_store, logs_store, vector_store

​framework

​Two intervals, two catalogs

​websocket

​Minimal Valid Config

Top-Level Keys

`version`

`source_of_truth`

`client`

`providers`

`governance`

`guardrails_config`

`access_profiles`

`cluster_config`

`config_store`, `logs_store`, `vector_store`

`framework`

Two intervals, two catalogs

`websocket`

Minimal Valid Config