cassady/docs/providers.md

Providers and models

Cassady currently supports OpenAI-compatible providers. A provider supplies the base URL and API key; a model entry supplies metadata for one model id used with that provider.

Built-in setup catalog

The setup wizard offers these provider templates:

Provider	Provider id	Base URL	Suggested API key env var
OpenAI	openai	https://api.openai.com/v1	OPENAI_API_KEY
xAI	xai	https://api.x.ai/v1	XAI_API_KEY
Fireworks	fireworks	https://api.fireworks.ai/inference/v1	FIREWORKS_API_KEY
Groq	groq	https://api.groq.com/openai/v1	GROQ_API_KEY
OpenRouter	openrouter	https://openrouter.ai/api/v1	OPENROUTER_API_KEY
OpenCode Zen	opencode-zen	https://opencode.ai/zen/v1	OPENCODE_API_KEY
OpenCode Go	opencode-go	https://opencode.ai/zen/go/v1	OPENCODE_API_KEY
Cerebras	cerebras	https://api.cerebras.ai/v1	CEREBRAS_API_KEY
Novita	novita	https://api.novita.ai/v3/openai	NOVITA_API_KEY
Together	together	https://api.together.xyz/v1	TOGETHER_API_KEY

There is also a custom OpenAI-compatible option. Custom setup asks for provider name, provider id, base URL, API key environment variable, and first model id.

Login and logout

Use cass login to add or update provider configuration from the shell. Inside an idle chat, /login opens the same flow and reloads the active provider/model afterward.

Use cass logout or /logout to remove saved provider entries from Cassady config. Logout also removes model metadata entries associated with the removed providers and repairs active defaults when other providers remain. It does not delete environment variables, shell profile exports, API keys stored elsewhere, or external provider accounts.

Model discovery

When the selected API key environment variable is available, setup tries:

GET {base_url}/models

If the provider returns model ids, setup lets you choose one. If discovery fails, setup offers a retry and then falls back to manual model entry. Some OpenAI-compatible providers do not expose /models or require different permissions; manual entry is normal in that case.

Custom provider requirements

A custom provider should expose OpenAI-compatible chat completions behavior at the configured base URL. Cassady may use:

• streamed assistant text;
• tool call requests and tool results;
• optional reasoning fields or reasoning request controls;
• optional /models discovery during setup.

Provider protocols that are not OpenAI-compatible are not currently supported.

Provider vs model metadata

providers.json answers: how does Cassady connect?

• provider id;
• base URL;
• API key reference;
• optional default model;
• optional list of associated model ids.

models.json answers: what does this model support?

• model id sent to the provider;
• owning provider id;
• display name;
• context length and max output tokens;
• tool and streaming support;
• reasoning support and request format.

config.json selects active defaults, such as default_provider, default_model, and default_access_mode.

Reasoning metadata

Reasoning metadata controls how the runtime reasoning effort behaves:

• supported: false: reasoning effort stays off.
• required: true: Tab cycles through low, medium, and high without off.
• default_effort: starting effort for the model.
• request_format: "reasoning_effort": sends a top-level reasoning_effort string.
• request_format: "reasoning_object": sends a reasoning object with an effort.

Reasoning display is separate. show_reasoning controls whether provider-streamed reasoning is visible in the transcript; press Ctrl-Shift-R or Ctrl-R to toggle it at runtime.

Switching models

Use one of these approaches:

cass --model MODEL

or inside a chat:

/model MODEL

The in-chat model autocomplete lists entries from ~/.cass/models.json. Switching the model also updates the default model and reasoning effort in config.json for future sessions.

Health checks

Run:

cass check

This confirms that the active provider and model resolve and that the active API key environment variable is set. Missing inactive-provider keys are warnings; missing active-provider keys are errors.