Skip to content

Quickstart

Store a provider key, send one request through the gateway, and prove a guardrail fires, with the CLI or with curl.

Updated 02 Nov 2026Markdown

You need the Vulnesis CLI, your org UUID and your Vulnesis API key. Both are on Resolve > AI Firewall when you are signed in. Which key is which is on Keys and base URLs.

1. Sign the CLI in

export VULNESIS_ORG_ID=<org-uuid>
export VULNESIS_API_KEY=<vulnetix-api-key>
vulnetix auth status

With both variables set the CLI needs no stored login. vulnetix auth login works too, if it stores an API key.

2. Store a provider key

export OPENAI_PROVIDER_KEY=sk-proj-...
vulnetix ai-firewall key set openai --from-env OPENAI_PROVIDER_KEY

The key is encrypted with KMS and cannot be read back. From now on your applications carry only the Vulnesis key. See Provider keys.

3. Send a request

curl -s "https://guardrails.vulnes.is/openai/$VULNESIS_ORG_ID/v1/chat/completions" \
  -H "Authorization: Bearer $VULNESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Say hello"}]}'

A completion means the request went through the gateway. The same call from Python:

import os
from openai import OpenAI

client = OpenAI(
    base_url=f"https://guardrails.vulnes.is/openai/{os.environ['VULNESIS_ORG_ID']}/v1",
    api_key=os.environ["VULNESIS_API_KEY"],
)
resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Say hello"}],
)
print(resp.choices[0].message.content)

4. Prove a guardrail fires

Guardrails need the Business plan. Add a rule that blocks the word hunter2, then send it:

vulnetix ai-firewall policy guardrail canary \
  --rule-type blocked_pattern --action block --pattern 'hunter2' --priority 1

curl -s -i "https://guardrails.vulnes.is/openai/$VULNESIS_ORG_ID/v1/chat/completions" \
  -H "Authorization: Bearer $VULNESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"my password is hunter2"}]}'

The response is 403 with an OpenAI-shaped error and X-Vulnetix-Firewall-* headers:

{
  "error": {
    "message": "request blocked by AI firewall policy: content matched pattern for policy \"canary\"",
    "type": "policy_violation",
    "code": "request_blocked",
    "blocked_by": "canary",
    "violations": [
      {
        "policy_uuid": "<guardrail-uuid>",
        "policy_name": "canary",
        "rule_type": "blocked_pattern",
        "action": "block",
        "detail": "content matched pattern for policy \"canary\""
      }
    ]
  }
}

A completion here means the request did not go through the gateway, or the org is below Business and guardrails are not loaded. Remove the rule when you are done: find its UUID with vulnetix ai-firewall get -o json, then run vulnetix ai-firewall policy guardrail canary --uuid <uuid> --delete.

5. Wire your tools

vulnetix ai-firewall install --dry-run
vulnetix ai-firewall install
vulnetix ai-firewall status

install writes the gateway into the shell, Claude Code, Codex, Continue and aider configs it finds; status confirms each one is wired. See Wiring clients, or Clients to set one up by hand.

Next

esc
↑ ↓ move↵ openSearches in your browser. A key like autonomy.max or a code like threshold_required jumps straight to it.