feat(gatekeeper): add Vertex AI support and refactor configuration

Add first-class support for the Vertex AI provider in the gatekeeper system. The configuration structure has been refactored to accommodate separate settings for each provider type.

Author: subpop

docs/config-reference.md

@@ -58,18 +58,21 @@ These are used when `LINUX_MCP_TOOLSET` is set to `run_script` or `both`.
 | Option / Env Var | Default | Description |
 | ---------------- | ------- | ----------- |
 | `--always-confirm-scripts` / `--no-always-confirm-scripts`<br>`LINUX_MCP_ALWAYS_CONFIRM_SCRIPTS` | `False` | All scripts must be confirmed by the user |
-| `--gatekeeper.provider`<br>`LINUX_MCP_GATEKEEPER__PROVIDER` | `openai` (inferred from model if unset) | LLM provider: `openai`, `anthropic`, `gemini`, or `openrouter` |
-| `--gatekeeper.backend`<br>`LINUX_MCP_GATEKEEPER__BACKEND` | `direct` | API backend: `direct` or `vertex` (GCP/Vertex AI) |
+| `--gatekeeper.provider`<br>`LINUX_MCP_GATEKEEPER__PROVIDER` | `openai` (inferred from model if unset) | LLM provider: `openai`, `anthropic`, `gemini`, `openrouter`, or `vertex_ai` |
 | `--gatekeeper.model`<br>`LINUX_MCP_GATEKEEPER__MODEL` | _(none)_ | Required: provider-native model ID (e.g. `gpt-5.4`, `claude-sonnet-4-6`, `gemini-2.0-flash`, `openai/gpt-oss-120b` for OpenRouter) |
