AI Providers

Shannon is provider-agnostic, and you always bring your own key. One setting, SHANNON_AI_MODEL=<provider>:<model-id>, picks the provider and model for the whole scan. Anthropic, OpenAI, xAI, and AWS Bedrock are built in. Any other provider in the Pi harness catalogue works with a single API key, a custom base URL routes any provider through a proxy or LLM gateway, and local models served by Ollama, vLLM, or LM Studio run through a custom model configuration. The default model is anthropic:claude-sonnet-4-6. Keygraph never proxies your model traffic.

Each provider can be configured through the interactive setup wizard (npx mode) or by supplying environment variables directly. In source-build mode, the same variables can live in a .env file. Pick a tab. Your choice is remembered across the site.

Choosing a model

One model runs the entire scan. Set SHANNON_AI_MODEL=<provider>:<model-id>. If it is unset, Shannon uses anthropic:claude-sonnet-4-6.

Suggested model IDs (the setup wizard offers these, best first):

Provider	Suggested model IDs
anthropic	claude-sonnet-4-6, claude-opus-4-8
openai	gpt-5.6-sol, gpt-5.5
xai	grok-4.6, grok-4.5
amazon-bedrock	us.anthropic.claude-sonnet-4-6, us.anthropic.claude-opus-4-8

The wizard also takes a typed model ID, and SHANNON_AI_MODEL accepts any model in the provider’s catalogue. The older ANTHROPIC_SMALL_MODEL, ANTHROPIC_MEDIUM_MODEL, and ANTHROPIC_LARGE_MODEL variables no longer do anything.

Shannon refreshes the model catalogue over the network at scan start, so a newly released model on a catalogue provider resolves without upgrading Shannon. The refresh is bounded and falls back to the built-in catalogue if it times out.

Cyber safeguards (do this before your first scan)

Anthropic and OpenAI both apply real-time safeguards to security workloads, and a Shannon scan is one. If a safeguard engages mid-run, the model can refuse and the scan stops partway through rather than at the start. Review each vendor’s guidance and complete the verification or enrollment they ask of legitimate security testers before you run Shannon:

• Anthropic: Real-time cyber safeguards on Claude Opus and Sonnet
• OpenAI: Cyber

This applies to the Anthropic and OpenAI providers, including when either is reached through an LLM gateway. Bedrock serves Claude models and is subject to Anthropic’s safeguards as well.

Anthropic

npx (recommended)

Run the setup wizard:

npx @keygraph/shannon@latest setup

Or export a key and model directly:

export SHANNON_AI_API_KEY=sk-ant-...
export SHANNON_AI_MODEL=anthropic:claude-sonnet-4-6

Build from source

Add your credential and model to the .env file:

SHANNON_AI_API_KEY=sk-ant-...
SHANNON_AI_MODEL=anthropic:claude-sonnet-4-6

Anthropic, OpenAI, and xAI also accept their native variables (ANTHROPIC_API_KEY, OPENAI_API_KEY, XAI_API_KEY). When the selected provider’s native variable is set, it takes precedence over SHANNON_AI_API_KEY. Shannon forwards only the selected provider’s credential into the scan container.

Switching provider

The pattern is the same for every provider: export the provider’s key and name the model. Two lines change, nothing else.

OpenAI:

export SHANNON_AI_API_KEY=sk-...
export SHANNON_AI_MODEL=openai:gpt-5.6-sol

xAI:

export SHANNON_AI_API_KEY=xai-...
export SHANNON_AI_MODEL=xai:grok-4.6

Source-build mode reads the same variables from the .env file.

AWS Bedrock

Run npx @keygraph/shannon@latest setup and select AWS Bedrock, or set the variables directly:

npx (recommended)

export AWS_REGION=us-east-1
export AWS_BEARER_TOKEN_BEDROCK=your-bearer-token
export SHANNON_AI_MODEL=amazon-bedrock:us.anthropic.claude-opus-4-8

Build from source

