ModelWarden Quickstart

Step 1

Download the build for this machine

For the current released support path, sign in to the customer portal, open Dashboard → Downloads, and choose the covered Linux build shown for your account. Check the machine architecture first:

uname -m
# x86_64  → Linux x86-64
# aarch64 → Linux ARM64

In Bash, open the folder containing the downloaded executable. Set BINARY to its actual filename, for example ./mw-proxy or ./mw-proxy-arm64. For an archive, compare its checksum before extracting, then select the extracted executable. Renaming a file does not change its architecture.

BINARY=./mw-proxy
sha256sum "$BINARY"

Stop if the checksum differs from Downloads. Only after it matches, allow execution and check the version:

chmod +x "$BINARY"
"$BINARY" --version

Step 2

Start the proxy on loopback

In the same Bash terminal, start the downloaded executable:

"$BINARY"

A first run creates a missing default configuration and listens on 127.0.0.1:3758. An existing configuration is reused, including its listener settings. Follow the address in the startup output; do not start a second proxy on an occupied port.

Leave that terminal running. In a second terminal, check the default listener:

curl --fail http://127.0.0.1:3758/health

"$BINARY" --init --config /absolute/path/config.json

Step 3

Protect dashboard access, then activate the license

Open the proxy's local dashboard at http://127.0.0.1:3758/admin/. Keep it on loopback. Your customer-portal password is not the local dashboard password.

Dashboard password

Your browser sign-in to the local dashboard.

Proxy client API key

Your coding client's credential for model requests.

Admin API token

Privileged automation only. Never use it as a client key.

1. For a new setup, open Config → Credentials → Protect credentials. Set a dashboard password, save the one-time admin token privately, and sign in again. Use a password distinct from the client key.
2. Open License. Paste the complete token from Customer Dashboard → Licenses.
3. Leave the heartbeat endpoint blank when the signed token already supplies its trusted portal URL. Otherwise use https://modelwarden.ai/api/v1/license/heartbeat. Leave the machine ID blank on first activation.

Locked out already? Do not guess credentials repeatedly. Stop the proxy and follow Recover dashboard access.

Step 4

Connect a model and a judge

Open Providers → Add Endpoint. Enter your provider's endpoint, format, credential, and upstream model. Save it, then use the model's Assign action to create the client-facing route my-model.

• The route key is the model name your client sends to ModelWarden.
• The upstream model is the model name ModelWarden sends to the provider.
• Start with one provider. Professional and Enterprise can add ordered providers, schedules, aliases, and failover from Routing.

Configure contextual review

Open Judge → Provider chain, select a judge-eligible model, and choose Add Provider. Free and Professional use your own judge credentials. Enterprise Managed uses a managed judge only when your signed contract includes it and it is configured.

No judge configured? Current source falls back to heuristics-only operation when no judge is available. A working model route does not mean contextual judging is active. Judge calls can incur provider costs.

Step 5

Create a client key and connect one client

Return to Config → Credentials → Generate new proxy key after separating dashboard access. Store the displayed key privately and update every client using an older key. The result panel clears when you leave; authenticated Copy Config on Providers or Routing can also retrieve the active client key.

Use this proxy key as MODELWARDEN_API_KEY, never your upstream provider key or admin token. Run the following in the second Bash terminal, then start your client from that terminal.

Bash: read the key without echoing it. Do not paste it into command history, logs, or chat.

read -rsp 'ModelWarden client key: ' MODELWARDEN_API_KEY
export MODELWARDEN_API_KEY
printf '\n'

export ANTHROPIC_BASE_URL=http://127.0.0.1:3758
export ANTHROPIC_API_KEY="$MODELWARDEN_API_KEY"
claude --model my-model

Step 6

Verify each layer, not only health

curl --fail http://127.0.0.1:3758/health

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

1. Process: /health succeeds.
2. Routing catalog: /v1/models includes your route key. This catalog endpoint is public and does not prove that the client key is correct.
3. Client authentication and upstream: with a fake/test or explicitly approved provider, use the intended client key to send one harmless text-only prompt with tools disabled. A real provider may incur cost. Success proves the key was accepted and the route reached its upstream. As a negative check, a deliberately invalid placeholder key must receive 401 without reaching the upstream; do not reuse an old real secret for this test.
4. Safety configuration: in Config → Safety → General, check Enabled, Audit only, and Heuristics only. Ordinary blocking requires protection enabled and Audit only off; contextual review also needs an available judge and Heuristics only off. Review On error: its default is allow, not fail-closed.

A text reply is not a blocking test. With no tool call, a normal text request does not prove tool-call enforcement or require an Audit row. Audit also depends on logging settings. On entitled profiles, Debug evaluates an inert tool-call sample without executing it; it may call the judge, but it does not create an enforcement Audit event. Full protection acceptance needs a controlled tool-call test and matching client and audit evidence.

curl --fail http://127.0.0.1:3758/v1/chat/completions \
  -H "Authorization: Bearer $MODELWARDEN_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"my-model","messages":[{"role":"user","content":"Reply with OK only."}],"tools":[],"stream":false}'