feat(config): Make the gatekeeper model more configurable

Move the gatekeeper configuration into a nested member off
our config object, so LINUX_MCP_GATEKEEPER_MODEL becomes
LINUX_MCP_GATEKEEPER__MODEL (LINUX_MCP_GATEKEEPER_MODEL
is supported as a deprecated alias.)

Add controls for:
 reasoning_effort: turn off or down reasoning often make models
   perform better for us.
 structured_output: e.g. for gemma-4-31b-it, turning off
   response_format is needed to keep the model from going into
   infinite looop.
 temperature: Anthropc models need a non-zero temperature to
   enable reasoning.
 quantization: OpenRouter mixes together models with different
   quantization in a single model name - specifying a specific
   quantization is needed for clean benchmarking data.

Author: owtaylor

.gitlab/ci/eval-gatekeeper.yml

@@ -54,7 +54,7 @@ gatekeeper-eval-claude-4.6-opus:
   variables:
     MODEL_NAME: "claude-4.6-opus"
   script:
-    - export LINUX_MCP_GATEKEEPER_MODEL="openrouter/anthropic/$MODEL_NAME"
+    - export LINUX_MCP_GATEKEEPER__MODEL="openrouter/anthropic/$MODEL_NAME"
     - uv run eval/gatekeeper/run-eval.py --all -f json --output-all -o "$CI_PROJECT_DIR/data/$MODEL_NAME.json"
   rules:
     - if: $OPENROUTER_API_KEY

docs/config-reference.md

@@ -3,87 +3,93 @@
 The Linux MCP Server is configured through command line options or environment variables. Environment variables use a `LINUX_MCP_` prefix. For example, `--log-level` corresponds to `LINUX_MCP_LOG_LEVEL`.
 
 !!! note "Precedence"
-    Command line options take precedence over environment variables. For MCP client configurations (Claude Desktop, Cursor, etc.), you typically use environment variables in the config file rather than command line arguments, but either will work.
+Command line options take precedence over environment variables. For MCP client configurations (Claude Desktop, Cursor, etc.), you typically use environment variables in the config file rather than command line arguments, but either will work.
 
 To see available options, run `linux-mcp-server --help`.
 
 ## Transport Settings
 
-| Option / Env Var | Default | Description |
-|------------------|---------|-------------|
-| `--transport`<br>`LINUX_MCP_TRANSPORT` | `stdio` | Transport type: `stdio` or `http` |
-| `--host`<br>`LINUX_MCP_HOST` | `127.0.0.1` | Host address for HTTP transport |
-| `--port`<br>`LINUX_MCP_PORT` | `8000` | Port number for HTTP transport |
-| `--path`<br>`LINUX_MCP_PATH` | `/mcp` | Path for HTTP transport |
+| Option / Env Var                       | Default     | Description                       |
+| -------------------------------------- | ----------- | --------------------------------- |
+| `--transport`<br>`LINUX_MCP_TRANSPORT` | `stdio`     | Transport type: `stdio` or `http` |
+| `--host`<br>`LINUX_MCP_HOST`           | `127.0.0.1` | Host address for HTTP transport   |
+| `--port`<br>`LINUX_MCP_PORT`           | `8000`      | Port number for HTTP transport    |
+| `--path`<br>`LINUX_MCP_PATH`           | `/mcp`      | Path for HTTP transport           |
 
 !!! warning "HTTP Transport Security"
-    The HTTP transport does not currently have authentication. It should not be used in production or on untrusted networks.
+The HTTP transport does not currently have authentication. It should not be used in production or on untrusted networks.
 
 !!! note
-    Some clients, like Claude Desktop, require `stdio` transport.
+Some clients, like Claude Desktop, require `stdio` transport.
 
 ## SSH Connection Settings
 
-| Option / Env Var | Default | Description |
-|------------------|---------|-------------|
-| `--user`<br>`LINUX_MCP_USER` | *(empty)* | Default username for SSH connections |
-| `--ssh-key-path`<br>`LINUX_MCP_SSH_KEY_PATH` | *(none)* | Path to SSH private key file |
-| `--key-passphrase`<br>`LINUX_MCP_KEY_PASSPHRASE` | *(empty)* | Passphrase for encrypted SSH key |
-| `--search-for-ssh-key`<br>`LINUX_MCP_SEARCH_FOR_SSH_KEY` | `False` | Auto-discover SSH keys in `~/.ssh` |
-| `--command-timeout`<br>`LINUX_MCP_COMMAND_TIMEOUT` | `30` | Local and remote command timeout in seconds |
+| Option / Env Var                                         | Default   | Description                                 |
+| -------------------------------------------------------- | --------- | ------------------------------------------- |
+| `--user`<br>`LINUX_MCP_USER`                             | _(empty)_ | Default username for SSH connections        |
+| `--ssh-key-path`<br>`LINUX_MCP_SSH_KEY_PATH`             | _(none)_  | Path to SSH private key file                |
+| `--key-passphrase`<br>`LINUX_MCP_KEY_PASSPHRASE`         | _(empty)_ | Passphrase for encrypted SSH key            |
+| `--search-for-ssh-key`<br>`LINUX_MCP_SEARCH_FOR_SSH_KEY` | `False`   | Auto-discover SSH keys in `~/.ssh`          |
+| `--command-timeout`<br>`LINUX_MCP_COMMAND_TIMEOUT`       | `30`      | Local and remote command timeout in seconds |
 
 ## SSH Security Settings
 
