ModelWarden operator guide

Start here

One local control point, four separate proofs

A green /health proves only that the process is serving. Separately verify client authentication and upstream routing. To prove tool-call protection, use a harmless controlled tool-call fixture, check the actual enforcement result, correlate the configured audit/event evidence, and confirm what the intended client receives. A normal text reply is not that proof.

For AI agents and automation

Agent-safe operating contract

Treat every observation as belonging to one exact state. Source support, a released download, the binary currently running, its saved JSON, and its effective licensed policy can all differ. Name the state behind a claim instead of collapsing them into “ModelWarden supports it.”

Preflight before a mutation

1. Identify the exact process, its own --version output, executable hash, active --config path, listener, and license lifecycle. Check for an existing listener before starting another instance. Do not assume the default path or port when startup flags are present.
2. Start with masked or read-only surfaces. Never print tokens, credential-reference contents, provider secrets, session cookies, or a raw secret-bearing config into logs or chat.
3. Preserve an owner-only copy of the active config and every referenced credential source needed for rollback on a trusted filesystem, never in a shared temporary directory. A JSON file without its adjacent <config-filename>.credentials directory may be incomplete.
4. Use the dashboard UI for mutations unless the exact route-specific API contract for this binary version has been reviewed. Refresh immediately before the change and let the UI carry its current revision, authentication, and origin checks. There is no general public “admin write API” contract; do not invent one or replay a captured request.
5. Read the state back after every write. A timeout or lost response is ambiguous: the operation may have committed.
6. Verify the affected layer, then audit/event truth, dashboard truth, and the intended client. A 200 from /health is not enforcement evidence.

pgrep -af '(^|/)mw-proxy([[:space:]]|$)'
ss -ltn 'sport = :3758'
ps -p PID -o pid=,lstart=,args=
readlink -f /proc/PID/exe
/proc/PID/exe --version
sha256sum /proc/PID/exe

ModelWarden does not expose a durable public instance ID. Bind an observation to the base URL, observed executable/version/hash, command line, listener, and active configuration. A PID, port, configuration revision, or license reference is useful evidence but is not a permanent identity by itself.

Authoritative reads before a write

Use the narrowest redacted status surface for the family you intend to change. Administrative reads require the authority described below and return no reusable secret bytes.

Authentication authority by surface

Dashboard API routes accept a valid browser session or administrator bearer unless a route is explicitly bearer-only. Browser-session writes must remain same-origin. A non-browser bearer client should omit Origin unless it can send the exact dashboard origin; a bearer does not bypass origin checks. After a write waits for the configuration lock, ModelWarden revalidates its original authority, so a concurrent credential rotation can turn it into 401 authentication_required.

Classify every write result

After an ambiguous credential or license operation, read in this order: /admin/api/v1/credentials, /admin/api/v1/license/credentials, /admin/api/v1/license, and—if providers or routes were involved—/admin/api/v1/provider-config. Compare saved and runtime revisions before choosing a new action.

Preferred inert probes

• Use public GET /v1/models to inspect effective route discovery without inference spend. It does not authenticate the client key.
• After confirming client authentication is enabled, send a structurally valid inference request with an intentionally invalid placeholder key and expect 401 before upstream forwarding. If authentication is disabled, that request is not an inert rejection probe. Prove successful authentication only through a fake/test or explicitly approved upstream.
• Use Debug, where entitled, to evaluate a harmless synthetic tool call without executing it. Evaluation can contact the configured judge and incur cost; the mounted Debug evaluator does not create a normal enforcement Audit event.
• Use mw-proxy --check-allocation … to inspect saved command decisions without writes or command execution.
• For routing proof, send one ordinary text prompt through a fake or explicitly approved upstream with client tools disabled. Verify enforcement separately with an inert tool-call fixture. Never execute a destructive command merely to prove that a detector blocks it.

Security-critical

Credentials: three jobs, three secrets

In that legacy mode, the human signs in with the selected password or raw client key. The legacy administrator bearer is its SHA-256 hex digest, not the raw value. Protecting credentials can deliberately retain that bearer for compatibility, so protection alone is not rotation.

