Providers & models

Connect OAuth subscriptions, API-key providers, or a local model — and switch models any time.

A provider is the service hosting AI models; a model is the specific one you talk to. Tau ships with several built-in providers and lets you add your own OpenAI-compatible endpoints (including local models).

The fastest setup: /login

Start Tau and use /login to connect a provider. The provider picker includes a search field, which is especially useful for the longer API-key provider list:

tau

/login              # choose a login method
/login openai       # save an OpenAI API key
/login openai-codex # authenticate a Codex/ChatGPT subscription via OAuth
/login anthropic-subscription # authenticate Claude Pro/Max via OAuth
/login anthropic-api # save an Anthropic API key
/login github-copilot # authenticate GitHub Copilot with a device code
/login opencode-go  # save an OpenCode Go API key
/login nvidia       # save an NVIDIA NIM API key
/login custom       # add an OpenAI-compatible custom provider

Built-in providers include OpenAI, Anthropic, OpenAI Codex (subscription), GitHub Copilot, OpenCode Go, OpenCode Zen, Moonshot AI (Kimi), Kimi Code (subscription), OpenRouter, Hugging Face, and NVIDIA NIM.

OAuth subscriptions

Choose Subscription / OAuth in /login for:

GitHub Copilot asks for a GitHub Enterprise Server URL/domain. Leave it blank for github.com. Device login also works in SSH/headless sessions: open the shown verification URL on any device and enter the displayed code.

Anthropic uses distinct direct-login aliases so the authentication method is unambiguous: /login anthropic-subscription starts OAuth, while /login anthropic-api saves an API key. The top-level /login picker still lists Anthropic under both Subscription / OAuth and API key. OAuth subscription requests use Anthropic’s required Claude Code identity and may be billed as extra usage rather than consuming ordinary Claude plan limits. Check Anthropic’s current account terms before using it.

OAuth tokens refresh automatically. /logout removes Tau’s local credential, but does not revoke the grant remotely; use the provider’s account settings for remote revocation.

OpenAI prompt caching

For direct OpenAI API and Codex OAuth sessions, Tau sends a stable session-derived prompt-cache key with every model request, including continuations after tool calls. OpenAI can use that key to keep successive append-only requests on the same cache path, improving reuse of the system prompt, tool schemas, and conversation prefix. Resuming a Tau session reuses its key; starting or branching a session creates a new one.

Requests remain stateless: Tau keeps provider storage disabled and resends the complete transcript. The key improves cache affinity but cannot preserve a hit if the prefix changes or the provider cache expires. OpenAI-compatible gateways do not receive these fields unless their catalog compatibility settings explicitly opt in. The TUI sidebar’s latest-request cache rate shows whether the most recent request actually hit.

Anthropic prompt caching

Tau marks cache breakpoints on Anthropic requests so the system prompt, tool schemas, and conversation history are reused between turns instead of being reprocessed. Which retention Tau asks for depends on how you authenticated:

• Claude Pro/Max via OAuth requests the one-hour cache. Subscription auth is not billed per token, and the five-minute default is shorter than a build, a test run, or the time it takes to read a diff — any of which would otherwise expire the cache mid-session.
• An Anthropic API key uses the five-minute default, because one-hour cache writes cost more per token and that should be a deliberate choice.

Providers that speak the Anthropic protocol through a gateway rather than being Anthropic itself — minimax, minimax-cn, fireworks, and vercel-ai-gateway — send no cache breakpoints, since not every gateway accepts them. Watch the sidebar’s cache hit rate to see caching working; see The interactive session for how to read it.

Codex subscription context limits

OpenAI’s public API and the ChatGPT/Codex subscription are separate serving surfaces. A model with the same ID can have a smaller, rollout-specific context window through Codex OAuth than through an API key. For example, the public GPT-5.6 Sol API advertises a 1.05M-token window, while Codex has advertised substantially smaller limits through its authenticated model catalog.

Tau queries that catalog when a Codex session starts and uses the returned context window and automatic-compaction threshold for the session. If discovery is unavailable, Tau falls back to conservative Codex-specific values from its built-in catalog; it does not reuse the public API limit. /session reports both the active value and whether it came from the live provider catalog or Tau’s configured fallback.

Live limits can vary by account or rollout and may change independently of Tau. A discovery failure is non-fatal: Tau reports it in /session and continues with the fallback. Direct OpenAI API sessions retain the context limits documented on the API model page. Vision-capable Codex models retain their image-input metadata separately from these runtime context limits, allowing image files read by Tau to reach the model. The gpt-5.6 alias, which routes to GPT-5.6 Sol, is only available through the direct OpenAI API; Codex subscription users should select the explicit gpt-5.6-sol model instead. Tau tombstones the API-only alias for the Codex provider, so older user catalog overlays and saved preferences cannot restore it after an upgrade.

OpenCode Go and Zen

