AI model support

Hezo is bring-your-own-model. You connect your own provider accounts, Hezo stores the credentials encrypted (see Master key & encryption), and your agents run on the models you choose.

Supported providers

Each provider is driven through a first-party agentic command-line runtime inside the agent's container. Anthropic, OpenAI, Google, and xAI each use their own CLI (xAI runs on its Grok Build CLI, on the grok-4.5 model); Kimi, DeepSeek, and Z.ai run through Claude Code against their Anthropic-compatible endpoints; OpenRouter runs through the OpenCode CLI; and Ollama and LM Studio run through Claude Code against your own machine.

Every runtime is asked to reason, at the effort level the agent is configured for. On OpenRouter through OpenCode that reasoning is always on: the run asks the model to think at its own effort level rather than answering straight away, and the thinking shows in the run log alongside the tool calls. A model that cannot reason ignores the request.

Where the Runtime column lists more than one, you choose which one that credential runs on. The first is the default, and you never have to pick: adding a key without touching the setting runs it on the default.

Choosing the agent CLI

When a provider can be run by more than one command-line agent, the choice lives under Advanced in the add-provider form, below the API key. A provider that offers only one CLI shows no picker there.

You can also change it later without re-entering the key: on Settings → AI providers, click the CLI name next to the provider and pick another. Existing agents pick up the change on their next run.

Nothing about a provider you have already added changes unless you change it. The account, key and models are the same whichever CLI you pick - only the harness differs. Pick per credential (the Advanced setting), per agent (in the agent's settings) or per task (by pinning the task's runtime).

Two ways to run Kimi

Moonshot's models can be run by either of two command-line agents, on one credential:

• Claude Code, pointed at Moonshot's Anthropic-compatible endpoint. This is the default.
• Kimi Code, Moonshot's own command-line agent.

Hezo used to list these as two separate providers. They are now one Kimi entry with the choice under Advanced; an existing Kimi Code credential keeps running on Kimi Code, and you no longer need a second credential to try the other harness.

Local models

You can run agents entirely on your own hardware, with no per-token cost and no prompt or code leaving your machine. Hezo supports two local model servers:

Both serve Anthropic's Messages API directly, so agents run on the same Claude Code runtime the hosted Anthropic-compatible providers use. There is nothing to translate and no extra proxy to run.

To connect one, pick it in Add AI provider and fill in the Server URL. That is the only field: Ollama ignores an API key, and LM Studio only checks one if you turned on Require Authentication - if you did, put the key under Advanced.

Then choose the model it runs. A local server has no standard model, so adding one finishes only once you pick one. If Hezo cannot load your server's model list, for example because the address works only from inside the agent containers, type the model's name (such as qwen3:32b) in the search box and choose Use with that name. A connection with no model shows Needs a model on the providers list, and its runs fail until you choose one.

Use an address the agents can reach

A localhost address is the common mistake. Agents run inside a container, so localhost there means the container itself, not the machine running your model server, and a URL that works in your browser will fail at run time.

Use one of these instead:

• http://host.docker.internal:11434 - a server on the same machine as Hezo.
• http://192.168.1.50:11434 - a server elsewhere on your network, by its LAN address.

Both only resolve while the container is on the same machine as the server - that is, on local Docker, the default. On a managed sandbox service the container runs on the provider's machines, where these addresses mean nothing - use a model endpoint reachable over the internet instead.

Hezo warns you in the connect form if you enter a localhost address.

Cost and model choice

Local runs cost nothing per token, but they still count their tokens, so budgets apply to local agents exactly as they do to any other.

Pick a model with strong tool-calling ability. Agents work by calling tools in a loop, and smaller local models are noticeably weaker at it than the hosted frontier models. Some capabilities the hosted providers offer are also unavailable locally, including prompt caching and token counting.

API key or subscription

Most providers accept a plain API key, and Anthropic and OpenAI also accept a subscription sign-in (Claude Pro/Max, or ChatGPT) - so you can put an existing plan to work instead of paying per token. You choose the method when you connect the provider; where a subscription is available it is the one offered first, and an API key is a click away. Google is API-key only in Hezo for now: Antigravity has a consumer subscription (Login with Google), but Hezo cannot yet bring its keyring-only sign-in into a run container.

Signing in to a subscription