-| Option / Env Var | Default | Description |
-|------------------|---------|-------------|
-| `--verify-host-keys` / `--no-verify-host-keys`<br>`LINUX_MCP_VERIFY_HOST_KEYS` | `True` | Verify remote host identity via known_hosts |
-| `--known-hosts-path`<br>`LINUX_MCP_KNOWN_HOSTS_PATH` | *(none)* | Custom path to known_hosts file |
+| Option / Env Var                                                               | Default  | Description                                 |
+| ------------------------------------------------------------------------------ | -------- | ------------------------------------------- |
+| `--verify-host-keys` / `--no-verify-host-keys`<br>`LINUX_MCP_VERIFY_HOST_KEYS` | `True`   | Verify remote host identity via known_hosts |
+| `--known-hosts-path`<br>`LINUX_MCP_KNOWN_HOSTS_PATH`                           | _(none)_ | Custom path to known_hosts file             |
 
 See [SSH Configuration](ssh.md) for details on setting up SSH connections and managing host keys.
 
 ## Tool Settings
 
-| Option / Env Var | Default | Description |
-|------------------|---------|-------------|
-| `--toolset`<br>`LINUX_MCP_TOOLSET` | `fixed` | Toolset: `fixed`, `run_script`, or `both` |
-| `--allowed-log-paths`<br>`LINUX_MCP_ALLOWED_LOG_PATHS` | *(none)* | Comma-separated allowlist of log file paths for `read_log_file` |
-| `--max-file-read-bytes`<br>`LINUX_MCP_MAX_FILE_READ_BYTES` | `1048576` | Maximum bytes `read_file` may return |
+| Option / Env Var                                           | Default   | Description                                                     |
+| ---------------------------------------------------------- | --------- | --------------------------------------------------------------- |
+| `--toolset`<br>`LINUX_MCP_TOOLSET`                         | `fixed`   | Toolset: `fixed`, `run_script`, or `both`                       |
+| `--allowed-log-paths`<br>`LINUX_MCP_ALLOWED_LOG_PATHS`     | _(none)_  | Comma-separated allowlist of log file paths for `read_log_file` |
+| `--max-file-read-bytes`<br>`LINUX_MCP_MAX_FILE_READ_BYTES` | `1048576` | Maximum bytes `read_file` may return                            |
 
 See [Guarded Command Execution](guarded-command-execution.md) for details on the `run_script` toolset.
 
 ## Guarded Command Execution Settings
 
 These are used when `LINUX_MCP_TOOLSET` is set to `run_script` or `both`.
 
-| Option / Env Var | Default | Description |
-|------------------|---------|-------------|
-| `--gatekeeper-model`<br>`LINUX_MCP_GATEKEEPER_MODEL` | *(none)* | Required: [LiteLLM model name](https://docs.litellm.ai/docs/providers) to use |
-| `--always-confirm-scripts` / `--no-always-confirm-scripts`<br>`LINUX_MCP_ALWAYS_CONFIRM_SCRIPTS` | `False` | All scripts must be confirmed by the user |
-| Other environment variables | *(none)* | As required by the LiteLLM provider, e.g. `OPENAI_API_KEY` |
+| Option / Env Var                                                              | Default            | Description                                                                                                                                                                                                                                                |
+| ----------------------------------------------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--gatekeeper.model`<br>`LINUX_MCP_GATEKEEPER__MODEL`                         | _(none)_           | Required: [LiteLLM model name](https://docs.litellm.ai/docs/providers) to use                                                                                                                                                                              |
+| `--gatekeeper.quantization`<br>`LINUX_MCP_GATEKEEPER__QUANTIZATION`           | _(model specific)_ | _Not usually needed_ - Particular model quantization to use (openrouter only)                                                                                                                                                                              |
+| `--gatekeeper.reasoning_effort`<br>`LINUX_MCP_GATEKEEPER__REASONING_EFFORT`   | _(model specific)_ | Reasoning effort to use for gatekeeper model (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`). Not all values are supported for all models. Special values (`enable_thinking`, `disable_thinking`) set the `enable_thinking` chat template parameter. |
+| `--gatekeeper.structured_output`<br>`LINUX_MCP_GATEKEEPER__STRUCTURED_OUTPUT` | _(autodected)_     | _Not usually needed_ - Whether to use structured output generation for the model. Default is to use if detected as available.                                                                                                                              |
+| `--gatekeeper.temperature`<br>`LINUX_MCP_GATEKEEPER__TEMPERATURE`             | 0.0                | _Not usually needed_ - Temperature to use for model - for some models, a non-zero value may be necessary when enabling reasoning                                                                                                                           |
+| Other environment variables                                                   | _(none)_           | As required by the LiteLLM provider, e.g. `OPENAI_API_KEY`                                                                                                                                                                                                 |
 
 ## Logging Configuration
 
