AIRGAP StudioAIRGAP Studio

Compatibility Proxy

Gateway ensuring compatibility between models and clients (port 11433)

Overview

The Compatibility Proxy is a Node.js HTTP gateway positioned between AIRGAP Studio's LLM-consuming extensions (airgap-assistant, airgap-lite-assistant, airgap-designer, etc.) and llama-server. It automatically normalizes the chat-format differences across some models (such as Mistral) so assistants can operate without worrying about per-model variations.

  • Port: 11433 (proxy) → forward → 11434 (llama-server)
  • Status: Phase 6 (ACCEPTED on 2026-04-29)
  • Location: All traffic stays on loopback (127.0.0.1), enforcing the air-gap policy.

Architecture

[Assistant Extension]
        │
        ▼
http://127.0.0.1:11433/v1   ← Compatibility Proxy (Node.js)
        │
        ▼ (forward + chat format normalization)
http://127.0.0.1:11434       ← llama-server (Vulkan GPU)
        │
        ▼
   [.gguf model]

Automatic Configuration

There is nothing to configure manually. The dev-launcher and installer automatically patch each assistant's endpoint to http://127.0.0.1:11433/v1.

  • airgap-assistant (Cline fork): globalStorage openAiBaseUrl is auto-patched
  • airgap-lite-assistant (Continue fork): config endpoint is auto-patched
  • Patching is idempotent — re-applied each time the assistant activates

Profile Routing

Different chat-format profiles are auto-applied based on the model and client combination. The mapping is defined in the cline.compatProfile field of phase3/models-metadata.json.

ModelProfileNormalization Behavior
Mistral-7B-Instruct-v0.3mistral-strictEnforces Cline XML schema + 3-stage retry escalation
Meta-Llama-3.1-8Bllama31-passthroughCline XML schema (Plan-only validation)
Qwen3 1.7B / 4B / 8Bqwen3-stripStrips think-blocks then validates Cline XML
Granite 4.0 MicropassthroughForwards original response unchanged
Any model + airgap-designer clientdesigner-mistralConverts to OpenAI tool-calls schema

Only the mistral-strict profile performs 3-stage retry escalation (stage1_suffix → stage2_few_shot → stage3_temp_zero) on validation failure. If all stages fail, it returns HTTP 503 with errorCode: model_format_compliance_failed.

Environment Variables

VariablePurpose
AIRGAP_PROXY_PORTProxy listening port (default 11433)
AIRGAP_PROXY_BYPASS=1Bypass the proxy entirely — assistant connects to 11434 directly (debugging)
AIRGAP_DATA_DIRDirectory for proxy jsonl log / state files
AIRGAP_LOG_FILEExplicit path for the proxy log file (default: under AIRGAP_DATA_DIR)

Caveats

  • Do not point assistants directly at port 11434 in their settings. The dev-launcher overwrites the endpoint to 11433 on each startup, which will cause conflicts.
  • When adding a new model, you must set the cline.compatProfile field in phase3/models-metadata.json. Omitting it falls back to passthrough, which may degrade response quality in some assistants.
  • The proxy does not support https:// upstream forwarding (loopback only — air-gap policy).

Debugging

To temporarily disable the proxy and isolate an issue:

# Enable proxy bypass
$env:AIRGAP_PROXY_BYPASS = "1"
# Restart AIRGAP Studio

After resolving the issue, remove the environment variable and restart — the proxy returns to its normal operating mode.