Models

Bring any model with your own key: Anthropic, OpenAI, Google, any OpenAI-compatible endpoint, or a local model runtime.

To add one: open Settings, add a provider and its key, fetch its live model list, and pick a model.

• The picker shows each model's context window and capability badges (tool calling, vision, reasoning).
• It warns you before you pick a model that can't call tools.
• Keys are stored encrypted by the OS keychain and never reach the app's interface.

Each chat keeps its own settings

A chat's model, reasoning effort, and approval mode belong to that chat.

• Changing one in a chat changes that chat only. Other chats, including ones running at the same time, keep theirs.
• Reopening a chat (or resuming it with /resume) brings back the settings it was using. In the terminal, a --provider, --model, --approval, or --full-auto flag given with --continue or --resume wins over the chat's own for that session.
• New chats start from the defaults, and sessions a chat starts begin with its settings.
• If a chat's model is no longer set up, the chat moves to another model of the same provider (or the default model) and says so.

Changing the defaults:

• Desktop app: the controls on the new-chat screen set the defaults, and Use for new chats in an open chat makes its settings the defaults.
• Terminal: add --default to change the default as well as the current chat: /model <id> --default, /reasoning high --default, /approval ask --default.

When a model isn't found

If a provider answers that it doesn't serve a model (the id is mistyped, the model was retired, or your key can't use it):

• the turn ends with a message saying so, instead of the raw error
• the model is marked "Not found" in the picker ("(not found)" in /model) until it answers a request again

Pick another model and retry.

Claude through your cloud account

If your Claude access runs through a cloud account rather than an Anthropic API key, add one of these from the provider picker in Settings:

• "Amazon Bedrock (AWS credentials)"
• "Google Vertex AI"
• "Microsoft Foundry"

Once added, all three behave like the Anthropic provider: the same streaming, extended thinking, and prompt caching.

• Bedrock uses the standard AWS credential chain, so an ~/.aws/credentials profile, an SSO login, or an instance role all work as-is. No API key needed. If you have an Amazon Bedrock API key instead, enter it as the optional key and it takes precedence over your AWS credentials. There's also a separate "Amazon Bedrock (API key)" provider for that case alone.
• Vertex needs no API key either. Run gcloud auth application-default login if you haven't already. The project is usually inferred from your credentials, so leave it blank unless you need a specific one.
• Foundry is the exception: it does take an API key. The resource name is the my-resource part of https://my-resource.services.ai.azure.com.

Model lists. The picker shows each model under one name whichever host you use. None of the three publishes a model list, so Houston ships a curated one, and "Fetch" restores it rather than calling out to the network. If your account can use a model that isn't listed, add its id by hand.

GPT models on Azure OpenAI

Add "Azure OpenAI" from the provider picker to use GPT models on your own Azure resource. Settings needs three things:

• API key from your Azure OpenAI resource.
• Endpoint, the resource URL, such as https://my-resource.openai.azure.com (or export AZURE_OPENAI_ENDPOINT).
• API version, the api-version Azure serves your deployments at. Houston pre-fills a widely supported one. A newer model may need a newer version, which you can change here without waiting for a Houston update.

Models are deployments you name yourself. Azure has no model list to fetch, and Houston ships none. Each model id in the provider's list is a deployment name: add the names you created in the Azure portal, and Houston sends each request to that deployment. One provider entry covers all your deployments.

Dropped connections

When the provider is overloaded, rate-limiting, or drops the connection, Houston retries the turn with a growing pause between attempts and tells you it's retrying.

• No duplicate answers. If part of the reply had already appeared, it's discarded and the turn starts over, so you only ever keep one copy. The desktop app removes the partial text, the terminal marks it as discarded (it can't erase what it printed), and headless mode never writes it to stdout.
• Nothing half-runs. Tool calls in a discarded reply never run.
• Real errors stop. A failure that isn't transient (a bad key, a malformed request) ends the turn instead.

Fallback models

Name backup models for Houston to try when your selected model can't serve a turn:

• the provider is still overloaded or rate-limiting after Houston's retries
• the conversation no longer fits the model's context window, even after compacting
• the provider doesn't serve the model

Set them as an ordered list in settings.json:

"fallbackModels": [
  { "providerId": "openai", "model": "gpt-5" },
  { "providerId": "ollama", "model": "qwen2.5-coder" }
]

• Entries are tried in order and can name any provider you've configured.
• An entry that no longer resolves (you removed the provider, or its key is missing) is skipped rather than failing the run.
• Any part of the reply that had already appeared is discarded before switching, so two models' output is never spliced together. The transcript tells you when a reply came from a fallback.
• A request that failed for its own reasons (a bad key, a malformed request) isn't retried on another model, since it would fail there too.

Leave the list unset to have a failing model simply end the turn.