1. Open Config → Credentials while the dashboard is still accessible.
2. Choose Protect credentials. When authentication was disabled, the form asks for a new password and may show a new administrator token once. In legacy mode it instead preserves the current dashboard sign-in and administrator bearer for compatibility. Either save ends the current browser session.
3. For the legacy path, sign in once more with the same password or raw client key, choose Change dashboard password, set a distinct password, and sign in again. This second save also ends current sessions. Do not rotate the client key until this separate password works.
4. If the page says the administrator token was derived from a dashboard password or proxy client key, rotate it when API clients are ready. Rotation is mandatory when the prior credential was exposed or its provenance is uncertain. Save the one-time result, update every admin API client, and confirm the old bearer no longer authenticates without logging either token.
5. Only then protect, import, or rotate the proxy client key.

Changing the dashboard password or administrator token invalidates current browser sessions. After dashboard protection, client-key replacement is separate from browser sign-in; it affects new proxy requests, so update every client that uses the old key.

Platform boundary: protected local credential migration is supported and documented for the current released Linux builds. Do not infer Windows or macOS support from a platform path in this guide; use the Downloads page and that build's credential-status capability before planning a migration.

Recover dashboard access

If neither the expected password nor the former client key works, stop retrying. Recovery changes live authentication: an AI agent must remain read-only until the operator approves the exact instance and exact snapshot.

1. Use the identity checks above to bind the PID, executable, listener, and active config path. After approval, stop that exact process; never stop by a broad name match.
2. On a trusted filesystem, create an owner-only recovery copy of the current failed config, its adjacent <config-filename>.credentials directory, and every neighboring backup. Preserve them as one set. Never use a shared temporary directory, paste their contents into chat, or delete/edit the credential files.
3. Choose a <config-name>.provider-backup-… candidate whose basename matches the active config and whose timestamp predates the failed change. Do not choose “the newest” blindly. Confirm every referenced credential source needed by that candidate still exists; stop if the config, timestamp, ownership, or source pairing is ambiguous.
4. Preserve the active file's owner and mode. Use the operator's OS/service procedure to replace the config atomically on the same filesystem. Do not combine a config snapshot with unrelated credential material.
5. Restart the same executable with the same --config path. Confirm the expected listener and /health, sign in with the credential belonging to that snapshot, and review dashboard password, admin-token authority, and client-key state under Config → Credentials before any further mutation.

There is no safe unattended “reset auth” shortcut. If the exact target, matching snapshot, file ownership, atomic replacement procedure, or external credential source is uncertain, preserve everything and contact support. Do not remove dashboard.authentication or hand-edit password verifiers.

Configuration

Paths, dashboard editing, and raw JSON

Configuration is JSON. With no arguments, mw-proxy uses the platform path and creates a valid 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

A missing explicit path requires --init. The optional TUI selects basic startup settings; the dashboard remains the clearer editor for a running installation.

Dashboard editing

• Providers owns upstream identities, credentials, formats, model discovery, health, and basic route assignment.
• Routing owns aliases, ordered providers, schedules, failover, client snippets, and plugin downloads.
• Judge owns contextual review providers and tuning. Config owns safety, network, operations, and advanced JSON.
• Credentials is the safe place to move secrets into owner-only files or external references.

Use the narrow dashboard controls, which validate their candidate, enforce licensed feature gates and reject stale revisions where required by that mutation family. Ordinary policy changes can publish to the running process; see Apply and restart for exceptions. Check the saved result and backup inventory. If a response is lost, reload before retrying: the first operation may already have committed.

{
  "version": "0.1.0",
  "enabled": true,
  "heuristics_only": true,
  "api_key": "replace-with-a-client-key",
  "route": {
    "my-model": [{
      "name": "primary",
      "endpoint": "https://provider.example/v1",
      "api_key": "replace-with-provider-key",
      "format": "openai",
      "priority": 1,
      "model": "upstream-model"
    }]
  },
  "proxy": { "host": "127.0.0.1", "port": 3758 }
}

Routing

Providers, routes, aliases, and failover

A route key is the model name sent by the client. A route points to one or more upstream provider bindings, ordered by priority. A binding can map that route to a different upstream model.

For a first route, open Providers → Add Endpoint, configure the endpoint and upstream model, then use the model's Assign action. Configure contextual review separately under Judge → Provider chain → Add Provider; assigning a route does not also configure a judge.

Provider formats

openai, openai_responses (alias responses), anthropic, gemini, bedrock, ollama, and mcp.