For OpenAI and Anthropic, Hezo runs the sign-in for you. These two open on the subscription option already selected, so just select Sign in (choose API key instead if that is what you want). Hezo walks you through it a step at a time. First it shows a short one-time code and a Copy code button. Then it offers the link: open it on any device - your phone is fine - sign in to that account, and enter the code. Hezo shows how long the code has left, and waits while you finish.

• OpenAI (Codex) finishes on its own once you complete the sign-in. Nothing to bring back.
• Anthropic (Claude Code) shows you a code at the end of its sign-in page. Paste that code into Hezo to finish. If the code was mistyped or has expired, Hezo says so and offers you a fresh sign-in.

Finish promptly once you have the code. It expires on the provider's clock, which is shorter than the window Hezo keeps the sign-in open for, so a code that sat for several minutes can be refused with nothing wrong at either end. Start again and it works.

Your credential is created inside the sandbox and stored encrypted without passing through your browser, so you never copy an auth file around. Before storing it, Hezo asks the provider whether it works, and tells you if the answer is no rather than saving something that would fail on your first run.

For any instance where the sandbox cannot reach the provider's sign-in page, use Paste credential manually instead and follow the steps the form shows.

Codex refreshes its credential as it runs. Once Hezo holds a Codex subscription, avoid using the same login on your own machine - pick one or the other, or the two will fall out of step.

Runs on a Codex subscription go in parallel, like every other provider. Codex's login token stays usable across concurrent runs, so Hezo runs as many at once as your containers allow and keeps the stored token current as they go. Nothing here limits how many agents share one Codex subscription.

How Hezo paces a subscription

A subscription gives you a usage allowance over a window, a week for Codex and for Claude Code, and the provider tells Hezo how much of it you have used on every response. Hezo uses that figure to spread the allowance across the window, so a fresh week lasts the week instead of going in the first few hours.

By default Hezo lets agents use one day's share of the window straight away, and one more day's share each day after that. A share they do not use carries forward, so the whole allowance is still usable by the end of the window. The last 5% is kept for runs you start yourself.

When agents get ahead of that pace, their work waits in the queue and starts again as the day's share opens up. You get one notice in your inbox the first time this happens in a window. Run now is never paced: a run you start yourself goes ahead, and what it reports keeps the pace current for everyone.

You set the pace per subscription. Open the subscription's Edit dialog in Settings -> AI providers. The pacing section lets you pick even over the week (the default), over five days, or no pacing, or type any daily share from 5% to 100% of the week. It says what that share means in days, and shows where the week stands now. The providers list shows the same line under each subscription, for example "42% of this week used, resets Oct 1, 02:42. Agents are paced to 30% now." Each project's Budget page shows it too, under Subscription usage, since every project shares the same weeks. A new setting takes effect within half an hour, as waiting work checks the pace again. A week appears once a run has read it from the provider.

Budgets still apply as well. A budget limits one agent or project in tokens, and the pace limits the whole subscription in the provider's own measure. Work runs only when both allow it. See Budgets and costs.

An Anthropic subscription does not refresh. Hezo stores the single long-lived token claude setup-token prints and passes it to Claude Code as-is. There is no refresh token behind it, so when that token expires or you revoke it, no run can renew it - sign in again to replace it.

If you paste the credential by hand, paste the token claude setup-token printed and nothing else. The short-lived token inside ~/.claude/.credentials.json starts with the same sk-ant-oat01- characters, so it looks right and is accepted, then stops working within hours. When that happens every run fails at once with an authentication error.

What "verified" means

A credential is marked verified when the provider accepted it, and invalid when the provider refused it. Hezo asks the provider when you add a credential, when you select Verify, and again after a run fails because the provider refused it.

A refused credential is marked invalid and stops being used, so the next run fails immediately instead of starting a container to find out. The credential is shared by every team on the instance, so this stops their runs too - replace it to bring them back.

Only an outright refusal changes the badge. If Hezo cannot reach the provider, or the provider answers with an error of its own, Verify says it could not check the credential and leaves the status exactly as it was: an outage must not take a working credential out of service, and it must not claim a pass either.

Where the provider gives a reason, Hezo repeats it back to you. That reason is the useful part: Anthropic answers OAuth access token is invalid. for a subscription token that has expired or been revoked, and API key is invalid. when what was pasted is an API key rather than a subscription token. The first means sign in again; the second means the credential is the wrong kind for the box it went in.

