AI Configuration

The AI Configuration category controls the AI assistant backend that powers the Ask AI feature and TalonStrike in Hawkra workspaces. You can choose between five providers: Anthropic, DeepSeek, Google Gemini, OpenAI (self-hosted only, linked with a ChatGPT account), or a self-hosted Llama router (llama-swap or any OpenAI-compatible multi-model router).

Choosing a Provider and Model (Admin → AI Configuration)

1. Open Admin → AI Configuration and pick a provider from the LLM Mode dropdown.
2. Only the fields for the selected provider are shown. Enter its API key (or the router URL for the Llama router). OpenAI has no API key: you link a ChatGPT account instead (see OpenAI (Sign in with ChatGPT)).
3. Pick a model from the model dropdown. It lists the provider's currently usable models, fetched live. If the live list cannot be fetched, a built-in fallback list is shown and marked as possibly out of date. OpenAI always uses the fixed list of supported models shown below.
4. If the selected model supports reasoning, a thinking level control appears. Leave it empty to use the provider default. It is hidden for models that do not support reasoning.
5. Click Save, then Test connection to validate the saved settings.

Changes Apply Without a Restart

Changing the provider, model, API key, or thinking level in Admin Settings takes effect immediately for Ask AI, TalonStrike, and the threat-intel briefings. Settings are resolved on every request, so no restart is needed. Environment variables still override database settings when they are set.

Settings Reference

