---
title: "Models and speed"
description: "Choose models, reasoning effort, and speed tiers to fit the work and your budget."
canonical_url: "https://hoplite.sh/docs/agent/models"
markdown_url: "https://hoplite.sh/docs/agent/models.md"
---

# Models and speed
URL: /docs/agent/models
LLM index: /llms.txt
Description: Choose models, reasoning effort, and speed tiers to fit the work and your budget.
Related: /docs/workspace/billing, /docs/agent/slash-commands, /docs/threads/cost

# Models and speed

Choose the model and execution settings that fit your task. Pick a model in the new-thread dialog, switch mid-thread with [`/model`](/docs/agent/slash-commands), or set a project-wide default under **Settings → Project → Agent**.

## Available models

The model picker reflects the models available to the selected workspace and connected accounts. Availability depends on the plan, provider, and whether a subscription or gateway is connected. Models marked as requiring an upgrade cannot run through platform billing on Free.

For API integrations, discover the current catalog through [List models](/docs/api/listModels) rather than hard-coding picker labels. The factory example uses this endpoint before creating a thread.

The picker groups models by provider. Search across providers, star models to keep them in **Favorites**, or use **Edit models** to reorder or hide entries. These preferences follow your account across devices.

### Long context

Standard and long-context offers share one model choice. Platform and BYOK runs automatically use the larger window when the catalog has an offer eligible for your workspace and plan. Subscription routes use that window only when the offer supports their backend; custom gateways use their own reported window.

Each call is billed at the tier the provider actually charged, rather than the picker label. Provider-reported cost takes precedence; otherwise Hoplite uses reported usage and the catalog's pricing rule, including cached input in the threshold. The usage record identifies the billed tier. See [Cost](/docs/threads/cost).

## Reasoning effort

Reasoning effort trades latency and cost for depth: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. The picker only shows the levels the selected model actually supports. Reasoning tokens are billed as output tokens.

A run uses the effort chosen for the thread or message first, then the project's default. If neither is set, it uses the model's own default effort when the catalog defines one, and `medium` otherwise; the picker preselects that level. The result is always clamped to a level the model supports.

### Retired models

A retired model disappears from the picker for new threads and model switches, but threads already on it keep running on that exact model. If the provider fails a request outright (rate limits that outlast retries, an outage, or the model being withdrawn), that run continues on the catalog's replacement and the thread shows a notice; the thread moves to the replacement only when the provider no longer serves the model. A model removed from the catalog entirely fails with a **Model retired** error asking you to pick another model.

## Speed

Models with a fast tier (currently the GPT family) offer a **standard / fast** toggle. Fast maps to a priority service tier — same model, quicker output.

## Automatic ChatGPT / API routing

There is one model list — no separate `codex/` copies. If you connect ChatGPT under **Settings → Integrations → Personal**, supported OpenAI models automatically use that subscription and are **billed to your ChatGPT plan, not your workspace credits**. For models eligible for platform billing, Hoplite can use the platform API when no eligible subscription is available. On Free, models unlocked only by a connected ChatGPT subscription stop with an error if that connection is lost; they do not silently switch to platform billing. Usage is still recorded on the [usage page](/docs/workspace/billing), with the actual payer tracked per call.

## Claude Code subscription routing

Connect your Claude subscription under **Settings → Integrations → Personal**.
Run `claude setup-token` on your own machine and paste the generated token.
Hoplite stores the token encrypted and never returns it after saving.

Eligible cloud runs can use the initiating member's connected Claude subscription. The connection stays outside the thread sandbox. If the member or model is ineligible, Hoplite uses the ordinary platform or BYOK route instead. Check usage attribution to confirm which route a run used.

## Bring your own provider keys

When BYOK is enabled for a workspace, its owners and admins can manage direct Anthropic and OpenAI API keys under **Settings → Workspace → Models**. Keys are encrypted and can be replaced or removed at any time. Saved keys may show a masked prefix and suffix; the full key is never returned.

Compatible runs use the workspace key for their selected provider; when that provider has no configured workspace key, Hoplite falls back to its platform credentials. This workspace-level provider routing is separate from a person's ChatGPT subscription connection. See [Cost](/docs/threads/cost) for how BYOK runs are badged in the cost breakdown.

## Account order and fallback

**Settings → Workspace → Models** manages account order, routing preferences, and compaction. Eligible personal subscriptions are tried before workspace keys or gateways, then Hoplite credits, respecting saved account order and an eligible model-specific **Run on** preference. Owners and admins choose whether personal accounts are allowed and whether members can override the workspace fallback rule. Eligible Codex, Claude, and Grok connections can be managed or reconnected here; availability still depends on rollout and model eligibility.

When an account reaches its usage limit, the fallback rule determines the next step:

- **Ask every time** stops for direction; this is the default.
- **Confirm before credits** tries another eligible account automatically but asks before spending Hoplite credits.
- **Continue automatically** tries the next eligible account, including credits.

Account-limit fallback keeps the selected model. A temporary rate limit alone does not trigger this account-switching policy. Automatic conversation compaction defaults to 60% of the model's context window; owners and admins can choose 20–90% and set model-specific overrides.

## Provider outages

Before any text, reasoning, or tool interaction has committed, an eligible platform-funded main-agent call can switch to a compatible model from another provider after transient failures exhaust retries, or while that provider is in cooldown. The alternative must preserve required capabilities, plan eligibility, context, effort, and speed without increasing applicable token rates. Some selections have no compatible fallback.

This does not change the thread's selected model permanently; usage is attributed to the model actually used. Subscription, BYOK, gateway, and child-agent routes do not enter this outage chain. Failures after output begins are not replayed, and authentication, billing, quota, policy, and cancellation errors do not trigger outage fallback.

## Model gateways

Workspaces with custom gateways enabled also get **Model gateways** on **Settings → Workspace → Models**. Owners and admins add a gateway with its credential, Hoplite verifies it against the provider and discovers its models, and every verified model then appears in the composer's model picker for the whole workspace. Gateway usage is billed by the account behind the gateway, so runs on these models carry the BYOK badge in the cost breakdown.

Supported gateway kinds:

| Gateway | What you enter |
| --- | --- |
| **Neon AI Gateway** | Branch host and API key |
| **OpenRouter** | API key |
| **Vercel AI Gateway** | API key |
| **Cloudflare AI Gateway** | Account ID / gateway ID and API token |
| **OpenAI-compatible endpoint** | A public `https` base URL (no credentials, query string or fragment), a display label, the API key, and optional static headers (up to 16; `Authorization` and `Host` are reserved) |

Hoplite verifies an OpenAI-compatible endpoint by listing `/models` and running a streaming tool-call probe, and it shows the endpoint's own error response when verification fails so you can fix the configuration. Models served through such an endpoint are labelled with the connection label in the picker (for example **GLM-5 · my-endpoint**) so they are easy to tell apart from platform models with the same name.

## Sitemap

Sitemap discovery is not enabled for this deployment.