A Codex subscription cannot be checked this way. Its credential is a sign-in file, not a token any endpoint accepts, so Verify tells you it could not check it rather than reporting a pass. The first real test is a run.

Where to get an API key

Each provider issues API keys from its own console. When you connect a provider, the form in Hezo walks you through these same steps inline.

Most consoles show a newly created key only once - copy it right away and paste it into Hezo, which stores it encrypted. Providers billed per token generally need a positive balance before agents can run. The local servers need no key at all - you give them a server URL instead.

Use more than one

You can connect several providers at once and keep them all available. That's useful for spreading work across accounts, keeping a cheaper model on hand for routine tasks and a frontier model for the hard ones, or having a fallback.

When a key is stored it's checked against the provider and shown as verified (the Verify action re-checks it any time), and Hezo then asks which model the connection should run. That question comes last because the list of models is read from the provider using the key you just gave it. A sensible model is already selected, so you can keep it; either way you can change it later from the connection's row or its Edit panel. A connection always has a model, and every run names it, so updating a coding CLI never changes the model your agents run on. Mark one provider as the default with the star: that's the single global default every agent uses unless it has its own model override.

Adding a connection does not make it the default - use the star for that. Once you do, every agent on the default runs on the new provider from its next run, including a live CEO chat, whose next reply runs on it.

Hezo treats the default as fixed. If the credential you designated stops being usable - the key gets revoked and shows as invalid, say - runs on the default fail and say so, naming the connection. Hezo will not move them onto one of your other connections: a run billing a provider you didn't pick, while the star still sits on the one you did, is the kind of thing that goes unnoticed for weeks. Re-verify the connection, or move the star, and runs resume.

Deleting the default is different, because you removed the designation yourself. The star moves to another connection rather than leaving your instance with none, preferring a verified one and taking the oldest where several qualify. It is visible on the connections list straight away, so you can move it if the pick is not the one you wanted.

Change a stored key

Keys expire, get rotated, or get revoked at the provider. When that happens the connection shows as invalid and agents on it stop running, because Hezo only picks up verified credentials.

Use the pencil at the end of the row to fix it in place. The Edit panel holds the connection's name, its credential, its default model, and - for the providers that offer more than one - the agent CLI it runs on. Paste the new key and save: Hezo checks it against the provider before storing it, and a key that passes clears the invalid state on the spot, so there's no separate Verify step and nothing else about the connection is lost. A key the provider rejects is refused, leaving the stored one exactly as it was.

Leave the credential field blank to keep the key you already have - that's how you rename a connection or switch its CLI without re-pasting anything.

Give an agent its own model

By default the agents on a team share the team's model, but you can override the model for any individual agent. One agent can run on Claude while another on the same team runs on Antigravity or DeepSeek - whatever fits its job. Set it when you hire the agent or any time afterward from its settings. See Hiring & customizing agents.

Wherever you pick a specific model - a provider's default model, or an agent's override - Hezo loads the list of choices live from that provider, so you always see the models your key can actually use. The list is alphabetical and has a search box at the top, which matters on a provider like OpenRouter that offers several hundred: type any part of a model's name or its id to narrow it. This works for a subscription too: a Claude subscription lists the models your plan offers, and a ChatGPT subscription lists the models the Codex version Hezo runs supports. The list is read again each time you open it.

How the starting model is chosen

A connection you add starts on a sensible current model for that provider rather than on nothing, so a key you paste and leave alone still runs. Hezo keeps that starting point fresh by re-reading each connected provider's catalog once a day and following the provider's own naming, so a new generation becomes the starting model without an update to Hezo. It stays within the same class of model, so the choice never jumps to a different price tier or to an image model.

Connections you already have are never changed. The model on a stored connection is yours until you change it, and a refresh only moves the default offered to the next connection you add. If a provider is unreachable when the refresh runs, its previous default stands.

OpenRouter starts on openrouter/auto, OpenRouter's own routing endpoint, which picks a model per request instead of fixing one. That is the routing you signed up for; pick a specific model from the list if you would rather choose yourself.

Local model servers have no pinned default: the catalog is whatever you have pulled, so you pick one of those models when you add the connection. A run on a connection with no model fails and says so, rather than leaving the choice to the CLI.

After an update, Hezo checks each connection's model against what its provider offers now. If a model is no longer offered, you get one notice in your inbox listing the affected connections. The model stays as you set it until you pick another, and runs on it fail at the provider until you do.