OpenCode Go and OpenCode Zen are API-key providers, not OAuth providers. Sign in at the OpenCode console, subscribe to Go or fund Zen, copy the API key, and then run:

/login opencode-go  # subscription limits; https://opencode.ai/zen/go/v1
/login opencode     # Zen pay-as-you-go; https://opencode.ai/zen/v1

Both can also read OPENCODE_API_KEY. Tau stores their saved credentials under separate opencode-go and opencode names, allowing different keys when needed. Available models and plan limits change over time; consult the OpenCode Go and OpenCode Zen pages for the current list.

Hugging Face Inference Providers

Log in with /login huggingface or set HF_TOKEN. Tau’s built-in Hugging Face catalog includes 47 coding-capable models routed through https://router.huggingface.co/v1, including DeepSeek, Gemma, GLM, GPT OSS, Kimi, Llama, MiniMax, MiMo, Qwen, and Step families. This includes moonshotai/Kimi-K3, with text and image input, a 1,048,576-token context window, and low, high, and max reasoning effort. Tau exposes max as its xhigh thinking level. Use /model to search the full list; model availability and the inference provider selected by Hugging Face can vary over time and by account.

For a new session without an explicit preference, Hugging Face initially routes the model automatically. After the first successful response, Tau reads Hugging Face’s x-inference-provider response header and pins that backing provider for the rest of the session. To choose the initial provider instead, add a per-model inference_providers preference to ~/.tau/providers.json:

{
  "schema_version": 2,
  "default_provider": "huggingface",
  "provider_preferences": {
    "huggingface": {
      "default_model": "zai-org/GLM-5.2",
      "inference_providers": { "zai-org/GLM-5.2": "deepinfra" }
    }
  },
  "scoped_models": []
}

Use the exact provider suffix advertised for that model by Hugging Face. Tau sends zai-org/GLM-5.2:deepinfra on the wire and continues to display and store the logical zai-org/GLM-5.2 model. The pin survives resume; changing the preference does not rewrite existing sessions. /session shows the active pin. Route selection is available through the external alejandro-ao/tau-huggingface extension rather than a built-in command. It requires Tau 0.3.10 or newer. Clone and load it explicitly:

git clone https://github.com/alejandro-ao/tau-huggingface.git
tau -e ./tau-huggingface

Then use /route <provider> to select a route or /route automatic to reset it. Switching models uses that model’s configured pin or starts automatic resolution again.

Transient failures retry on the same wire model, and stream failures are not retried after model output has started. Pinning can reduce cold prefix-cache misses caused by cross-provider routing, but cannot prevent eviction, TTL expiry, or load balancing among workers within the chosen provider. Tau does not yet fall back automatically from an unavailable pinned route: doing so also requires a user-visible reroute event and durable reroute telemetry. Use the Hugging Face extension or start a new automatic session to resolve another route. See Configuration.

Moonshot AI API vs. Kimi Code

Both Kimi providers authenticate requests with Bearer API keys; neither uses OAuth. They are separate because the keys come from different consoles, use different endpoints, and charge against different billing plans:

Kimi K3 uses the k3 model ID, accepts text and image input, and supports up to a 1,048,576-token context window on eligible plans. It supports three reasoning-effort levels via the reasoning_effort field: low, high, and max (default). Tau exposes these as the low, high, and xhigh thinking levels respectively, and starts new K3 sessions at xhigh unless a remembered per-model choice exists. Start a new session when switching to K3 so the previous model’s context cache is not re-prefilled. See Kimi’s model documentation for current plan availability and context limits.

A key for one service should not be treated as interchangeable with a key for the other. Tau stores them independently under the moonshotai and kimi-code credential names, so /login moonshotai and /login kimi-code can configure both at once. The distinct environment variable names provide the same separation when credentials are supplied through the shell.

Credentials saved through /login live in ~/.tau/credentials.json with private 0600 permissions and atomic file replacement. The file is not encrypted; protect your Tau home directory and do not share its contents. The custom-provider flow asks for the provider name, display name, base URL, API-key environment variable, default model, and API key; it writes the provider definition to ~/.tau/catalog.toml and runtime preferences to ~/.tau/providers.json.

Check what’s configured and how each provider will authenticate:

tau providers

Managing saved credentials

Use these slash commands inside Tau:

/login [provider]   # add or refresh a saved credential
/logout [provider]  # remove a saved credential

Saved credentials take precedence over environment variables. /logout only edits saved credentials — it never touches your environment or providers.json.

Choosing and switching models

• /model — open the picker (lists models across configured providers; choosing one can switch the active provider too).
• tau -m <model> or tau --provider <name> -m <model> — choose at launch.
• Ctrl+P — cycle your scoped (favorite) models without opening the picker. Build the list with /scoped-models, or press Space on a model in the /model picker.

Tau validates the selected model against the active provider’s configured model list before creating or refreshing a runtime provider. This prevents accidental provider/model mismatches, such as trying to send an API-only OpenAI model to the separate openai-codex subscription provider.

