modelmux
quick_start →
Open documentation index
Getting startedOverviewInstallationQuick startCore concepts
ConfigurationConfiguration referenceProvidersRouting and failoverRate limiting
OperationsStorageObservabilitySecurityTUI dashboardAI routing
ReferenceCLI referenceAdmin APITroubleshooting
Docs/Operations/Security
Operations

Security

Secure proxy access, admin endpoints, provider credentials, the secret store, and reverse-proxy deployments.

Network exposure

The safest default is binding ModelMux to 127.0.0.1. Bind to a broader interface only when another machine or container must connect.

Authentication is required for network exposure

Do not expose an unauthenticated ModelMux endpoint to an untrusted network. Anyone with access could spend provider quota and inspect operational endpoints.

Proxy authentication

config.yaml
server:
  host: "0.0.0.0"
  port: 8787
  require_auth: true
  auth_token_env: MODELMUX_AUTH_TOKEN
Terminal
export MODELMUX_AUTH_TOKEN="replace-with-a-long-random-token"
modelmux start

Clients authenticate with Authorization: Bearer <token>. Rotate the token through your secret-management process and restart or reload the service as required by your deployment.

Admin endpoint authentication

/admin/* is protected separately by server.admin.require_auth. Keep this setting enabled even when the proxy is local.

Admin endpoints can reload configuration, change key state, and test provider credentials. They should be treated as privileged operational controls.

Provider credentials and encrypted secrets

Provider keys are never written to request logs or metrics. Prefer environment variables or the encrypted store:

Terminal
export MODELMUX_MASTER_KEY="a-strong-master-password"
modelmux secret set --ref provider-a-primary
# Enter value through the hidden prompt
config.yaml
keys:
  - id: provider-a-primary
    provider_id: provider-a
    model_id: production-chat
    secret_ref: provider-a-primary

The encrypted store uses AES-256-GCM. Its encryption key is derived with Argon2id using a per-file salt. The documented derivation uses 64 MiB memory and three iterations.

Reverse-proxy deployments

Do not assume localhost checks remain safe behind a reverse proxy. Proxied traffic can appear to ModelMux as local traffic. Keep ModelMux authentication enabled and enforce TLS and access controls at the edge.

  • Do not publish /admin/* without authentication.
  • Restrict /metrics and /logs when they contain sensitive operational data.
  • Preserve or generate request correlation headers intentionally.
  • Set request body limits at both the edge and ModelMux.
  • Use HTTPS between clients and the reverse proxy.

Security checklist

  • Keep ModelMux and its dependencies updated.
  • Use a dedicated operating-system user with minimal file permissions.
  • Restrict read access to config, SQLite, and secrets.enc.
  • Never commit provider keys or MODELMUX_MASTER_KEY.
  • Use different ModelMux bearer tokens for different environments.
  • Back up encrypted secrets and store the matching master key separately.
  • Review logs and metrics before sharing them outside the operations team.