Claude Desktop

The Claude Desktop app can run on models served by this server instead of Anthropic's API, through its built-in third-party inference gateway. Claude keeps its interface, its projects, and its workflow; every token is generated here, on hardware you control, and nothing you type leaves your perimeter. This guide is the end-to-end tutorial; the server also walks you through it interactively at /claude, with every value paste-ready and live feedback when the first request lands.

1What you need#

Three things, all of which you likely have:

• This server, running, with at least one chat model installed. A fresh install pulls one in the admin console in a few minutes. The server's home page lists "Chat in Claude Desktop" among the ways to use it; that card opens a step-by-step setup wizard which enables the gateway, shapes the pools, and connects the app, explaining each step and showing every change for review before it applies. This guide and the /claude page cover the same ground for doing it directly.
• The Claude Desktop app (Windows or macOS), any recent build: third-party inference shipped in 2026 and lives behind its Developer menu.
• The gateway address: open /claude in a browser and it is the first thing on the page, with a copy button.

Nothing is installed and nothing changes on this server; the whole setup is four fields in one Claude Desktop dialog, and switching back is the same dialog.

2The five-minute setup#

On the machine that runs both the server and the app, skip the dialog entirely: the /claude page offers Connect Claude Desktop, and the server writes the app's gateway profile itself (Windows and macOS; Linux has no Claude Desktop build, so the manual path below is the path there). One click does three things:

• Validates the key first, when the server requires one, so a typo is one plain sentence on the page instead of the app failing every turn later.
• Sizes the serving pools for this client's real traffic, as per-model rows in the admin Inference panel; the server-wide defaults stay untouched. Section 4 explains the shapes, the one real decision in this setup.
• Stays reversible: Restore Anthropic setup undoes exactly what connect wrote, rows included.

The page also manages the app itself, because a profile only applies on the app's next start:

• Restart Claude Desktop restarts it in narrated stages: two polite close requests, a forced close if the app ignores them (a tray icon with no window is the usual reason), then the start, each attempt reported on the page as it happens. After a restore, the confirmation offers the same restart.
• One deliberate refusal: when the server itself was started from a Claude Code session inside the app, closing the app would take the server down with it, so the page says exactly that instead of restarting.

From another machine, or by hand, the same four values go into the dialog:

1. Enable Developer Mode. In Claude Desktop, open the Help menu (on Windows it sits in the title-bar menu), choose Troubleshooting, then Enable Developer Mode. Quit the app completely and reopen it.
2. Open the gateway dialog. In the new Developer menu, choose Configure third-party inference.
3. Fill the Connection form:

4. Apply locally and relaunch. When Claude Desktop restarts, choose Continue with Gateway at the sign-in. The model picker now lists this server's models by name, and the /claude page's feedback line turns green on the first turn.

3How the model picker works#

Claude Desktop selects between a small, fixed set of Claude model identities: its families, defaults, and automatic model selection are keyed on them. The gateway therefore advertises those identities and maps each one onto a model you actually have, showing YOUR model's name in the picker. The mapping is derived live from the installed models, so it needs zero configuration and follows every pull and delete:

• standards first, with the version numbers the picker shows: Opus 5 takes gemma4:26b-a4b, Sonnet 5 takes qwen3.5:9b, Haiku 4.5 takes qwen3.5:2b, and Sonnet 4.6 takes gemma4:12b, each whenever that model is installed,
• Fable 5 takes your newest flagship by the family ladder, and any identity whose standard is not installed falls back to the same ladder: family beats raw file size, so a specialized model never outranks a newer general-purpose one; for Haiku 4.5 the fallback is the smallest fast model above the sub-gigabyte floor, because fast is a job, not a race to the tiniest file.

What gets suggested, and what does not:

• Every installed, general-purpose model is in. One installed model yields one picker entry, five or more fill all five identities, and each model appears once, never as several aliases.
• An older version steps aside only when its replacement is installed here. The catalog pointing at a newer model you have not downloaded is a reason to pull it, never a reason to hide the best model you have.
• Task specialists (dedicated translation or OCR models) are never suggested; models you imported yourself always are; unranked families (a coding specialist, an exotic import) serve only the identities the curated families cannot fill.
• You can still pin anything. The pin menu's switch, "Show older versions and task-specific models", reveals the excluded ones under their own "Not suggested" group: a pin is your call even where the policy's answer is no.

The current lineup is always visible on /claude, and an operator changes it right there: click a model to pin a different one on that identity (the row says "pinned"), choose Automatic to hand it back to the policy, or press Reset to automatic to clear every pin at once. Pins persist in the server's settings and apply on Claude Desktop's next model listing; identities you leave alone keep following your installs.

4How the serving pools are shaped#

Each identity in the lineup is served from its own pool with two numbers: a context window (how many tokens one conversation can hold) and a slot count (how many requests decode at the same time). Two facts about Claude decide them:

• The window has a floor. Claude's system prompt and tool schemas alone exceed 70k tokens before you type a word, so every chat identity needs at least 131,072 tokens per slot. The fast identity (Haiku 4.5) only ever carries housekeeping such as connectivity checks and titles, so its floor is 16,384. These are facts about the client, not tuning preferences: below the floor, Claude's own prompts do not fit.
• Slots decide concurrency, not correctness. Claude runs parallel subagents: agent teams, background tasks, and batch commands fan work out to several sessions at once, each sending its own requests. One slot serves all of them correctly but makes them queue; more slots let them decode side by side. Every slot costs device memory at the full window, which is why the default is Auto: at apply time the server measures the widest count the device actually holds, up to four, instead of guessing.