-| Option / Env Var | Default | Description |
-|------------------|---------|-------------|
-| `--log-dir`<br>`LINUX_MCP_LOG_DIR` | `~/.local/share/linux-mcp-server/logs` | Directory for server logs |
-| `--log-level`<br>`LINUX_MCP_LOG_LEVEL` | `INFO` | Log verbosity: `DEBUG`, `INFO`, `WARNING` |
-| `--log-retention-days`<br>`LINUX_MCP_LOG_RETENTION_DAYS` | `10` | Days to retain log files |
+| Option / Env Var                                         | Default                                | Description                               |
+| -------------------------------------------------------- | -------------------------------------- | ----------------------------------------- |
+| `--log-dir`<br>`LINUX_MCP_LOG_DIR`                       | `~/.local/share/linux-mcp-server/logs` | Directory for server logs                 |
+| `--log-level`<br>`LINUX_MCP_LOG_LEVEL`                   | `INFO`                                 | Log verbosity: `DEBUG`, `INFO`, `WARNING` |
+| `--log-retention-days`<br>`LINUX_MCP_LOG_RETENTION_DAYS` | `10`                                   | Days to retain log files                  |
 
 See [Debug Logging](debugging.md) for details on log formats and locations.
 
 ## Examples
 
 **Specify SSH settings:**
+
 ```bash
 linux-mcp-server --user admin --ssh-key-path ~/.ssh/id_rsa --verify-host-keys
 ```
 
 **Configure log access:**
+
 ```bash
 linux-mcp-server --allowed-log-paths "/var/log/messages,/var/log/secure,/var/log/audit/audit.log"
 ```
 
 **Using environment variables in a client config:**
+
 ```json
 {
   "env": {

docs/guarded-command-execution.md

@@ -106,14 +106,14 @@ LINUX_MCP_TOOLSET=run_script
 
 **Configure a Gatekeeper Model**
 
-Set `LINUX_MCP_GATEKEEPER_MODEL` to the name of the model you want to use. Additional environment
+Set `LINUX_MCP_GATEKEEPER__MODEL` to the name of the model you want to use. Additional environment
 variables may be needed to configure credentials. See the
 [LiteLLM documentation](https://docs.litellm.ai/docs/providers) for details on how to configure your provider.
 
 Example:
 
 ```sh
-LINUX_MCP_GATEKEEPER_MODEL=openai/chatgpt-5.2
+LINUX_MCP_GATEKEEPER__MODEL=openai/chatgpt-5.2
 OPENAI_API_KEY=<....>
 ```
 

eval/gatekeeper/README.md

@@ -64,7 +64,7 @@ Runs test cases through the gatekeeper and reports results.
 
 ```bash
 # Set the gatekeeper model
-export LINUX_MCP_GATEKEEPER_MODEL="openrouter/anthropic/claude-3.5-sonnet"
+export LINUX_MCP_GATEKEEPER__MODEL="openrouter/anthropic/claude-3.5-sonnet"
 
 # Run evaluation on a single file
 uv run eval/gatekeeper/run-eval.py testcases/selinux-port-denial.yaml -o results.yaml

eval/gatekeeper/run-eval-models-corp.sh

@@ -38,8 +38,8 @@ get_MC_base_url() {
 }
 
 [[ -z "${MODEL}" ]] && echo "$MODEL must be set" && exit 1
-export LINUX_MCP_GATEKEEPER_MODEL
-LINUX_MCP_GATEKEEPER_MODEL="openai/$MODEL"
+export LINUX_MCP_GATEKEEPER__MODEL
+LINUX_MCP_GATEKEEPER__MODEL="openai/$MODEL"
 export OPENAI_API_BASE
 OPENAI_API_BASE="$(get_MC_base_url "$MODEL")"
 

