Policy File

• 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

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

export SHUX_POLICY_FILE="/etc/shux/policy.json"
# or
export SHUX_POLICY_FILE="https://example.com/shux/policy.json"

​

File format

• Unknown fields are rejected.
• JSON must be valid (no comments, no trailing commas).

{
  "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)

• id (required): provider ID (matches what you see in Settings → Providers)
• base_url (optional): if set to a non-empty string, Shux forces that provider base URL
• model_access (optional): list of allowed model IDs

• 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.

​

Shux Gateway models

• anthropic/<modelId>
• openai/<modelId>
• google/<modelId>
• xai/<modelId>

{
  "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)

{
  "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).

​

Runtime restrictions (runtimes)

• local
• worktree
• ssh
• ssh+coder
• docker
• devcontainer

{
  "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, Shux 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, Shux will block the action (it will not auto-switch).

​

Troubleshooting

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