AI Providers

AI Providers

ClusterSpace talks to any OpenAI-compatible chat-completions endpoint. That covers Claude (via Anthropic's compat shim), OpenAI directly, Ollama, LM Studio, vLLM, llama.cpp, and most other inference servers.

---

Open settings

Ctrl+Shift+A to open the AI chat panel, then click the gear icon. Or Ctrl+P → "AI settings".

You'll land in the providers list. Click + Add Provider to create one, or click an existing provider to edit / delete / activate.

---

Provider fields

Field	Notes
Name	Display label (e.g., "Claude Sonnet 4.5")
Endpoint	Base URL, no trailing /chat/completions (we append it)
Model	Model identifier the provider expects
Vision model	Optional. For dual-purpose models (Claude, GPT-4o) leave blank — main model handles vision too.
API key	Encrypted via OS keychain (safeStorage)
Temperature	0.0–1.0 slider, default 0.7
Max tokens	Cap on response length, default 4096
System prompt	Per-provider override. Defaults to the built-in 700-line prompt — see AI-Overview

Backend: src/main/ai-store.ts. The active provider is aiSettings.activeProviderId.

---

Provider-specific setup

Claude (Anthropic)

Endpoint	https://api.anthropic.com/v1
Model	claude-sonnet-4-5 (or claude-opus-4 / claude-haiku-4 for cost/speed tradeoffs)
Vision model	leave blank — Claude is dual-purpose
API key	Get one at https://console.anthropic.com

Claude's chat-completions endpoint is a compatibility shim for OpenAI's format. Works without changes.

OpenAI

Endpoint	https://api.openai.com/v1
Model	gpt-4o, gpt-4o-mini, gpt-4-turbo, etc.
Vision model	leave blank for gpt-4o* (multimodal)
API key	https://platform.openai.com/api-keys

Ollama (local, free)

1. Install Ollama from https://ollama.com
2. Pull a model: ollama pull llama3.1:8b (or any tool-calling-capable model — mistral-nemo, qwen2.5, etc.)
3. In ClusterSpace, use the Discover button with host localhost or 127.0.0.1 — Ollama runs on port 11434 by default and gets auto-detected.

Or manually:

Endpoint	http://localhost:11434/v1
Model	the model you pulled (e.g., llama3.1:8b)
API key	leave blank

⚠ Not every Ollama model supports tool calling. If you ask the AI to do something and nothing happens, check that your model is in Ollama's tools-capable list.

LM Studio

1. Open LM Studio, load a model, start the local server (default port 1234)
2. In ClusterSpace, Discover with localhost — port 1234 is checked

Or manually:

Endpoint	http://localhost:1234/v1
Model	as shown in LM Studio's server panel
API key	leave blank

vLLM / llama.cpp / TGI / OpenRouter / Groq / Together / …

Anything that speaks OpenAI's chat-completions API will work. Set the endpoint to the base URL (no /chat/completions suffix), the model to whatever the server expects, and the API key if it requires auth.

---

Discover button

ClusterSpace can probe common ports on a given host to find local providers automatically. From the providers list → Discover → enter an IP / hostname → it tries:

Port	Likely server
11434	Ollama
1234	LM Studio
8000	vLLM (default)
5000	text-generation-webui

Hits show up with detected model lists; pick one to auto-fill the new-provider form.

---

API key storage

API keys are stored via Electron safeStorage:

• macOS: Keychain
• Windows: DPAPI (per-user)
• Linux: Secret Service (gnome-keyring, kwallet, etc.)

If the OS keychain is unavailable (headless Linux without dbus-daemon), there's a base64 fallback with a console.warn. Don't rely on it for sensitive deployments.

Storage file: <userData>/clusterspace-data/clusterspace-ai-providers.json (only the encrypted blob is stored; the key never appears in plaintext on disk).

---

Test connection

After saving a provider, click Test Connection to send a one-token completion and verify the endpoint + key + model are all working. If the test fails:

Error	Likely cause
HTTP 401	Bad API key
HTTP 404	Wrong endpoint or model
HTTP 400: "model X does not exist"	Typo in model field — check provider's model list
HTTP 400: "No user query found in messages"	Provider rejects requests without a user role — this is fixed in v1.0.1+; if you see it, update
Connection refused	Local provider isn't running
TLS errors	Self-signed cert on local server — currently no UI to disable verification; use NODE_TLS_REJECT_UNAUTHORIZED=0 env var (don't do this in production)

More fixes in Troubleshooting.

---

Cost tips

Trick	Effect
Use a smaller model for the critic (criticProviderId on goals)	Critic runs every N steps and asks a yes/no/stuck/achieved question — perfect for a small fast model. Set up Claude Haiku or GPT-4o-mini as a second provider just for critics.
Set max tokens low for chat panel use	Most chat answers don't need 4096 tokens — 1024 is plenty
Per-pane convo isolation = shorter contexts	Driving pane A doesn't accumulate context about pane B
Goal wallClockMs cap	Don't let a runaway goal eat budget
Set temperature low for deterministic tasks	Especially for the critic and verification calls

---

Switching providers mid-session

Click any provider in the list to activate it. The chat panel uses the active provider for new messages. Existing conversation history persists; the next stream just routes to the new provider.

There is no set_persona tool — personas are tied to providers (one persona per provider's system prompt). If you want to switch mid-conversation, set up multiple providers, each with a different persona's system prompt, and switch between them.

---

See also

• AI-Overview — what the AI can do
• AI-Chat-Panel — the UI surface
• Personas — system-prompt templates
• Critic-and-Replan — second-provider use case
• Troubleshooting — provider errors