How model access works

Formal model: /architecture/backend-services · Surface: /concepts/ai-chat · Switch the model: /cli/chat-skills/models

Three modes, one switch

A cmdop agent reaches a model in exactly one of three modes, chosen by the active-provider setting:

You move between them with cmdop provider … (below) or the Desktop provider picker. The agent loop, tools, and permission gate are identical regardless of which mode answers.

The default path — the cmdop model gateway

On the default path, cmdop agents reach models through the cmdop model gateway: an OpenAI-compatible inference surface the relay exposes on the same host as the rest of the agent plane. It is not a separate service you point at — it rides the relay your agent already connects to.

The gateway brokers the major model families behind one shape:

• Chat completions — plain, streaming, and structured (response_format) output.
• Vision / OCR — describe-and-read an image in one call (see view_image below).
• Embeddings and model listing — the resolvable models and tier aliases.

Putting a gateway in front of providers means one place to pick a default, resolve an alias to a concrete model, and route a turn to the right backend — without every agent hard-coding a provider endpoint.

On this path:

1. Your agent presents the sign-in it already holds (the bearer token your agent receives at cmdop login) — the same credential it uses to join the agent plane. There is no separate provider key to configure.
2. The gateway holds platform-supplied provider keys, picks a concrete model (an alias like auto is resolved server-side), and brokers the call upstream.
3. Per-fleet spend and quota are tracked server-side — though, see maturity below, the billing surface around that is planned, not live.

So on the default path, cmdop holds the provider credentials and brokers the call, and your agent reuses one sign-in for both the agent plane and model access — there is no second key to manage.

The escape hatch — bring your own key

If you would rather use your own provider account — or a model the gateway doesn’t broker — add a custom provider. A custom provider is any OpenAI-compatible endpoint, configured with your own key:

cmdop provider add          # add a custom provider (preset or custom URL)
cmdop provider set <id>     # make it the active chat provider
cmdop provider default      # switch back to the cmdop default

When a custom provider is active, chat goes straight to your endpoint with your key — it bypasses the gateway entirely for chat completions. Custom-provider keys are stored locally (mode 0600), never sent to the control plane.

One honest caveat: vision / OCR is gateway-only. With a custom provider (or a local model) active, an image-analysis request returns a clear error telling you to switch to the cloud gateway, rather than silently doing nothing. See Vision and OCR.

Local mode — fully offline

The third mode runs an embedded model on your own machine — no network at all. It is the air-gapped / privacy-first path; nothing leaves your contour. See AI chat for how to download and select a local model.

There is also a built-in resilience behavior tying the cloud and local modes together: if the gateway is unreachable or your sign-in has lapsed, a cloud chat turn automatically degrades to the local model rather than hard-failing. So a logged-out or offline session still answers — quietly, on a small local model — instead of erroring.

Vision and OCR

Reading text or describing an image is one path: the view_image agent tool, served by the gateway. When you attach an image to chat, the agent decides to read it the same way it decides to read a file — there is no automatic OCR-on-attach side effect.

• On the gateway path, view_image describes the image and extracts its text in one call (vision and OCR are just “chat with an image part,” not a separate pipeline).
• On a custom-provider or local path, view_image returns a clear error — image analysis needs the cloud gateway. The failure is visible, not silent.

Two roles for one sign-in

A cmdop agent’s sign-in does double duty: it authenticates the agent to the agent plane (machines, terminal, fleets) and to the model gateway. They are the same credential against the same account store, so there is no second identity to reconcile on the default path.

A custom provider adds a second, local-only credential — your provider key — used only for chat completions to your endpoint, and never sent to the control plane.

This is a clean security boundary: the gateway that brokers model access validates against the same account store the control plane owns, but a model call never transits the live execution path.

Who pays, and what’s metered today

Be clear-eyed about maturity here, because it matters:

• On the gateway path, cmdop supplies the provider keys, so cmdop currently foots the upstream provider bill. Per-fleet spend is tracked server-side, but the metering and billing surface around it is planned, not live — do not read the default path as a metered, paid plan you can buy right now.
• On the custom-provider / local path, you supply the key (or run the model yourself), so you pay your provider directly and there is no gateway dependency for chat.

This matches the honest framing in Pricing: the managed, metered offering is on the roadmap, not shipping. When metering lands, the gateway is the surface it will land on — until then, treat model access as access, not as a billed product.

Related

• Backend architecture: the three planes — where the model gateway sits.
• Custom LLM providers — the bring-your-own-key escape hatch.
• cmdop models — aliases, concrete ids, and switching.
• AI chat — the user-facing chat surface, including local models.
• Pricing & editions — the honest billing picture.