AWS_REGION=us-east-1
AWS_BEARER_TOKEN_BEDROCK=your-bearer-token
SHANNON_AI_MODEL=amazon-bedrock:us.anthropic.claude-opus-4-8

Bedrock uses bearer-token authentication only. IAM access keys, session tokens, assumed roles, and instance profiles are not supported. The model must be enabled in your region.

Any other provider

Shannon accepts any provider and model in the Pi harness catalogue (browse them at pi.dev/models), as long as the provider’s credential is a single API key. Name the provider in SHANNON_AI_MODEL and supply its key in SHANNON_AI_API_KEY:

export SHANNON_AI_API_KEY=your-api-key
export SHANNON_AI_MODEL=openrouter:moonshotai/kimi-k3

Providers that need more than a single API key are not currently supported. The setup wizard offers this path as Other provider, with an optional base URL to route that provider through a proxy or LLM gateway.

Custom base URL

SHANNON_AI_BASE_URL routes model traffic through a proxy or LLM gateway, such as LiteLLM, instead of the provider’s default endpoint. It changes only where requests go: the provider named in SHANNON_AI_MODEL still decides which credential is sent and which API dialect is spoken. An anthropic: model needs an endpoint that speaks Anthropic Messages, and an openai: model needs one that speaks OpenAI Responses. Servers that speak only Chat Completions (Ollama, vLLM, LM Studio) are reached through a custom model configuration passed with --models-config. See Local and self-hosted models.

Model capability varies

Models are validated against the harness catalogue, but a model that does not follow Shannon’s instructions or tool-use constraints reliably will produce weaker pentests. Evaluate the model you choose against your own targets before depending on its results.

Run npx @keygraph/shannon@latest setup and select Custom Base URL, or set the variables directly:

npx (recommended)

export SHANNON_AI_API_KEY=your-gateway-key
export SHANNON_AI_MODEL=anthropic:claude-sonnet-4-6
export SHANNON_AI_BASE_URL=https://llm-gateway.example.com

Build from source

SHANNON_AI_API_KEY=your-gateway-key
SHANNON_AI_MODEL=anthropic:claude-sonnet-4-6
SHANNON_AI_BASE_URL=https://llm-gateway.example.com

The model ID must still resolve in the harness catalogue. A gateway that serves a model under its own name needs that name described in a custom model configuration file.

Local and self-hosted models

Ollama, vLLM, LM Studio, and other OpenAI-compatible servers are reached through a custom model configuration. Describe the server as a provider in a models.json file, pass the file with --models-config, and name its model in SHANNON_AI_MODEL.

Use host.docker.internal, not localhost

The scan runs inside a container, so localhost points at the container itself rather than at your machine.

A models.json for Ollama:

{
  "providers": {
    "ollama": {
      "baseUrl": "http://host.docker.internal:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        { "id": "<model-id>" }
      ]
    }
  }
}

Then name the model and run:

export SHANNON_AI_API_KEY=ollama
export SHANNON_AI_MODEL=ollama:<model-id>
npx @keygraph/shannon@latest start -u https://your-app.com -r /path/to/your-repo --models-config ./models.json

In source-build mode, pass the same flag to ./shannon start. LM Studio and vLLM take the same shape on their own ports, http://host.docker.internal:1234/v1 and http://host.docker.internal:8000/v1. The provider name is yours to choose; it only has to match the prefix in SHANNON_AI_MODEL. SHANNON_AI_API_KEY is still required even though a local server ignores it, so set it to any placeholder value.

Some servers need compatibility flags. If a reasoning-capable model is rejected, turn off the roles it does not understand, at either provider or model level:

"compat": { "supportsDeveloperRole": false, "supportsReasoningEffort": false }

Local model capability

Shannon drives every phase through multi-turn tool use. A model that does not follow Shannon’s instructions or tool-use constraints reliably produces weaker pentests than a frontier model, so take this path only if you know how your chosen model behaves.

Custom model configuration

The same --models-config file also reaches a hosted model the catalogue does not carry, such as one a router or gateway serves under its own ID. Shannon merges the file’s definitions over the catalogue, and they take precedence over it, so SHANNON_AI_MODEL can then name the model like any other.