Setting	Key	Type	Default	Description
LLM Mode	llm_mode	Dropdown	gemini	Selects the provider: anthropic, deepseek, gemini, openai, or llama_router. Legacy values are still accepted: cloud maps to gemini, claude maps to anthropic, and local maps to llama_router.
Anthropic API Key	anthropic_api_key	String	Empty	Anthropic API key. Required when LLM mode is anthropic. Get one from Anthropic Console.
Anthropic Model	anthropic_model	Dropdown	claude-sonnet-5-5	Claude model to use. Only applies when LLM mode is anthropic.
Anthropic Workspace ID	anthropic_workspace_id	String	Empty	Optional. Only needed when the API key is not tied to a workspace. A wrong value is rejected, so leave it blank otherwise.
Anthropic Thinking Level	anthropic_effort	Dropdown	Empty	Thinking level: low, medium, high, xhigh, or max. Empty uses the provider default. Only applies to models that support reasoning.
DeepSeek API Key	deepseek_api_key	String	Empty	DeepSeek API key. Required when LLM mode is deepseek.
DeepSeek Model	deepseek_model	Dropdown	deepseek-v4-pro	DeepSeek model to use (deepseek-v4-pro or deepseek-flash). Only applies when LLM mode is deepseek.
DeepSeek Thinking Level	deepseek_effort	Dropdown	Empty	Thinking level: low, high, or max. Empty uses the provider default. Only applies to models that support reasoning.
Gemini API Key	gemini_api_key	String	Empty	Google AI Studio API key. Required when LLM mode is gemini. Get one from Google AI Studio.
Gemini Model	gemini_model	Dropdown	gemini-3.6-flash	Gemini model to use. Only applies when LLM mode is gemini.
Gemini Thinking Level	gemini_effort	Dropdown	Empty	Thinking level: low, medium, or high. Empty uses the provider default. Only applies to models that support reasoning.
OpenAI Account	n/a	Link	Not linked	The linked ChatGPT account. There is no API key; use Link Account (see below). Required when LLM mode is openai.
OpenAI Model	openai_model	Dropdown	gpt-5.5	GPT-5.5 or newer model to use. Only applies when LLM mode is openai.
OpenAI Thinking Level	openai_effort	Dropdown	Empty	Thinking level: low, medium, high, xhigh, or max (gpt-5.5 stops at xhigh). Empty uses the provider default.
Llama Router URL	llama_router_url	String	Empty	Base URL of your llama-swap or OpenAI-compatible router (e.g., http://10.1.2.69:8080). Required when LLM mode is llama_router. The older LOCAL_LLM_SERVER variable is still read as a fallback.
Llama Router Model	llama_router_model	String	Empty	The real model id served by the router (e.g., gpt-oss-120b). This must not be default.

note

The thinking level (*_EFFORT) only applies to models that support reasoning, and only to the levels that model supports.

Gemini Model Options

Model	Description
gemini-3.6-flash	Latest flash model — fast responses with strong quality. Low API cost. Recommended for most use cases.
gemini-2.5-flash	Proven, budget-friendly flash model. Good for high-volume, low-latency tasks.
gemini-2.5-pro	Highest quality. Ideal for complex multi-step analysis.

Claude Model Options

Model	Description
claude-sonnet-5-5	Fast responses with excellent quality. Best balance of speed and capability. Recommended for most use cases.
claude-opus-5-5	Most capable model with deepest reasoning. Ideal for complex multi-step security analysis.
claude-haiku-4-5	Fastest and most cost-effective. Good for simple queries and high-volume usage.

DeepSeek Model Options

Model	Description
deepseek-v4-pro	Default DeepSeek model.
deepseek-flash	Alternative DeepSeek model.

OpenAI Model Options

Model	Thinking levels
GPT-5.5 (gpt-5.5, default)	low, medium, high, xhigh
GPT-5.6 Luna / Sol / Terra (gpt-5.6-luna, gpt-5.6-sol, gpt-5.6-terra)	low, medium, high, xhigh, max
GPT-6 Astra / Luna / Sol (gpt-6-astra, gpt-6-luna, gpt-6-sol)	low, medium, high, xhigh, max
GPT-6.1 Sol (gpt-6.1-sol)	low, medium, high, xhigh, max

The model dropdown in Admin → AI Configuration shows the models currently available for your account, which may differ from the lists on this page (except OpenAI, which always uses the fixed list above).

OpenAI (Sign in with ChatGPT)

Self-hosted only

The OpenAI provider is only available on self-hosted deployments. It is not part of the SaaS build.

Instead of an API key, the OpenAI provider authenticates by linking a ChatGPT account (OAuth with PKCE). Requests use the OpenAI Responses API (streaming) and count against the linked account's ChatGPT plan, not API billing. The tokens are stored encrypted in the database and refreshed automatically.

Linking an Account

1. Open Admin → AI Configuration and select OpenAI as the provider.
2. Click Link Account. A browser tab opens the OpenAI sign-in page, and a dialog appears in Hawkra.
3. Sign in with your ChatGPT account and approve access. Then finish the link using one of the two paths below.
4. When the link succeeds, the button changes to Relink Account. Pick a model and thinking level; each is saved as soon as you select it.

The dialog shows the sign-in link with a Copy button (to paste it into another browser manually), a Manually enter redirect URL here field with Submit, and Cancel.

Automatic path. The Hawkra backend listens on 127.0.0.1:1455 for the OAuth redirect (http://localhost:1455/auth/callback). This only works when your browser runs on the same machine as the Hawkra backend, outside a container. OpenAI only redirects to 127.0.0.1 or localhost, so the callback cannot be pointed at the server's LAN address or domain instead. When Hawkra runs in a container (Docker or Podman), it skips the listener and the dialog says the automatic callback is unavailable.

Manual path (typical for Docker and remote servers). After you sign in, the browser is redirected to http://localhost:1455/auth/callback?code=... and shows a "can't connect" page. That is expected. Copy the full address from the address bar, paste it into Manually enter redirect URL here, and click Submit. Use this path whenever the dialog says the automatic callback is unavailable on this server.

note

Pending sign-ins expire after a few minutes. If Submit reports an expired or invalid state, click Link Account again to start over.

If Submit reports "OpenAI did not issue tokens for this account", OpenAI refused the sign-in for that ChatGPT account. Sign in with an account on a ChatGPT plan that includes Codex.

Once linked, the Account row offers Relink Account and Unlink, and Test Connection sits at the bottom of AI Configuration. The link persists when you switch to another provider and back; only Unlink removes it. As with the other providers, changes apply immediately and no restart is needed.

Setting Up a Local LLM with Ollama

Ollama is a simple way to run a local LLM for Hawkra. It provides an API server that Hawkra can use through the Llama Router provider.

note

The local provider is now called Llama Router (llama_router). It works with llama-swap or any OpenAI-compatible multi-model router. Set Llama Router Model to the real model id the server reports, not default. Message quotas and premium gating are bypassed for the Llama router because it runs on your own hardware.

Option 1: Ollama on the Same Host

If you want to run Ollama alongside Hawkra on the same server, add it to your Docker Compose configuration:

services:
  ollama:
    image: ollama/ollama
    container_name: hawkra-ollama
    volumes:
      - ollama_data:/root/.ollama
    ports:
      - "11434:11434"
    restart: unless-stopped

volumes:
  ollama_data:

After starting the Ollama container, pull a model:

docker exec hawkra-ollama ollama pull llama3

Then configure Hawkra: set LLM Mode to llama_router, Llama Router URL to http://ollama:11434, and Llama Router Model to the model you pulled (e.g., llama3). If Ollama is on a different Docker network, use the host machine's IP address instead of the container name.

Option 2: Ollama on a Separate Machine

1. Install Ollama on the target machine following the instructions at ollama.com/download.
2. Pull a model: ollama pull llama3
3. Ensure the Ollama server is accessible from your Hawkra server on port 11434.
4. Configure Hawkra: set LLM Mode to llama_router, Llama Router URL to http://<ollama-server-ip>:11434, and Llama Router Model to the model you pulled..

Recommended Models

Model	Size
llama3	8B
llama3:70b	70B
mistral	7B
mixtral	8x7B

Configuration via Environment Variables

Setting	Environment Variable
LLM Mode	LLM_MODE
Anthropic API Key	ANTHROPIC_API_KEY
Anthropic Model	ANTHROPIC_MODEL
Anthropic Workspace ID (optional)	ANTHROPIC_WORKSPACE_ID
Anthropic Thinking Level	ANTHROPIC_EFFORT
DeepSeek API Key	DEEPSEEK_API_KEY
DeepSeek Model	DEEPSEEK_MODEL
DeepSeek Thinking Level	DEEPSEEK_EFFORT
Gemini API Key	GEMINI_API_KEY
Gemini Model	GEMINI_MODEL
Gemini Thinking Level	GEMINI_EFFORT
OpenAI Model (optional)	OPENAI_MODEL
OpenAI Thinking Level (optional)	OPENAI_EFFORT
Llama Router URL	LLAMA_ROUTER_URL (LOCAL_LLM_SERVER is still read as a fallback)
Llama Router Model	LLAMA_ROUTER_MODEL

Environment variables override the values saved in Admin Settings when they are set. This includes OPENAI_MODEL and OPENAI_EFFORT. Linking the OpenAI account cannot be done through environment variables; use Link Account in the admin UI.