Where you choose. The setup wizard's Serving profile step shows one row per pool: the model, the identities it serves, and its slots and window, prefilled with the current values and floored per identity. Your choices are remembered per identity, so they follow the role even when a different model takes it over later. The rows land in the admin Inference panel, which stays the one place inference is configured; each row's Applies to lane records who manages it (rows in the Claude Desktop lane are refreshed by this activation and removed by its restore; rows in other lanes are yours alone).

Nothing changes without you. The server never rewrites configuration behind your back: pinning a different model, editing a row, or restoring a backup changes exactly what you touched. Instead, the gateway continuously audits the shape each lineup model would REALLY be served at, whatever configured it. When a model sits below its identity's floor (a newly pinned model with no row yet, a row edited down, a removed row), the /claude page shows an alert naming the model, the identity, and the numbers, each lineup row shows its live shape (an amber figure is below the floor), and the home page's Claude Desktop card carries the same warning. The alert's button writes the missing rows only when you click it; a below-floor shape owned by another lane is your explicit call, so the alert points at that row instead of rewriting it.

5Choosing the models yourself#

Prefer to decide exactly what appears? Type model ids into the dialog's Model list instead of leaving it empty: one id per line, using any id this server serves (the same ids the model catalog shows). The picker then lists exactly those, and each request names the model directly with no identity mapping involved. This is also how you pin one specific model for everything Claude Desktop does.

6A team or hosted server#

The same setup scales beyond your own machine; what changes is posture, not protocol (Going Live covers exposure and TLS):

• Use HTTPS and a real key. Beyond loopback, anonymous access is automatically withdrawn: mint a key in Keys and Authentication and put it in the API key field.
• The key must be full-scope. Every gateway call is a POST, so a read-only key cannot even fetch the model list.
• Keep the auth scheme on bearer. This server authenticates the Authorization header; the x-api-key scheme is read for attribution only and will not authenticate.
• Requests land in the request trail like every other call, attributed to the key, so the admin console sees Claude Desktop traffic exactly as it sees the rest.

7Claude Code and the terminal#

The same gateway serves Claude Code, in the app, in a terminal, or in CI, on any machine that can reach this server. No profile and no dialog: two environment variables point the CLI here, and the model flag names any advertised identity or any local model id directly.

ANTHROPIC_BASE_URL=http://127.0.0.1:PORT/claude ANTHROPIC_API_KEY=YOUR_KEY claude --model claude-sonnet-5

On an open loopback install any placeholder (such as lm-kit) serves as the key; beyond loopback, mint a full-scope key. Operators can prove the whole chain in one command with scripts/smoke_claude_gateway.sh, which runs the real CLI through the gateway and fails loudly on any regression.

8What to expect, honestly#

• Conversations, projects, and files work as usual: the app is the same; the model behind it is yours. Answer quality and tool-use reliability follow the local model you picked, not the Claude models the app was built around.
• The app sends housekeeping requests of its own. Claude Desktop uses its fast identity for background work (connectivity checks, titles), so the Haiku-mapped model may load the moment the app opens, before you have sent anything: that is the app's request, not a misrouted chat. The server log names both sides of every routed request (request for 'claude-haiku-...' served by ...), so which model answered what is always one log read away.
• Images degrade gracefully. If the model serving a request has no vision capability, attached images are replaced with a visible notice instead of failing the turn; pick a vision-capable model in the picker when screenshots matter.
• Long conversations follow the model's context window. The gateway reports each model's real limits, so the app's context accounting stays truthful.
• Anthropic-side features stay Anthropic-side. Anything the app implements by calling Anthropic services directly (rather than through the model) is outside what a gateway can provide, whoever the gateway is.
• New conversations warm up fast after the first two. Conversations share Claude's large fixed preamble, and the server learns it: the first two conversations pay the full prompt, and from the third the shared head is restored from cache, so a fresh conversation starts in a few seconds instead of tens.
• Agent features multiply concurrent requests. Subagents, agent teams, and batch commands run as parallel sessions, each with its own requests. With one slot per model those requests queue and agents feel slow but work; more slots let them decode side by side (section 4 is the full story).

9When something refuses#

10Switching back#

Open the same Configure third-party inference dialog and switch the provider back to Anthropic, or pick your Anthropic account at the sign-in. The server keeps serving its other surfaces unchanged; nothing about the gateway lingers in the app beyond the dialog's values.

11Stated plainly#

• Four fields in one dialog turn Claude Desktop into a front end for this server's models; the /claude page hands you every value and confirms the first request.
• The picker shows your models under the hood of Claude's fixed identities, mapped automatically and shown by name; an explicit model list overrides the mapping entirely.
• Same keys, same Bearer authentication, same request trail as every other door into this server; images degrade with a notice rather than failing on text-only models.
• The serving pools have floors set by Claude's own prompts and slots for its parallel agents (section 4); the server audits them continuously, alerts when a model falls below its floor, and never changes configuration without your click.
• This is one of three Claude integrations here: Claude Desktop runs ON your models (this guide), Claude Code does too, in the app or from any terminal with two environment variables (section 7), and both can borrow this server's document tools over MCP.