Basic route

Every profile can configure a one-provider route.

Ordered failover

Professional and Enterprise can add multiple providers, schedules, and aliases where entitled. Retries are bounded and stop once response bytes have started.

Image-aware routing

Capability-aware selection can keep image requests away from bindings that do not support them.

Use provider health as evidence about the upstream connection, not as proof that safety evaluation is active. Test one normal request through the exact route and client you intend to use.

Clients

Connect clients without sharing provider secrets

Clients receive only the ModelWarden base URL, a route key, and the proxy client API key. Provider credentials stay in ModelWarden.

curl --fail http://127.0.0.1:3758/v1/models

read -rsp 'ModelWarden client key: ' MODELWARDEN_API_KEY
export ANTHROPIC_BASE_URL=http://127.0.0.1:3758
export ANTHROPIC_API_KEY="$MODELWARDEN_API_KEY"
claude --model my-model

model = "my-model"
model_provider = "modelwarden"

[model_providers.modelwarden]
name = "ModelWarden"
base_url = "http://127.0.0.1:3758/v1"
env_key = "MODELWARDEN_API_KEY"
wire_api = "responses"
supports_websockets = false

Protection

Know which safety mode is actually active

Configure these under Config → Safety → General. on_error defaults to allow and applies after a judge attempt; an unjudged Flag follows unjudged_flag_action, also allow by default. For sensitive use, review both settings instead of assuming one fail-closed switch covers every path.

No available judge: current effective policy falls back to heuristics-only when no judge can be used. Free and Professional use your own judge credentials; Enterprise Managed uses managed review only when the signed contract supplies it. Check the effective policy, not just the saved toggle.

Decisions

Judge review, human approvals, and allocations

• Judge: configure a separate provider chain under Judge. Review can cover every non-trusted tool or only heuristically flagged calls.
• Approvals: entitled HTTP flows can hold an Ask decision for a human response. Holds have a timeout, concurrency bound, and expiry action.
• MCP stdio: has no in-band human hold surface. An Ask is denied, so design MCP policy to make safe Allow/Deny decisions without waiting.
• Allocations: saved exact, per-part, and template command decisions are enforced when enabled. They can displace ordinary flags, but never mandatory hard Blocks.

The typed approvals default is hold, while an unentitled effective Free configuration projects approval flow off. Always read the effective controls shown by the dashboard for the active license.

Evidence

Audit, replay, errors, and monitoring

Use the surfaces in this order when proving behavior:

1. Proxy result: did the request allow, deny, ask, or fail?
2. Audit/event truth: does the event identify route, tool, heuristic/judge outcome, and enforcement?
3. Dashboard truth: does Audit, Logs, or Errors display the same event?
4. Client smoke: does the intended client behave correctly end to end?

Audit persistence depends on the effective licensed configuration. Hash-chained audit is opt-in, disabled by default, and requires a signing-key path. Session replay persistence is also opt-in; set retention and disk limits deliberately. Additional pages cover tracing, alerts, uptime, cron monitoring, profiling, source control, issue tracking, and provider health.

No row is not a verdict. Plain text may contain no tool call to evaluate, allowed-event logging can be off, and Debug evaluation deliberately skips enforcement Audit recording. Correlate a controlled tool-call result with the configured event source before diagnosing missing protection.

Privacy

Secret redaction: what is hidden from the logs

ModelWarden hides secrets in tool arguments before an audit record is written. The record keeps the tool, the decision and the useful values; each secret becomes <redacted>. It works out of the box.

Fields hidden by name

A field is hidden when its name is, or ends with, a word such as password, secret, API key, access token, refresh token, authorization, cookie or private key. Case and punctuation don't matter, so DEPLOY_API_KEY and db_password are both hidden.

Secret-looking values anywhere in a command

• Private-key blocks, such as -----BEGIN PRIVATE KEY-----.
• Provider keys: sk-…, GitHub ghp_… and github_pat_…, GitLab glpat-…, Slack xox… and AWS AKIA….
• Login tokens (eyJ…).
• Bearer … and Basic … headers.
• token=… and password: … pairs, and flags such as --token ….
• Passwords inside URLs, such as postgres://user:pass@host.
• Secret URL parameters, such as ?token=….
• Cookie headers.