pi.dev/models supplies the file contents. Find the model under the provider you want, since the same model has a different ID per provider, then open its page and expand Show configuration for a ready-to-paste snippet. A trimmed example for a router model:

{
  "providers": {
    "openrouter": {
      "apiKey": "YOUR_API_KEY",
      "api": "openai-completions",
      "baseUrl": "https://openrouter.ai/api/v1",
      "models": [
        { "id": "z-ai/glm-5.3", "name": "Z.ai: GLM 5.3", "reasoning": true, "contextWindow": 1048576 }
      ]
    }
  }
}

Then name the model the usual way:

export SHANNON_AI_API_KEY=your-api-key
export SHANNON_AI_MODEL=openrouter:z-ai/glm-5.3

Leave YOUR_API_KEY exactly as it is. Shannon sends the credential from your environment, which takes precedence over anything the file declares, so the file describes the model and never has to hold a secret. Pi’s models documentation describes the full format, including routing preferences and compatibility flags.

Subscriptions

A ChatGPT Plus or Pro (Codex) subscription or an xAI (Grok) subscription can run Shannon by reusing a login created by Pi. Complete the cyber safeguards steps first. Then install Pi by following the instructions at pi.dev and log in with your subscription using Pi’s subscription authentication guide. This creates ~/.pi/agent/auth.json.

Enable Pi authentication and select a model:

export SHANNON_USE_PI_AUTH=1
export SHANNON_AI_MODEL=openai-codex:gpt-5.5   # or xai:grok-4.6

Run npx @keygraph/shannon@latest start from the same shell. In source-build mode, add the two variables to .env and run ./shannon start. Supported Codex models are gpt-5.6-sol, gpt-5.5, and gpt-5.4. Suggested Grok models are grok-4.6 and grok-4.5.

Claude Code subscriptions work only on Shannon 1.9.0 (npx @keygraph/shannon@1.9.0 setup), the final release built on the Claude Agent SDK. The current version does not support them.

Validation

Checks run before a scan starts, so a mistake fails immediately rather than partway through a run:

• Provider and model ID are validated against the Pi harness catalogue. An unknown provider or model ID fails preflight with a pointer to pi.dev/models. To run a model the catalogue does not carry, describe it with --models-config.
• Model configuration: when --models-config is passed, the file is parsed and schema-checked before the scan starts, and a fault fails preflight with the offending field named.
• Credential presence is checked for the selected provider, or read from Pi when SHANNON_USE_PI_AUTH=1.
• Credential validity is checked with one minimal request against the model the scan will use, so a rejected key, an exhausted quota, or a model the account cannot reach fails before any agent runs. Bedrock goes through the same probe.

Upgrading from earlier versions

Before	Now
SHANNON_AI_OPENAI_FORMAT (2.x)	Removed in 3.1. An openai: model with a base URL always speaks OpenAI Responses. A Chat Completions-only endpoint goes through a custom model configuration with "api": "openai-completions".
A custom base URL exempted the model ID from catalogue validation (2.x)	The model ID must resolve in the catalogue, or be described with --models-config.
ANTHROPIC_SMALL_MODEL, ANTHROPIC_MEDIUM_MODEL, ANTHROPIC_LARGE_MODEL (1.x)	A single SHANNON_AI_MODEL.
CLAUDE_CODE_USE_BEDROCK=1 plus three Bedrock model IDs (1.x)	SHANNON_AI_MODEL=amazon-bedrock:<model-id>.
ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN (1.x)	SHANNON_AI_BASE_URL overrides the endpoint; SHANNON_AI_MODEL selects the provider.
Google Vertex AI (1.x)	No longer supported. Switch to Anthropic, AWS Bedrock, or an Anthropic-compatible base URL.

In ~/.shannon/config.toml, the [models] section and bedrock.use are gone, each provider has its own section, and the model lives at core.model. Re-run npx @keygraph/shannon@latest setup to regenerate the file.