Local & custom models

Mastery HQ runs any model that speaks the OpenAI-compatible chat API as a first-class agent window — the same streaming chat window you get from OpenRouter, just pointed at your own machine or your own endpoint. That covers two lanes:

• Local servers you already run — Ollama, LM Studio, and Jan — detected automatically, no key.
• Custom endpoints — anything else with an OpenAI-compatible URL: Msty, Together, Groq, or a company gateway. You add its base URL and an optional key.

Local models are private (nothing leaves your machine) and free to run, which also makes them great default picks for the Model Council and the Benchmark.

Auto-detected local servers

If Ollama, LM Studio or Jan is running with at least one model, its models just appear — no setup. Mastery HQ probes their documented default ports (Ollama 11434, LM Studio 1234, Jan 1337) and lists whatever’s installed.

You’ll find them in two places:

• The first-run Setup Wizard → the Local & custom models step.
• Settings → Agents → the Local & custom models section (with a Re-scan button).

Each detected model has an Open button that launches it as an agent window.

Opening a local model

The fastest way is the agent picker: click Open agent in the toolbar and choose Local model (the cyan chip), or say / type “open a local model” in the command bar. Mastery HQ then:

• opens it straight away if there’s exactly one model available,
• shows a small picker if there are several, or
• points you to start a server or add an endpoint if it finds nothing.

A local window streams its replies token-by-token like any other agent, carries its own cyan accent so you can spot it on the canvas, and is a chat/planning window — with optional MCP tools (see below).

Give a local model tools (MCP)

A local window has a 🛠 Tools toggle in its header. Turn it on and the model can call the MCP servers you configured in the MCP Manager — a filesystem, web fetch, a database, GitHub, and so on — turning a chat model into a research/planning assistant with real context.

When it’s on, a send runs a tool-call loop: the model decides which tools to call, Mastery HQ runs them against your servers and feeds the results back, and the model keeps going until it has an answer. Each call it makes appears as a ⚙ line above the reply, so you can see what it did.

A few things to know:

• The model must support tool calling. Many local models do (recent Llama, Qwen, Mistral, and others); a model that doesn’t will simply answer without using tools.
• It uses the servers you already set up. There’s nothing to configure per window — it reads the servers from your MCP Manager setup. If you haven’t added any yet, the window tells you so and answers normally.
• Tools are stdio MCP servers. Remote (HTTP/SSE) MCP servers aren’t used here yet. Any secret keys resolve from your app .env exactly as they do for the coding CLIs.

Custom endpoints

For anything that isn’t one of the auto-detected servers, add it once and it behaves like a saved local model everywhere. In the wizard step or Settings → Agents, fill in:

• Name — what you’ll see in the picker (e.g. Together).
• Base URL — the OpenAI-compatible base, ending in /v1 (e.g. https://api.together.xyz/v1).
• Model id — the model to run (e.g. meta-llama/Llama-3-70b).
• API key — optional. Local servers need none; hosted providers do.

Saved endpoints show up in the Local model launcher and as contestants in the Council and Benchmark, alongside the auto-detected ones.

Where the key lives

A custom endpoint’s optional key is saved in Mastery HQ’s local app data (not the shared .env) and is sent directly on the request to that endpoint. It never leaves your machine except to the endpoint you pointed it at. To change or remove an endpoint (and its key), use Remove in Settings → Agents.

In the Council & Benchmark

Every local model and custom endpoint automatically joins the roster in the Model Council and the Benchmark. Because local servers cost nothing to run, they’re ideal for comparing answers or judging without spending on API calls. Promote a winner to its own chat window from either pane.

Requirements & notes

• Ollama / LM Studio / Jan must be running with a model loaded; use their OpenAI-compatible endpoint (Ollama exposes it at /v1).
• A model that returns an empty response surfaces a clear error rather than a blank window.
• Local windows are for chat, planning, and research. They don’t run a coding CLI or edit files directly, but they can call MCP tools (above) for context. For full coding agents, use a CLI brand (see supported agents).