Configuration Reference

Config paths and CLI selection

Configuration is JSON only. With no arguments, mw-proxy uses the platform config path and creates a default file when it is missing.

Linux: $XDG_CONFIG_HOME/modelwarden/config.json, falling back to ~/.config/modelwarden/config.json.
macOS: ~/Library/Application Support/modelwarden/config.json.
Windows: %APPDATA%\modelwarden\config.json.

mw-proxy
mw-proxy --config /absolute/path/config.json
mw-proxy --init --config /absolute/path/config.json
mw-proxy --tui

--init creates a default file at an explicit missing path. --tui is an optional terminal wizard for selecting basic safety, judge, and audit settings.

Dashboard editing

The local dashboard at http://127.0.0.1:3758/admin/ is the preferred editor for an interactive installation.

Providers manages upstream endpoints, credentials, formats, health, and basic route assignment.
Routing manages paid multi-provider ordering, failover, client snippets, and the OpenCode plugin.
Judge manages judge providers and review behavior.
Config exposes common form fields plus the complete raw JSON document.

Every save parses the complete document, validates schema and license gates, persists it to the active config path, and updates the running policy state.

Minimal schema

{
  "version": "0.1.0",
  "enabled": true,
  "heuristics_only": true,
  "route": {
    "gpt-5.4": [{
      "name": "primary-openai",
      "endpoint": "https://api.openai.com/v1",
      "api_key": "Bearer sk-...",
      "format": "openai",
      "priority": 1,
      "model": "gpt-5.4"
    }]
  },
  "judge": {
    "provider_chain": [],
    "review_policy": "flagged_only"
  },
  "audit": {
    "enabled": true,
    "persist_enabled": false,
    "log_dir": ".modelwarden/logs",
    "retention_days": 90,
    "log_allowed": false,
    "log_denied": true
  },
  "dashboard": {
    "host": "127.0.0.1",
    "port": 3758,
    "password": ""
  },
  "proxy": {
    "host": "127.0.0.1",
    "port": 3758,
    "tls": { "enabled": false, "cert_path": "", "key_path": "" },
    "insecure_allow_remote_http": false
  },
  "license": {
    "enabled": true,
    "online": true,
    "heartbeat_endpoint": "https://modelwarden.ai/api/v1/license/heartbeat",
    "license_token": "mwf_...",
    "machine_id": ""
  }
}

The default generated file includes every supported section. Use the dashboard’s raw JSON mode when configuring advanced policy, alerting, monitoring, integrations, or wrapper options not shown in the common form.

Providers, routes, and judge providers

route is an object keyed by the model name requested by the client. Each value is an ordered provider list.

name: Stable provider identifier used by the dashboard.
endpoint: Upstream API base URL.
api_key: Credential sent to the upstream. Keep the config file private.
format: openai, anthropic, gemini, ollama, bedrock, or mcp.
priority: Provider order within a route; lower values are tried first.
model: Optional upstream model override.

Free supports basic routes with one provider each. Multiple providers on the same route require Professional or Enterprise. Judge providers live under judge.provider_chain and are separate from request routing, although the dashboard can copy a configured provider into the judge chain.

License, heartbeat, and managed credentials

Paste the complete signed token into license.license_token. Saving automatically enables license enforcement when a token is present.

The proxy prefers a trusted portal URL signed into the token. When one is not present, set license.heartbeat_endpoint to https://modelwarden.ai/api/v1/license/heartbeat. Startup and periodic heartbeats can refresh the token and managed provider data when the profile is entitled.

Free, Professional, and Enterprise BYOK keep provider and judge keys in local configuration. Only Enterprise Managed receives managed judge/provider material from the portal.

Apply and restart rules

Change path	Persisted	Applied now	Restart required
Dashboard policy, providers, judge, audit, and license fields	Yes	Yes	No
Dashboard proxy host, port, or TLS fields	Yes	Listener stays unchanged	Yes
Direct file edits outside the dashboard	Already on disk	No file watcher	Yes
CLI `--host` or `--port` overrides	No	At process start	Start-time only

Restart required: The running socket cannot move when proxy.host, proxy.port, or TLS settings change.

Enterprise fleet deployment

Use an explicit path and deploy the same reviewed JSON shape through your configuration-management system. Machine IDs and machine-specific credentials should remain unique where required.

sudo install -d -o root -g modelwarden -m 0750 /etc/modelwarden
sudo install -o modelwarden -g modelwarden -m 0600 config.json /etc/modelwarden/config.json

sudo -u modelwarden /usr/local/bin/mw-proxy \
  --config /etc/modelwarden/config.json

sudo systemctl enable --now modelwarden
curl --fail http://127.0.0.1:3758/health
curl --fail http://127.0.0.1:3758/v1/models

Rollout procedure

Render and validate the candidate on one canary host by starting the binary with the explicit config path.
Verify health, model discovery, provider status, license state, and a normal audited request.
Roll out in batches and monitor Errors, Audit, provider health, and client request success.
Keep the previous config artifact. Roll back by restoring it and restarting the service.

ModelWarden does not interpolate environment variables inside JSON values. Supply fully rendered secrets through a protected deployment artifact, or use Enterprise Managed provider credentials where contracted.

Dashboard for one machine. Files for repeatable deployments.