eval/gatekeeper/run-eval.py

@@ -219,9 +219,9 @@ def main(
         typer.echo("Must specify either a test case file or --all.", err=True)
         raise typer.Exit(code=1)
 
-    if "LINUX_MCP_GATEKEEPER_MODEL" not in os.environ:
+    if "LINUX_MCP_GATEKEEPER__MODEL" not in os.environ and "LINUX_MCP_GATEKEEPER__MODEL" not in os.environ:
         typer.echo(
-            "Please set the LINUX_MCP_GATEKEEPER_MODEL environment variable to specify the Gatekeeper model to use."
+            "Please set the LINUX_MCP_GATEKEEPER__MODEL environment variable to specify the Gatekeeper model to use."
         )
         raise typer.Exit(code=1)
 

src/linux_mcp_server/config.py

@@ -1,10 +1,14 @@
 """Settings for linux-mcp-server"""
 
+import logging
+import os
 import sys
 
 from pathlib import Path
+from typing import Any
 
 from pydantic import Field
+from pydantic import model_validator
 from pydantic import SecretStr
 from pydantic_settings import BaseSettings
 from pydantic_settings import SettingsConfigDict
@@ -13,6 +17,9 @@
 from linux_mcp_server.utils.types import UpperCase
 
 
+logger = logging.getLogger(__name__)
+
+
 class Transport(StrEnum):
     stdio = "stdio"
     http = "http"
@@ -27,6 +34,20 @@ class Toolset(StrEnum):
     BOTH = "both"
 
 
+class ReasoningEffort(StrEnum):
+    """Reasoning effort levels for the gatekeeper model."""
+
+    NONE = "none"
+    MINIMAL = "minimal"
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    XHIGH = "xhigh"
+    DEFAULT = "default"
+    DISABLE_THINKING = "disable_thinking"
+    ENABLE_THINKING = "enable_thinking"
+
+
 class AuthProvider(StrEnum):
     """Authentication provider types."""
 
@@ -78,6 +99,24 @@ class AuthConfig(BaseSettings):
     introspection: IntrospectionAuthConfig | None = None
 
 
+class GatekeeperConfig(BaseSettings):
+    """Gatekeeper Model configuration"""
+
+    model: str | None = None
+
+    # model quantization (e.g. fp8, bf16 - only supported for openrouter)
+    quantization: str | None = None
+
+    # reasoning effort
+    reasoning_effort: ReasoningEffort | None = None
+
+    # Whether we should use structured output (default, autodetect support)
+    structured_output: bool | None = None
+
+    # Temperature for gatekeeper model
+    temperature: float = 0.0
+
+
 class Config(BaseSettings):
     # The '_' is required in the env_prefix, otherwise, pydantic would
     # interpret the prefix as LINUX_MCPLOG_DIR, instead of LINUX_MCP_LOG_DIR
@@ -127,8 +166,7 @@ class Config(BaseSettings):
     # What tools are available
     toolset: Toolset = Toolset.FIXED
 
-    # Gatekeeper model (required for run_script tools)
-    gatekeeper_model: str | None = None
+    gatekeeper: GatekeeperConfig = Field(default_factory=GatekeeperConfig)
 
     # Command execution timeout (applies to both local and remote commands)
     command_timeout: int = 30  # Timeout in seconds; prevents hung commands
@@ -165,9 +203,25 @@ def transport_kwargs(self):
     #
     # @model_validator(mode="after")
     # def validate_gatekeeper_model(self):
-    #     if self.toolset != Toolset.FIXED and self.gatekeeper_model is None:
-    #         raise ValueError('gatekeeper_model must be set unless the toolset is "fixed"')
+    #     if self.toolset != Toolset.FIXED and self.gatekeeper.model is None:
+    #         raise ValueError('gatekeeper.model must be set unless the toolset is "fixed"')
     #     return self
 
+    @model_validator(mode="before")
+    @classmethod
+    def handle_deprecated_aliases(cls, data: Any) -> Any:
+        if isinstance(data, dict):
+            old_value = os.environ.get("LINUX_MCP_GATEKEEPER_MODEL")
+            if old_value is not None:
+                logger.warning(
+                    "LINUX_MCP_GATEKEEPER_MODEL is deprecated. Please use LINUX_MCP_GATEKEEPER__MODEL instead.",
+                )
+
+                gatekeeper_data = data.setdefault("gatekeeper", {})
+                if isinstance(gatekeeper_data, dict) and "model" not in gatekeeper_data:
+                    gatekeeper_data["model"] = old_value
+
+        return data
+
 
 CONFIG = Config()