When a switch crosses provider APIs, Tau compiles existing tool history for the target provider. Provider-specific tool-call IDs are deterministically translated to a portable format, with the same translated ID used for each call and result. When compiling history for Anthropic, Tau also omits opaque reasoning signatures created by other APIs. This lets a session continue after tools have run without exposing users to provider validation errors or rewriting the saved JSONL history.

Claude Opus 5

Tau supports Anthropic’s claude-opus-5 through the direct anthropic provider. The model has a 1M-token context window, accepts text and images, generates up to 128k tokens, and costs $5 / $25 per million input/output tokens. Anthropic enables adaptive thinking by default. Tau maps its low through high modes directly, maps xhigh to Anthropic’s maximum effort, and sends an explicit disabled-thinking request for off.

Use /login anthropic-api or /login anthropic-subscription, then select Claude Opus 5 in /model. See Anthropic’s Claude Opus 5 guide for current behavior and availability.

Adding a custom / local provider

Any OpenAI-compatible endpoint works — including local servers like llama.cpp or Ollama. The easiest interactive path is:

/login custom

Tau prompts for the provider details, saves the API key, writes the provider metadata to ~/.tau/catalog.toml, and makes the provider available immediately.

llama.cpp quickstart

Tau works with llama.cpp through its OpenAI-compatible server. Start a local server with a GGUF model from Hugging Face:

llama-server -hf ggml-org/Qwen3.6-35B-A3B-GGUF:Q8_0

Some installs expose the same server as llama serve:

llama serve -hf ggml-org/Qwen3.6-35B-A3B-GGUF:Q8_0

Then register it with Tau:

export LLAMA_API_KEY=local # any non-empty value unless you started llama.cpp with --api-key

tau --provider llama-cpp \
  --base-url http://localhost:8080/v1 \
  --api-key-env LLAMA_API_KEY \
  --model local \
  setup

Run Tau against the local model:

tau --provider llama-cpp
tau --provider llama-cpp "summarize this project"    # TUI with an initial prompt
tau --provider llama-cpp -p "summarize this project" # one-shot print mode

llama-server listens on port 8080 by default and only enforces the bearer token if you launch it with --api-key.

For scripted or one-off setup with another OpenAI-compatible server, use the same tau setup flow. For example, Ollama’s OpenAI-compatible endpoint usually runs at http://localhost:11434/v1:

tau --provider local \
  --base-url http://localhost:11434/v1 \
  --api-key-env LOCAL_API_KEY \
  --model qwen \
  setup

This writes the provider definition to ~/.tau/catalog.toml, writes runtime preferences to ~/.tau/providers.json, and (by default) makes it the default provider.

For reusable provider definitions, add a user-level catalog overlay at ~/.tau/catalog.toml:

schema_version = 1

[[providers]]
name = "local-gateway"
display_name = "Local Gateway"
kind = "openai-compatible"
base_url = "http://localhost:11434/v1"
api_key_env = "LOCAL_GATEWAY_API_KEY"
credential_name = "local-gateway"
models = ["qwen-coder"]
default_model = "qwen-coder"
docs_url = "https://example.test/local-gateway"

[providers.context_windows]
qwen-coder = 64000

Tau loads its bundled src/tau_coding/data/catalog.toml first, then overlays ~/.tau/catalog.toml. A user entry with the same name can extend or override a built-in provider: scalar fields replace built-in values, models are merged with your models first, and context_windows are merged.

There is intentionally no project-level .tau/catalog.toml. Only the user-level ~/.tau/catalog.toml is loaded, so cloning a repository cannot silently redirect a provider’s base_url or credentials to an unexpected service.

Run the custom provider with:

tau --provider local-gateway
tau --provider local-gateway "summarize this project"    # TUI with an initial prompt
tau --provider local-gateway -p "summarize this project" # one-shot print mode

Catalog TOML is for provider and model metadata. It does not accept runtime request options such as custom HTTP headers, timeouts, or retry settings. Put those in ~/.tau/providers.json instead. Saved providers.json entries support headers, timeout_seconds, max_retries, and max_retry_delay_seconds. For the full JSON shape, the catalog TOML shape, and thinking_levels for custom models, see Configuration.

{
  "default_provider": "huggingface",
  "provider_preferences": {
    "huggingface": {
      "default_model": "openai/gpt-oss-120b",
      "headers": { "X-HF-Bill-To": "my-org" },
      "thinking_defaults": { "openai/gpt-oss-120b": "low" },
      "timeout_seconds": 60,
      "max_retries": 2,
      "max_retry_delay_seconds": 1
    }
  },
  "scoped_models": []
}

How credentials are resolved

For a given provider, Tau uses, in order: a stored credential in ~/.tau/credentials.json, then the environment variable named by the provider’s api_key_env. OAuth credentials are refreshed immediately before a request and the replacement is saved atomically. Use /login for built-in providers or /login custom for OpenAI-compatible custom providers.