Aider

Aider is a terminal-based pair programmer: it reads the files you add to the chat, proposes edits, and commits them to git. It is configured entirely from .aider.conf.yml and environment variables, which makes it one of the simplest clients to put behind the firewall — you override the OpenAI base URL, and every request it makes goes to the gateway.

Note .aider.conf.yml is commonly committed to a repository so the whole team picks up the same model settings. That is safe here: the file the CLI writes contains a base URL and a model name, never a key. Aider reads the credential from your environment. If you are tempted to put the key in the file instead, see --embed-key below.

Why put Aider behind the firewall

Your provider key never sits in the agent’s config. Aider carries your Vulnetix API key, from the environment. Your OpenAI key stays in the KMS-encrypted BYOK vault and is decrypted just-in-time by the gateway, on the server side of the request.
Every prompt the agent sends is screened by your guardrails — and for an agent, “prompt” means far more than what you typed. Aider puts the full contents of every file you /add into the request, and feeds the output of the commands it runs back into the conversation as tool results. All of it goes through your guardrails.
Provider and model policy is enforced centrally. Aider cannot silently switch to a model your organisation has not approved: the decision is made at the gateway, on every request, not in a local config file a developer can edit.

Quick start

CLI

vulnetix ai-firewall key set openai --from-env OPENAI_KEY
vulnetix ai-firewall install aider --model gpt-4o-mini

That writes .aider.conf.yml with openai-api-base pointing at your organisation’s gateway URL, and model set to the model you asked for. The --model is validated against your organisation’s policy before the file is touched, so you cannot wire a model the gateway would refuse at request time.

vulnetix ai-firewall install aider --scope project --dry-run

--scope project writes the file at the git root, so the whole team shares it. --dry-run prints the exact file and the exact block it would write, and changes nothing.

Then make sure your Vulnetix API key is in the environment Aider inherits:

export VULNETIX_API_KEY=vlx_...
export OPENAI_API_KEY="$VULNETIX_API_KEY"

Aider reads the credential from OPENAI_API_KEY, because it believes it is talking to an OpenAI-compatible endpoint — which it is. The value must be your Vulnetix API key.

Tip vulnetix ai-firewall install shell adds a managed block to your shell rc that exports VULNETIX_API_KEY for you, so every client on the machine picks it up.

Manual

Create .aider.conf.yml — at your home directory for a per-user default, or at the git root of a repository for a per-project one:

openai-api-base: https://guardrails.vulnetix.com/openai/{orgUuid}/v1
model: gpt-4o-mini

Then export the credential:

export OPENAI_API_KEY=vlx_...

Three things to get right:

The base URL does end in /v1 — this is the OpenAI shape. (Anthropic’s is the one that does not; see base URLs.)
OPENAI_API_KEY holds your Vulnetix API key, not an OpenAI key. The variable is named for the protocol Aider speaks, not for the key you should give it.
model is the provider’s own model string, passed through the gateway verbatim.

Never commit the key

vulnetix ai-firewall install aider --embed-key will write the literal key into the file — and refuses, as a hard error, if that path is not git-ignored. It will not help you commit a secret. There is no override. If you need the key in a file, ignore the file first.

How it works

Aider sends POST /v1/chat/completions to https://guardrails.vulnetix.com/openai/{orgUuid}/v1 — the gateway’s chat surface. The gateway authenticates the Vulnetix API key to your organisation, applies provider and model policy, runs your guardrails over every text segment in the request, decrypts your provider key from the vault, and forwards the call. Prompts and completions are never logged.

No local proxy is required. Aider is talking to the gateway directly, over the same protocol it would use to talk to OpenAI.

Because chat is the surface almost every provider serves, you are not tied to openai. Point openai-api-base at openrouter, groq, mistral, deepseek or any other chat provider your organisation has a stored key for, and set model to that provider’s own model string — openai/gpt-4o-mini on openrouter, gpt-4o-mini on openai. The gateway does not rewrite model names.

Verify

vulnetix ai-firewall status

Aider should show as wired:

clients
  aider          wired          .aider.conf.yml
                                https://guardrails.vulnetix.com/openai/{orgUuid}/v1

points elsewhere means .aider.conf.yml exists but openai-api-base names a different endpoint — api.openai.com, or another gateway. That client raises the bypasses_firewall check, and it is the one to act on.

A key_env_unset check means the config is correct but the credential is not in your environment, so Aider will fail with a 401 the moment you run it.

