> ## Documentation Index
> Fetch the complete documentation index at: https://mux.coder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Policy File

> Admin-enforced restrictions for providers, models, MCP, and runtimes

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 either:

* an absolute path on the machine running Mux, or
* a remote `http://` / `https://` URL that Mux can fetch.

```bash theme={null}
export MUX_POLICY_FILE="/etc/mux/policy.json"
# or
export MUX_POLICY_FILE="https://example.com/mux/policy.json"
```

If `MUX_POLICY_FILE` is set but the file can’t be read/fetched/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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](/config/providers) and [Models](/config/models).