Skip to main content
Mux supports an admin-controlled policy file that can restrict what users can do in the app.
  • It is opt-in (no behavior changes unless enabled).
  • It is enforced server-side (users can’t bypass it via the UI, slash commands, or manual edits).
  • It is loaded at startup and refreshed every 15 minutes.

​
Enable the policy file

Set MUX_POLICY_FILE to an absolute path on the machine running Mux: 
export MUX_POLICY_FILE="/etc/mux/policy.json"
If MUX_POLICY_FILE is set but the file can’t be read/parsed/validated, Mux will block startup with an error.

​
File format

The policy file is strict JSON.
  • Unknown fields are rejected.
  • JSON must be valid (no comments, no trailing commas).
Example skeleton: 
{
  "policy_format_version": "0.1",
  "minimum_client_version": "1.0.0",
  "provider_access": [
    {
      "id": "openai",
      "base_url": "https://api.openai.com/v1",
      "model_access": ["gpt-5.2", "gpt-5.2-codex"]
    }
  ],
  "tools": {
    "allow_user_defined_mcp": {
      "stdio": true,
      "remote": false
    }
  },
  "runtimes": [{ "id": "worktree" }, { "id": "ssh+coder" }]
}

​
Provider and model access (provider_access)

If provider_access is omitted or an empty array, all providers are allowed. If provider_access is present, only providers listed there are allowed. Each entry supports:
  • id (required): provider ID (matches what you see in Settings → Providers)
  • base_url (optional): if set to a non-empty string, Mux forces that provider base URL
  • model_access (optional): list of allowed model IDs
model_access behavior:
  • If omitted, all models for that provider are allowed.
  • If present but an empty list, all models for that provider are allowed.
  • If non-empty, only the listed models are allowed.

​
Mux Gateway models

The Mux Gateway provider ID is mux-gateway. Gateway model IDs use the form:
  • anthropic/<modelId>
  • openai/<modelId>
  • google/<modelId>
  • xai/<modelId>
Example: 
{
  "policy_format_version": "0.1",
  "provider_access": [
    {
      "id": "mux-gateway",
      "model_access": ["openai/gpt-5.2", "anthropic/claude-sonnet-4-5"]
    }
  ]
}

​
MCP restrictions (tools.allow_user_defined_mcp)

Control whether users can add/edit MCP servers themselves: 
{
  "policy_format_version": "0.1",
  "tools": {
    "allow_user_defined_mcp": {
      "stdio": false,
      "remote": false
    }
  }
}
  • stdio applies to local stdio MCP servers.
  • remote applies to remote transports (http, sse, and auto).
If allow_user_defined_mcp is omitted, both are allowed.

​
Runtime restrictions (runtimes)

If runtimes is omitted or an empty array, all runtimes are allowed. If runtimes is present, only the listed runtime IDs are allowed:
  • local
  • worktree
  • ssh
  • ssh+coder
  • docker
  • devcontainer
Example: allow only worktrees and Coder-managed SSH: 
{
  "policy_format_version": "0.1",
  "runtimes": [{ "id": "worktree" }, { "id": "ssh+coder" }]
}

​
Operational behavior

  • The policy is loaded at startup and refreshed every 15 minutes.
  • If a refresh fails, Mux keeps the last-known-good policy (it does not fall back to allow-all).
  • If the policy changes to disallow the currently selected provider/model/runtime, Mux will block the action (it will not auto-switch).

​
Troubleshooting

  • Mux won’t start and mentions policy: fix the policy file, or temporarily unset MUX_POLICY_FILE.
  • Changes aren’t visible yet: policy reloads every 15 minutes (or restart Mux to reload immediately).
  • Need help finding provider IDs: see Providers and Models.