Limitations

Once wired, nothing about Aider bypasses the firewall. It has no built-in models and no background service of its own: every model call it makes — the main edit loop, the commit-message generation, the repo-map summarisation — uses the base URL and credential in this config.

Two honest caveats:

The arguments the model generates for a tool call are not scanned. Prompt content and tool results are; the file edits and shell commands the model emits as tool-call arguments are not.
Aider takes command-line flags that override the config file. --openai-api-base on the command line beats .aider.conf.yml, so a developer can point a single run somewhere else without changing a tracked file. The firewall is a control, not a cage.

Common errors

`401` — invalid Vulnetix API key

{
  "error": {
    "message": "invalid Vulnetix API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Two causes, and they look identical from the outside.

The first is the two-keys confusion: OPENAI_API_KEY is holding an actual OpenAI key (sk-…) instead of your Vulnetix API key. The variable name is misleading — it exists because Aider speaks the OpenAI protocol, not because it wants an OpenAI credential. The gateway authenticates you with the Vulnetix key and supplies the OpenAI key itself, from the vault. Your provider key belongs in the vault, never in the agent.

The second is that the variable is not set at all in the shell Aider was launched from. The CLI catches that locally as the key_env_unset check.

Fix:

Store your OpenAI key in the vault: vulnetix ai-firewall key set openai --from-env OPENAI_KEY.
export OPENAI_API_KEY=vlx_... — your Vulnetix API key.
Run vulnetix ai-firewall status: no key_env_unset check should remain.
Start a new terminal session so Aider inherits the variable.

`403` — `provider_key_missing`

{
  "error": {
    "message": "no OpenAI API key configured for your organisation: add one with 'vulnetix ai-firewall key set openai' or at https://www.vulnetix.com/vdb-ai-firewall#byok",
    "type": "permission_error",
    "code": "provider_key_missing"
  }
}

You are authenticated, but your organisation has no key in the vault for the provider named in your base URL, so the gateway has nothing to forward the request with.

Fix:

export OPENAI_KEY=sk-...
vulnetix ai-firewall key set openai --from-env OPENAI_KEY
vulnetix ai-firewall status — that provider’s row should now show a stored key.

vulnetix ai-firewall install aider refuses to wire a provider with no stored key, so this error usually means the key was removed after the config was written — or that the .aider.conf.yml in this repository was committed by someone whose organisation is not yours.

`403` — `model_not_allowed`

{
  "error": {
    "message": "model gpt-4.5-preview is not in the organisation allowlist",
    "type": "permission_error",
    "code": "model_not_allowed"
  }
}

Your organisation runs an allowlist for this provider, and the model in .aider.conf.yml — or the one you passed to --model on the command line — is not on it. (A model that is explicitly denied returns model_denied instead.)

Fix:

Run vulnetix ai-firewall get to see which models your policy permits.
Re-wire with an approved model: vulnetix ai-firewall install aider --model gpt-4o-mini. The CLI validates the model against policy before writing, so this cannot leave you in the same state.
If the model should be allowed, an administrator adds it to the policy.

`404` — `unsupported_api`

{
  "error": {
    "message": "provider anthropic does not support the OpenAI Chat Completions API (POST /v1/chat/completions). Use POST /v1/messages for anthropic: https://guardrails.vulnetix.com/anthropic/{orgUuid}",
    "type": "not_found_error",
    "code": "unsupported_api"
  }
}

openai-api-base names a provider that does not serve the chat surface. anthropic serves messages only, so it cannot be reached this way — Aider’s OpenAI transport cannot speak to it through the gateway. The same code also appears when the /v1 suffix is missing: the OpenAI shape requires it.

Fix:

Open .aider.conf.yml.
Set openai-api-base to https://guardrails.vulnetix.com/{provider}/{orgUuid}/v1, where {provider} serves chat — openai, openrouter, groq, mistral, deepseek, xai, together, fireworks, alibaba, moonshot or minimax.
Keep the trailing /v1.

The CLI catches this class of mistake locally, before you send a request, as the wire_unsupported check.

Aider

Why put Aider behind the firewall

Quick start

Never commit the key

How it works

Verify

Limitations

Common errors

401 — invalid Vulnetix API key

403 — provider_key_missing

403 — model_not_allowed

404 — unsupported_api

`401` — invalid Vulnetix API key

`403` — `provider_key_missing`

`403` — `model_not_allowed`

`404` — `unsupported_api`