-| `--gatekeeper.quantization`<br>`LINUX_MCP_GATEKEEPER__QUANTIZATION` | _(none)_ | OpenRouter only: filter providers by quantization level (e.g. `fp4`, `bf16`) |
-| `--gatekeeper.base_url`<br>`LINUX_MCP_GATEKEEPER__BASE_URL` / `OPENAI_API_BASE` | `https://api.openai.com/v1` | OpenAI-compatible API base URL (OpenAI provider only) |
-| `--gatekeeper.project`<br>`LINUX_MCP_GATEKEEPER__PROJECT` / `VERTEXAI_PROJECT` | _(none)_ | GCP project for Vertex backends |
-| `--gatekeeper.location`<br>`LINUX_MCP_GATEKEEPER__LOCATION` / `VERTEXAI_LOCATION` | `global` | GCP region for Vertex backends |
 | `--gatekeeper.reasoning_effort`<br>`LINUX_MCP_GATEKEEPER__REASONING_EFFORT` | _(model specific)_ | Reasoning effort (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`). Not all values are supported for all models. |
 | `--gatekeeper.structured_output`<br>`LINUX_MCP_GATEKEEPER__STRUCTURED_OUTPUT` | `True` | Whether to use structured JSON output from the model |
 | `--gatekeeper.temperature`<br>`LINUX_MCP_GATEKEEPER__TEMPERATURE` | 0.0 | Temperature to use for the model |
-| `--gatekeeper.template_kwargs`<br>`LINUX_MCP_GATEKEEPER__TEMPLATE_KWARGS` | _(none)_ | _Not usually needed_ - Extra chat-template arguments for OpenAI-compatible servers (e.g. llama.cpp `enable_thinking`), sent as `chat_template_kwargs` on Chat Completions requests. JSON object, e.g. `{ "enable_thinking": false }` |
-| Provider credentials | _(none)_ | `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY` / `GEMINI_API_KEY`, or `OPENROUTER_API_KEY` for direct backends; `GOOGLE_APPLICATION_CREDENTIALS` for Vertex backends |
+| `--gatekeeper.cost`<br>`LINUX_MCP_GATEKEEPER__COST` | _(none)_ | Gatekeeper cost for accounting (`input$/token:output$/token`) |
+| `--gatekeeper.openai.base_url`<br>`LINUX_MCP_GATEKEEPER__OPENAI__BASE_URL` / `OPENAI_API_BASE` | `https://api.openai.com/v1` | OpenAI provider: API base URL |
+| `--gatekeeper.openai.template_kwargs`<br>`LINUX_MCP_GATEKEEPER__OPENAI__TEMPLATE_KWARGS` | _(none)_ | OpenAI provider: extra chat-template arguments (e.g. llama.cpp `enable_thinking`), sent as `chat_template_kwargs` |
+| `--gatekeeper.openrouter.base_url`<br>`LINUX_MCP_GATEKEEPER__OPENROUTER__BASE_URL` | `https://openrouter.ai/api/v1` | OpenRouter provider: API base URL |
+| `--gatekeeper.openrouter.quantization`<br>`LINUX_MCP_GATEKEEPER__OPENROUTER__QUANTIZATION` | _(none)_ | OpenRouter provider: filter providers by quantization level (e.g. `fp4`, `bf16`) |
+| `--gatekeeper.openrouter.template_kwargs`<br>`LINUX_MCP_GATEKEEPER__OPENROUTER__TEMPLATE_KWARGS` | _(none)_ | OpenRouter provider: extra chat-template arguments |
+| `--gatekeeper.vertex_ai.project`<br>`LINUX_MCP_GATEKEEPER__VERTEX_AI__PROJECT` / `VERTEXAI_PROJECT` | _(none)_ | Vertex AI provider: GCP project |
+| `--gatekeeper.vertex_ai.location`<br>`LINUX_MCP_GATEKEEPER__VERTEX_AI__LOCATION` / `VERTEXAI_LOCATION` | `global` | Vertex AI provider: GCP region |
+| `--gatekeeper.vertex_ai.base_url`<br>`LINUX_MCP_GATEKEEPER__VERTEX_AI__BASE_URL` | _(computed)_ | Vertex AI provider: override OpenAI-compatible MaaS endpoint URL (default derived from project/location) |
+| Provider credentials | _(none)_ | `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY` / `GEMINI_API_KEY`, or `OPENROUTER_API_KEY` for direct providers; `GOOGLE_APPLICATION_CREDENTIALS` for `vertex_ai` |
 
 ## Logging Configuration
 

docs/guarded-command-execution.md

@@ -108,7 +108,7 @@ LINUX_MCP_TOOLSET=run_script
 
 Set `LINUX_MCP_GATEKEEPER__PROVIDER` and `LINUX_MCP_GATEKEEPER__MODEL` to configure the gatekeeper.
 Set the matching API credentials for your provider (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`,
-`GOOGLE_API_KEY`, or `OPENROUTER_API_KEY`). For Vertex AI backends, install the `gcp` extra and configure
+`GOOGLE_API_KEY`, or `OPENROUTER_API_KEY`). For the `vertex_ai` provider, install the `gcp` extra and configure
 `GOOGLE_APPLICATION_CREDENTIALS`, `VERTEXAI_PROJECT`, and `VERTEXAI_LOCATION`.
 
 Example (OpenAI):
@@ -132,10 +132,19 @@ Example (OpenRouter):
 ```sh
 LINUX_MCP_GATEKEEPER__PROVIDER=openrouter
 LINUX_MCP_GATEKEEPER__MODEL=openai/gpt-oss-120b
-LINUX_MCP_GATEKEEPER__QUANTIZATION=fp4
+LINUX_MCP_GATEKEEPER__OPENROUTER__QUANTIZATION=fp4
 OPENROUTER_API_KEY=<....>
 ```
 
+Example (Vertex AI):
+
+```sh
+LINUX_MCP_GATEKEEPER__PROVIDER=vertex_ai
+LINUX_MCP_GATEKEEPER__MODEL=gemini-3.1-pro-preview
+LINUX_MCP_GATEKEEPER__VERTEX_AI__PROJECT=my-gcp-project
+GOOGLE_APPLICATION_CREDENTIALS=<path-to-service-account.json>
+```
+
 
 **Configure your client's tool policy**
 

eval/gatekeeper/README.md

@@ -75,6 +75,10 @@ uv run eval/gatekeeper/run-eval.py testcases/selinux-port-denial.yaml -o results
 export OPENROUTER_API_KEY="..."
 ./eval/gatekeeper/standard-evals.sh --no-save gpt-oss-120b:low,fp4@openrouter
 
+# Run via standard-evals.sh (Vertex AI example)
+export VERTEXAI_PROJECT="my-gcp-project"
+./eval/gatekeeper/standard-evals.sh --no-save gemini-3.1-pro-preview:low@vertex_ai
+
 # Run all test case files in testcases/
 uv run eval/gatekeeper/run-eval.py --all -o results.yaml
 

eval/gatekeeper/standard-evals.sh

@@ -263,25 +263,23 @@ case "$provider" in
     anthropic)
         : "${ANTHROPIC_API_KEY:?'api key must be set'}"
         LINUX_MCP_GATEKEEPER__PROVIDER=anthropic
-        LINUX_MCP_GATEKEEPER__BACKEND=direct
         LINUX_MCP_GATEKEEPER__MODEL="$model"
         ;;
     llama_cpp)
         OPENAI_API_KEY=tasty
         LINUX_MCP_GATEKEEPER__PROVIDER=openai
-        LINUX_MCP_GATEKEEPER__BACKEND=direct
-        LINUX_MCP_GATEKEEPER__BASE_URL=http://localhost:8080/v1
+        LINUX_MCP_GATEKEEPER__OPENAI__BASE_URL=http://localhost:8080/v1
         # gemma-4 and qwen3.5 support enable_thinking via chat_template_kwargs; granite-4 has no control
         case "$reasoning" in
             none)
-                LINUX_MCP_GATEKEEPER__TEMPLATE_KWARGS='{ "enable_thinking": false }'
+                LINUX_MCP_GATEKEEPER__OPENAI__TEMPLATE_KWARGS='{ "enable_thinking": false }'
                 ;;
             default)
-                LINUX_MCP_GATEKEEPER__TEMPLATE_KWARGS='{ "enable_thinking": true }'
+                LINUX_MCP_GATEKEEPER__OPENAI__TEMPLATE_KWARGS='{ "enable_thinking": true }'
                 ;;
         esac
         export OPENAI_API_KEY
-        export LINUX_MCP_GATEKEEPER__BASE_URL
+        export LINUX_MCP_GATEKEEPER__OPENAI__BASE_URL
         max_parallel=1
         quant_tag="${quantization^^}"
         case "$model" in
@@ -317,37 +315,25 @@ case "$provider" in
         : "${VERTEXAI_PROJECT:?'project must be set'}"
         uv_args+=("--extra" "gcp")
         max_parallel=50
-        LINUX_MCP_GATEKEEPER__BACKEND=vertex
-        vertex_location="${VERTEXAI_LOCATION:-global}"
-        vertex_openapi_base="https://aiplatform.googleapis.com/v1/projects/${VERTEXAI_PROJECT}/locations/${vertex_location}/endpoints/openapi"
+        LINUX_MCP_GATEKEEPER__PROVIDER=vertex_ai
+        LINUX_MCP_GATEKEEPER__VERTEX_AI__PROJECT="${VERTEXAI_PROJECT}"
         case $model in
-            claude-*)
-                LINUX_MCP_GATEKEEPER__PROVIDER=anthropic
-                LINUX_MCP_GATEKEEPER__MODEL="$model"
-                ;;
-            gemini-*)
-                LINUX_MCP_GATEKEEPER__PROVIDER=gemini
+            claude-*|gemini-*)
                 LINUX_MCP_GATEKEEPER__MODEL="$model"
                 ;;
             gemma-4-26b-a4b-it)
                 if [[ $reasoning == "none" ]] ; then
                     LINUX_MCP_GATEKEEPER__REASONING_EFFORT=
                 fi
-                LINUX_MCP_GATEKEEPER__PROVIDER=openai
                 LINUX_MCP_GATEKEEPER__MODEL="${model}-maas"
-                LINUX_MCP_GATEKEEPER__BASE_URL="${vertex_openapi_base}"
                 LINUX_MCP_GATEKEEPER__COST=0.15e-6:0.60e-6
                 ;;
             gpt-oss-20b)
-                LINUX_MCP_GATEKEEPER__PROVIDER=openai
                 LINUX_MCP_GATEKEEPER__MODEL="${model}-maas"
-                LINUX_MCP_GATEKEEPER__BASE_URL="${vertex_openapi_base}"
                 LINUX_MCP_GATEKEEPER__COST="0.07e-6:0.25e-6"
                 ;;
             gpt-oss-120b)
-                LINUX_MCP_GATEKEEPER__PROVIDER=openai
                 LINUX_MCP_GATEKEEPER__MODEL="${model}-maas"
-                LINUX_MCP_GATEKEEPER__BASE_URL="${vertex_openapi_base}"
                 LINUX_MCP_GATEKEEPER__COST="0.09e-6:0.36e-6"
                 ;;
         esac
@@ -357,7 +343,6 @@ case "$provider" in
         SSL_CERT_FILE=${SSL_CERT_FILE:-/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem}
         export SSL_CERT_FILE
         LINUX_MCP_GATEKEEPER__PROVIDER=openai
-        LINUX_MCP_GATEKEEPER__BACKEND=direct
         case $model in
             granite-*)
                 LINUX_MCP_GATEKEEPER__MODEL="ibm-granite/$model"
@@ -366,15 +351,14 @@ case "$provider" in
                 LINUX_MCP_GATEKEEPER__MODEL="openai/$model"
                 ;;
         esac
-        LINUX_MCP_GATEKEEPER__BASE_URL="$(get_MC_base_url "$model")"
+        LINUX_MCP_GATEKEEPER__OPENAI__BASE_URL="$(get_MC_base_url "$model")"
         max_parallel=5
         ;;
     openrouter)
         : "${OPENROUTER_API_KEY:?'api key must be set'}"
         LINUX_MCP_GATEKEEPER__PROVIDER=openrouter
-        LINUX_MCP_GATEKEEPER__BACKEND=direct
         if [[ -n $quantization ]] ; then
-            LINUX_MCP_GATEKEEPER__QUANTIZATION=$quantization
+            LINUX_MCP_GATEKEEPER__OPENROUTER__QUANTIZATION=$quantization
         fi
         case $model in
             claude-*)
@@ -399,11 +383,12 @@ case "$provider" in
         ;;
 esac
 
-export LINUX_MCP_GATEKEEPER__PROVIDER LINUX_MCP_GATEKEEPER__BACKEND LINUX_MCP_GATEKEEPER__MODEL
+export LINUX_MCP_GATEKEEPER__PROVIDER LINUX_MCP_GATEKEEPER__MODEL
 export LINUX_MCP_GATEKEEPER__COST LINUX_MCP_GATEKEEPER__REASONING_EFFORT
-[[ -n "${LINUX_MCP_GATEKEEPER__QUANTIZATION:-}" ]] && export LINUX_MCP_GATEKEEPER__QUANTIZATION
-[[ -n "${LINUX_MCP_GATEKEEPER__BASE_URL:-}" ]] && export LINUX_MCP_GATEKEEPER__BASE_URL
-[[ -n "${LINUX_MCP_GATEKEEPER__TEMPLATE_KWARGS:-}" ]] && export LINUX_MCP_GATEKEEPER__TEMPLATE_KWARGS
+[[ -n "${LINUX_MCP_GATEKEEPER__OPENROUTER__QUANTIZATION:-}" ]] && export LINUX_MCP_GATEKEEPER__OPENROUTER__QUANTIZATION
+[[ -n "${LINUX_MCP_GATEKEEPER__OPENAI__BASE_URL:-}" ]] && export LINUX_MCP_GATEKEEPER__OPENAI__BASE_URL
+[[ -n "${LINUX_MCP_GATEKEEPER__OPENAI__TEMPLATE_KWARGS:-}" ]] && export LINUX_MCP_GATEKEEPER__OPENAI__TEMPLATE_KWARGS
+[[ -n "${LINUX_MCP_GATEKEEPER__VERTEX_AI__PROJECT:-}" ]] && export LINUX_MCP_GATEKEEPER__VERTEX_AI__PROJECT
 
 variant_suffix=""
 if [[ -n "$variant" ]] ; then

src/linux_mcp_server/config.py

@@ -55,13 +55,7 @@ class GatekeeperProvider(StrEnum):
     ANTHROPIC = "anthropic"
     GEMINI = "gemini"
     OPENROUTER = "openrouter"
-
-
-class GatekeeperBackend(StrEnum):
-    """API backend for the gatekeeper provider."""
-
-    DIRECT = "direct"
-    VERTEX = "vertex"
+    VERTEX_AI = "vertex_ai"
 
 
 class AuthProvider(StrEnum):
@@ -129,39 +123,43 @@ def parse_cost(v: Any) -> Any:
     return v
 
 
-class GatekeeperConfig(BaseSettings):
-    """Gatekeeper Model configuration"""
+class OpenAIGatekeeperConfig(BaseSettings):
+    """OpenAI gatekeeper provider configuration."""
 
-    provider: GatekeeperProvider | None = None
-    backend: GatekeeperBackend = GatekeeperBackend.DIRECT
-    model: str | None = None
+    base_url: str | None = None
+    template_kwargs: dict[str, Any] = Field(default_factory=dict)
 
-    # Model quantization for OpenRouter provider routing (e.g. fp8, bf16)
-    quantization: str | None = None
 
-    # OpenAI-compatible API base URL (OpenAI provider only)
+class OpenRouterGatekeeperConfig(BaseSettings):
+    """OpenRouter gatekeeper provider configuration."""
+
     base_url: str | None = None
+    quantization: str | None = None
+    template_kwargs: dict[str, Any] = Field(default_factory=dict)
+
+
+class VertexAIGatekeeperConfig(BaseSettings):
+    """Vertex AI gatekeeper provider configuration."""
 
-    # GCP project and region for Vertex backends
     project: str | None = None
     location: str | None = None
+    base_url: str | None = None
 
-    # reasoning effort
-    reasoning_effort: ReasoningEffort | None = None
 
-    # Whether we should use structured output
-    structured_output: bool = True
-
-    # Extra chat-template arguments for OpenAI-compatible servers (e.g. llama.cpp enable_thinking).
-    # Passed as chat_template_kwargs on Chat Completions requests.
-    template_kwargs: dict[str, Any] = Field(default_factory=dict)
+class GatekeeperConfig(BaseSettings):
+    """Gatekeeper Model configuration"""
 
-    # Temperature for gatekeeper model
+    provider: GatekeeperProvider | None = None
+    model: str | None = None
+    reasoning_effort: ReasoningEffort | None = None
+    structured_output: bool = True
     temperature: float = 0.0
-
-    # Gatekeeper cost for accounting (input $/token, output $/token)
     cost: Annotated[tuple[float, float] | None, BeforeValidator(parse_cost)] = None
 
+    openai: OpenAIGatekeeperConfig | None = None
+    openrouter: OpenRouterGatekeeperConfig | None = None
+    vertex_ai: VertexAIGatekeeperConfig | None = None
+
 
 class Config(BaseSettings):
     # The '_' is required in the env_prefix, otherwise, pydantic would

src/linux_mcp_server/gatekeeper/anthropic_client.py

@@ -3,15 +3,10 @@
 from typing import Any
 
 from linux_mcp_server.config import CONFIG
-from linux_mcp_server.config import GatekeeperBackend
-from linux_mcp_server.gatekeeper.gcp_auth import get_gcp_access_token
-from linux_mcp_server.gatekeeper.gcp_auth import get_gcp_location
-from linux_mcp_server.gatekeeper.gcp_auth import get_gcp_project
 from linux_mcp_server.gatekeeper.http_utils import ANTHROPIC_API_URL
 from linux_mcp_server.gatekeeper.http_utils import ANTHROPIC_API_VERSION
 from linux_mcp_server.gatekeeper.http_utils import ANTHROPIC_DEFAULT_MAX_TOKENS
 from linux_mcp_server.gatekeeper.http_utils import anthropic_thinking_block
-from linux_mcp_server.gatekeeper.http_utils import ANTHROPIC_VERTEX_VERSION
 from linux_mcp_server.gatekeeper.http_utils import DEFAULT_TIMEOUT_SECONDS
 from linux_mcp_server.gatekeeper.http_utils import get_anthropic_api_key
 from linux_mcp_server.gatekeeper.http_utils import normalize_model_id
@@ -20,7 +15,7 @@
 from linux_mcp_server.gatekeeper.schema import anthropic_output_config
 
 
-def _build_messages_body(prompt: str, *, include_model: bool) -> dict[str, Any]:
+def build_messages_body(prompt: str, *, include_model: bool) -> dict[str, Any]:
     body: dict[str, Any] = {
         "max_tokens": ANTHROPIC_DEFAULT_MAX_TOKENS,
         "messages": [{"role": "user", "content": prompt}],
@@ -36,14 +31,7 @@ def _build_messages_body(prompt: str, *, include_model: bool) -> dict[str, Any]:
     return body
 
 
-def _vertex_url(model: str) -> str:
-    project = get_gcp_project()
-    location = get_gcp_location()
-    host = "aiplatform.googleapis.com" if location == "global" else f"{location}-aiplatform.googleapis.com"
-    return f"https://{host}/v1/projects/{project}/locations/{location}/publishers/anthropic/models/{model}:rawPredict"
-
-
-def _extract_messages_text(response: dict[str, Any]) -> str:
+def extract_messages_text(response: dict[str, Any]) -> str:
     for item in response.get("content", []):
         if isinstance(item, dict) and item.get("type") == "text":
             text = item.get("text")
@@ -53,24 +41,6 @@ def _extract_messages_text(response: dict[str, Any]) -> str:
 
 
 def complete_anthropic(prompt: str, *, timeout: int = DEFAULT_TIMEOUT_SECONDS) -> GatekeeperCompletion:
-    model = normalize_model_id(CONFIG.gatekeeper.model or "")
-
-    if CONFIG.gatekeeper.backend == GatekeeperBackend.VERTEX:
-        body = _build_messages_body(prompt, include_model=False)
-        body["anthropic_version"] = ANTHROPIC_VERTEX_VERSION
-        headers = {
-            "Authorization": f"Bearer {get_gcp_access_token()}",
-            "Content-Type": "application/json",
-        }
-        response = post_json(
-            provider="anthropic",
-            url=_vertex_url(model),
-            headers=headers,
-            body=body,
-            timeout=timeout,
-        )
-        return GatekeeperCompletion(text=_extract_messages_text(response))
-
     headers = {
         "x-api-key": get_anthropic_api_key(),
         "anthropic-version": ANTHROPIC_API_VERSION,
@@ -80,7 +50,7 @@ def complete_anthropic(prompt: str, *, timeout: int = DEFAULT_TIMEOUT_SECONDS) -
         provider="anthropic",
         url=ANTHROPIC_API_URL,
         headers=headers,
-        body=_build_messages_body(prompt, include_model=True),
+        body=build_messages_body(prompt, include_model=True),
         timeout=timeout,
     )
-    return GatekeeperCompletion(text=_extract_messages_text(response))
+    return GatekeeperCompletion(text=extract_messages_text(response))

src/linux_mcp_server/gatekeeper/gcp_auth.py

@@ -10,17 +10,23 @@ class GCPAuthError(RuntimeError):
 
 
 def get_gcp_project() -> str:
-    project = CONFIG.gatekeeper.project or os.environ.get("VERTEXAI_PROJECT") or os.environ.get("GOOGLE_CLOUD_PROJECT")
+    vertex_ai = CONFIG.gatekeeper.vertex_ai
+    project = (
+        (vertex_ai.project if vertex_ai else None)
+        or os.environ.get("VERTEXAI_PROJECT")
+        or os.environ.get("GOOGLE_CLOUD_PROJECT")
+    )
     if not project:
         raise GCPAuthError(
-            "Vertex backend requires a GCP project. Set VERTEXAI_PROJECT, GOOGLE_CLOUD_PROJECT, "
-            "or LINUX_MCP_GATEKEEPER__PROJECT."
+            "Vertex AI provider requires a GCP project. Set VERTEXAI_PROJECT, GOOGLE_CLOUD_PROJECT, "
+            "or LINUX_MCP_GATEKEEPER__VERTEX_AI__PROJECT."
         )
     return project
 
 
 def get_gcp_location() -> str:
-    return CONFIG.gatekeeper.location or os.environ.get("VERTEXAI_LOCATION") or "global"
+    vertex_ai = CONFIG.gatekeeper.vertex_ai
+    return (vertex_ai.location if vertex_ai else None) or os.environ.get("VERTEXAI_LOCATION") or "global"
 
 
 def get_gcp_access_token() -> str: