Models and providers

A model is the AI that reads your message and decides what the agent does next. A provider is the company that runs it. Headmaster comes with its own models, and you can also connect models you already pay for.

This page covers the Headmaster models, every way to connect your own, how the model picker works, and what to do when a model stops working.

How it fits together

Option	Who pays	Where to set it up	Works in
Headmaster Lite	Free during the beta	Nothing to do, it is the default	Cloud, Work, web chat
Headmaster Pro	Free during the beta	Pick it in the model picker	Cloud, Work, web chat
Subscription sign-in (ChatGPT, Claude)	Your subscription	Settings → Providers → Accounts	Signed in per mode
Your own API key	Your provider bills you	Settings → Providers → API keys	Saved to your account, used in Cloud and Work
Custom endpoint or local model	You, or free if it runs on your machine	Settings → Providers → Custom Endpoints or Local Models	Work Mode only

Headmaster models

Every account starts with two Headmaster models. Both are free during the beta.

Headmaster Lite

Fast and light. It is the default for every account and the model new chats use until you pick something else. Good for everyday questions, writing, quick research, and short tasks.

Headmaster Pro

More capable, for longer and harder tasks: multi-step projects, careful reasoning, bigger coding jobs.

Usage limits

During the beta, Headmaster models have usage allowances.

• When you use up the daily Lite allowance, you see: You've used today's Headmaster Lite allowance. Connect your own provider to keep going. It refills the next day.
• There is also a monthly allowance. When it runs out, Headmaster tells you it resets on the 1st of next month.
• Either message has a Connect your provider button. Your own models do not count against Headmaster allowances.

Limits can change during the beta. We note changes in the changelog.

Connect your own models

Your own models appear alongside the Headmaster ones. Your provider bills you directly, under your plan with them.

Option 1: sign in with a subscription

If you already pay for ChatGPT or Claude, you can use that plan without copying a key.

1. Open Settings → Providers → Accounts.
2. Choose Connect an account. ChatGPT is marked Recommended.
3. Headmaster runs the browser sign-in for you inside the app. Finish signing in.
4. The provider shows Connected, and its models appear in the model picker.

Sign-ins are kept per mode. Work and each Cloud runtime sign in separately. In Cloud Mode the page shows Signed in for Cloud or Not signed in for Cloud for each provider. If a model is available in one mode but not the other, sign in again in the mode where it is missing.

To remove a sign-in, choose Disconnect next to the provider.

Option 2: add an API key

An API key lets Headmaster call a provider on your account. Supported providers:

• OpenAI
• Anthropic
• Groq
• Mistral
• DeepSeek
• xAI
• Moonshot
• Z.AI
• NVIDIA
• OpenRouter

To add one:

1. Open Settings → Providers → API keys. Under Your API keys, find the provider.
2. Choose Add, paste the key, and choose Save key.
3. The row shows Saved with the last four characters of your key. The full key is never shown again.

How keys are stored:

• Keys are stored encrypted on your Headmaster account, not on your PC.
• One saved key is used in both Work and Cloud. A change can take a minute to reach Cloud.
• To change a key, choose Replace. To delete it, choose Remove.

If the provider rejects the key when you save it, you see That key was rejected by the provider name. Check that you copied the whole key and that it is active.

OpenRouter is a good choice if you want many models from different companies under one key.

Option 3: custom endpoints and local models (Work Mode)

In Work Mode you can point Headmaster at any OpenAI-compatible endpoint. That includes model servers you run yourself, such as Ollama, llama.cpp or vLLM.

• Settings → Providers → Custom Endpoints for a server on your network or a hosted endpoint with its own address.
• Settings → Providers → Local Models for a model server on this computer.

These pages only appear in Work Mode, because a Cloud runtime cannot reach your computer. Keys for these endpoints stay on the device where you entered them.

In web chat

Web chat has its own Providers settings with the same ideas: In use right now, Sign in with a subscription, Use your own API key, and Your own endpoints. Web chat uses your Cloud runtime, so anything you connect there is for Cloud. See Web chat.

Choosing a model

The model picker

The model picker sits in the chat box. Open it to see models grouped under:

• Headmaster: Lite and Pro.
• Your keys: models from providers you connected.

Use Search models to filter. Each model lists what it is good at, such as Intelligence, Speed and Context (how much text it can keep in view at once). Choose Refresh models if a newly connected provider has not appeared yet.

Picking a model in the chat box changes the model for the chat you are in, right away. The next message uses it.

Model options

Some models have extra options in the picker:

• Thinking and Effort: how hard the model reasons before it answers. Levels run from Minimal and Low up to High and above. Higher effort is slower and uses more of your allowance or plan, but helps on hard problems.
• Fast: a faster service tier, where the provider offers one.

If a model has none of these, the picker says No options for this model.

The default for new chats

Settings → Model → Main model sets the model that new chats start with. In Work Mode it applies to new sessions. In Cloud it sets the model for new chats on this device. To change the chat you are already in, use the picker instead.

When a model is no longer available

If the model you were using goes away, Headmaster moves you back to a Headmaster model and tells you why, for example:

• Your model was reset to Headmaster Lite because your OpenAI key was removed.
• ...because your key can no longer be read.
• ...because the provider is no longer available.

Reconnect the provider, then pick the model again.

Examples

Example: keep going past the daily limit

You hit the Lite allowance mid-afternoon. Choose Connect your provider, sign in with ChatGPT, then pick a ChatGPT model in the picker. The same chat continues on the new model.

Example: one key for everything

You add an OpenRouter key once in API keys. It works in Work Mode on your laptop and in Cloud, including web chat, with no extra setup.

Example: a private model on your own machine

You run a model with Ollama on your PC. In Work Mode, add it under Local Models. Your chats with it never leave your computer for inference. Note that it will not show up in Cloud.

Example: quick vs careful

Use Lite for a quick email draft. For a tricky refactor, switch the chat to Pro, or to your own model with Effort set higher.

Tips

• Lite is enough for most everyday tasks. Save Pro and high effort for hard ones.
• If you use both modes, remember subscription sign-ins are per mode, but API keys are shared.
• A model with a bigger Context handles long documents and long chats better.

Troubleshooting

• "Re-enter your key". Your saved key can no longer be read. Open Settings → Providers → API keys and choose Replace.
• "Sign in again to manage your keys". Your Headmaster sign-in expired. Sign in from Settings → Account.
• "Saving keys is unavailable right now". Try again in a few minutes.
• My ChatGPT models show in Work but not in Cloud. Sign in to ChatGPT again while in Cloud Mode.
• A new model is missing from the picker. Choose Refresh models.
• "Headmaster Lite is temporarily unavailable". Try again shortly, or switch to your own provider.

See also Troubleshooting.