Skip to main content

​
Models & Providers

Headmaster connects to model providers you already have API keys for. It does not host models itself. You add a provider, paste a key, and Headmaster can use any model that provider offers. Headmaster supports 28+ LLM platforms — official, cloud, Chinese, international, and custom. All configured from Settings → Headmaster’s Library → Connections → Add provider.

​
Provider catalog

​
Adding a provider

1

Open Connections

Go to Settings → Headmaster’s Library → Connections → Add provider.
2

Pick the provider

Select the provider type from the dropdown.
3

Enter your API key

Paste your API key. You can paste multiple keys (comma-separated or one per line) — Headmaster rotates across them automatically.
4

Test and save

If the provider has a custom base URL, enter it. Click Test connection to verify, then Save.
The provider appears in the Connections list and its models become available in the model selector immediately.

​
Platform-specific setup

  1. Get a key at Google AI Studio — sign in, create a new API key.
  2. Settings → Connections → Add provider → Gemini → paste key → save.
  3. Model list is auto-fetched: Gemini Pro, Ultra, Flash, and image-capable variants.
  1. Create a project at Google Cloud Console, enable the Vertex AI API.
  2. Note your Project ID (format: my-project-123456).
  3. Settings → Connections → Add provider → Gemini (Vertex AI) → enter Project ID + API key → save.
  1. Get a key at platform.openai.com.
  2. Settings → Connections → Add provider → OpenAI → paste key → save.
  3. Models auto-fetched: GPT-4o, GPT-4 Turbo, GPT-3.5 Turbo, o-series, DALL-E.
  1. Get a key at console.anthropic.com.
  2. Settings → Connections → Add provider → Anthropic → paste key → save.
  3. Models auto-fetched: Claude Sonnet, Opus, Haiku.
Two auth methods:
  • Access key: Enter AWS Region, Access Key ID, Secret Access Key.
  • Profile: Enter AWS Region + locally configured AWS CLI Profile name.
Supported regions: us-east-1, us-west-2, eu-west-1, eu-central-1, ap-southeast-1, ap-northeast-1, ap-southeast-2, ca-central-1.
Multi-key rotation is not supported for AWS Bedrock (it uses AWS credential auth, not API keys).
  1. Sign in at openrouter.ai, create a key at openrouter.ai/keys — copy it immediately (shown only once).
  2. Settings → Connections → Add provider → OpenRouter → paste key → save.
  3. 300+ models from many providers appear under a single key.
OpenRouter is the easiest way to get access to many models without managing multiple provider accounts.
  1. Get a key at platform.deepseek.com.
  2. Settings → Connections → Add provider → DeepSeek → paste key → save.
For local models or any OpenAI-compatible endpoint:
  • Enter Base URL + API key + model names.
  • Use any non-empty placeholder for local models without auth.

​
Multi-key rotation

Paste multiple API keys for a single provider — Headmaster rotates across them automatically. Format — comma-separated:
Or line breaks:
Under the hood:
  • Automatic rotation on errors (401, 429, 503) — the failed key is skipped and the next one is tried.
  • Smart blacklist: Failed keys are blocked for 90 seconds, then auto-recover.
  • Load balancing: Random starting key selection spreads load evenly.
  • Per-key logging: Key rotation events are logged.
Multi-key rotation is supported for all providers except AWS Bedrock, which uses AWS credential auth.

​
Model defaults

Open Settings → My Headmaster → Model defaults to set which model new chats start on. Pick a model based on the kind of work:

​
Per-conversation model override

Click the model name at the top of the conversation and pick a new one from the dropdown. The choice sticks for that conversation only — new chats still use your default.

​
Profile model fallback

Each profile can specify a fallback model. If the primary model is unavailable (provider outage, rate limit across all keys), the runtime falls back to the secondary model automatically. Configure in Settings → My Headmaster → Profile → Model fallback.

​
Local models

To use a local model (Ollama, LM Studio, vLLM, llama.cpp):
1

Start your local model server

Make sure it’s listening on a known port.
2

Add as Custom provider

Settings → Connections → Add provider → Custom OpenAI-compatible. Set the base URL to your local server’s address.
3

Save

Leave the API key blank (or use a dummy value if required). The local models appear in the selector.
Local models are free and private — no data leaves your machine. They’re slower and less capable than frontier cloud models, but excellent for offline work, privacy-sensitive data, or cost savings on routine tasks.

​
FAQ

Models appear in the selector, are selectable in a conversation, and you receive normal replies.
Check the format (comma or line break), verify the platform supports multi-key (AWS Bedrock doesn’t), and check the console logs for rotation errors.
Ensure the provider is enabled in Connections, the key is valid, and the model isn’t filtered out by the specialist’s allowed list.
Use the model selector at the bottom-left of the input box. The selection is remembered for that conversation only.

Image Generation

Which providers support image generation and how to set them up.

Connections (MCP)

Extend the agent with external tool servers.