Add your own

"redact_keys": ["ticket_ref"]

This hides any field whose name starts or ends with ticket_ref, ignoring case and punctuation.

Changes apply to new records. Records already written stay as they are, and the dashboard applies the same rules again whenever it shows them.

Current source

Capability map

Availability varies by signed entitlement and purchase type. See Features for the public profile comparison; the running License and Config pages show what this installation can actually use.

Entitlements

License activation, heartbeat, and offline behavior

Paste the complete signed token on the local License page. The proxy prefers the trusted portal URL signed into the token; set license.heartbeat_endpoint only when that URL is absent. Leaving the machine ID blank on first activation lets the proxy create a stable local identity.

• Signed issued_at and expires_at describe token validity; they do not by themselves redefine lifetime ownership.
• Activation receipts, concurrent-operation limits, heartbeat budgets, purchase type, and grace rules all participate in effective access.
• Free, Professional, and Enterprise BYOK keep provider and judge credentials local. Enterprise Managed can receive contracted managed material from the portal.

When licensing looks wrong, inspect the License page's lifecycle and entitlement details before editing config. A heartbeat success alone does not prove a model request or safety feature is active.

Contract-authorized offline operation is an Enterprise BYOK entitlement, not a promise of unlimited disconnected use. It still requires valid token/activation-receipt state and trusted-time checks; upstream models may still need network access. Enterprise Managed retains its separate heartbeat and grace policy. Disabling heartbeat is not a way to acquire offline entitlement.

Release state

Check for an update without confusing source with a download

About → Check for Updates is advisory. It asks the configured portal for the running binary's recognized artifact platform, when available, validates the returned release description, and shows a download link only when that description is internally consistent and uses a safe HTTP(S) URL. The check contacts that portal and may refresh an owner-only local update-cache sidecar; it never changes the main config, downloads, installs, replaces, or restarts the binary.

• The check uses the portal URL from effective license state, falling back to the configured heartbeat endpoint. Without either source, it reports that no portal URL is configured.
• Results are isolated by portal origin and exact platform and cached briefly. A malformed, contradictory, oversized, withdrawn, or legacy response cannot become a trusted download link; a previously seen version may remain only as stale diagnostic text.
• The signed-in Downloads page remains the artifact authority. A platform name in current source is not proof that a package exists, was natively tested, is signed or notarized, or is available to this account.

Current limitation: local source recognizes Linux x86-64/ARM64, Windows x86-64/ARM64, and macOS Intel/Apple-Silicon/Universal 2 release identities. That source support does not claim that Windows or macOS artifacts have completed native build, packaging, signing, notarization, installation, or runtime acceptance. Use Downloads for the actual release set.

Change control

What applies now, and what needs a restart

Config writers retain owner-only neighboring snapshots according to their mutation path; a no-op is not a new backup. Check the backup inventory rather than assuming every dashboard action created one. Ordinary config backups are bounded, so preserve a separate owner-only config/credential set before a bulk migration.

Fast diagnosis

Start with the symptom

Automation

CLI reference and repeatable fleets

mw-proxy [--config PATH] [--host HOST] [--port PORT] [--init] [--tui]
mw-proxy models-dev import [--config PATH]
mw-proxy mcp [--config PATH] -- <server command…>
mw-proxy --check-allocation <COMMAND> [--config PATH] [--route KEY] [--tool NAME]
mw-proxy auth openai login …   # experimental; explicit OAuth endpoints required

• models-dev import fetches and persists catalog advertisements; a running proxy uses the CLI import after restart, while the authenticated dashboard API can import at runtime.
• --check-allocation is inert: it inspects saved matches without executing the command.
• mcp -- launches a configured stdio child and gates tool calls through the same pipeline. A disabled gateway is transparent passthrough.

Fleet deployment

1. Render a reviewed JSON file and credential sources with owner-only permissions. Keep machine identities and machine-specific secrets unique where required.
2. Start one canary with an explicit path: mw-proxy --config /etc/modelwarden/config.json.
3. Verify process, public model discovery, client authentication, provider response and license lifecycle separately. Then correlate an inert enforcement fixture with its configured event evidence, dashboard display and intended client.
4. Roll out in batches while watching Errors, Audit, provider health, and client success. Retain the previous config plus every referenced credential file for rollback.