/docs
Guide
Providers

Choose the model Spark will use.

Start with one provider for Agent and Mission, or split them during setup if you already know what you want. Agent means chat, runtime reasoning, memory, and recall. Mission means Spark's longer build work in Mission Control.

Agent Markdown Commands Fix

Start with the easiest choice.

If you already pay for or use one of these tools, use that first. Spark can always be reconfigured later.

Already use OpenAI?

Choose OpenAI Codex

Use the Codex CLI sign-in path so Spark can use your existing Codex or ChatGPT setup without asking most users for an OpenAI API key.

spark setup --llm-provider codex
Already use Claude Code?

Choose Anthropic Claude

Spark can use the Claude CLI route when Claude Code is installed and signed in. This is the friendliest Claude path for many subscription users.

spark setup --llm-provider anthropic
Have an API key or local model?

Choose your provider

Use Z.AI GLM, Kimi, MiniMax, OpenRouter, Hugging Face, Ollama, LM Studio, or another OpenAI-compatible endpoint you already trust.

spark recommend llms

What setup will ask.

01

Pick a default provider

This is the model family Spark starts with for Agent and Mission.

02

Keep it together or split now

Most people use one provider for both. If you already know your build model should be different, choose a separate Mission provider during setup.

03

Prove it works

Run the provider test and onboarding verify before you expect Telegram or builds to work.

spark recommend llms
spark setup
spark providers status
spark providers test --role chat
spark verify --onboarding

Provider types, not mystery names.

Most choices fit into three simple buckets. Pick the bucket that matches what you already have.

Signed-in app

Subscription CLI

Use this when you already have Codex/ChatGPT or Claude Code signed in on your computer. Spark talks through the local CLI route.

  • OpenAI Codex: codex
  • Anthropic Claude: anthropic
Provider account

API key

Use this when you have a provider key. Spark stores the key locally and only routes to the provider you selected.

  • zai, kimi, minimax
  • openrouter, huggingface, openai
Runs on your machine

Local model

Use this when LM Studio or Ollama is running locally. The local app must stay open while Spark uses it.

  • LM Studio: lmstudio
  • Ollama: ollama

Agent and Mission, in plain English.

Agent

Chat, runtime reasoning, memory, and recall.

This is what answers Telegram messages, remembers preferences, recalls context, and decides how Spark should respond.

Mission

Builds and longer tracked work in Mission Control.

This is what runs bigger Spark work: building apps, researching, debugging, coding, and tracking progress on Kanban or Canvas.

Default recommendation

Choose one provider and use it for both Agent and Mission unless you already know you want a split. You can change this later by rerunning spark setup.

Use one provider, or split Agent and Mission.

Recommended first

One provider for everything

This is the least confusing path. Agent chat, memory, runtime reasoning, and Mission Control all use the same selected provider. For Anthropic, Spark uses --anthropic-model (default sonnet) for both roles unless you explicitly choose a split.

spark setup --llm-provider codex
spark providers status
spark providers test --role chat
More control

Agent on one provider, builds on another

Use this during setup or later when you like one model for conversation and memory, but want a different model for longer build missions.

spark setup --agent-llm-provider anthropic --mission-llm-provider codex
spark providers status
spark providers test --role chat
spark providers test --role mission
Expert mode

Split every role

Only do this if you know why each role needs a different model. It is useful for experiments, not first setup.

spark setup --chat-llm-provider codex --builder-llm-provider zai --memory-llm-provider lmstudio --mission-llm-provider anthropic

Supported providers.

These provider IDs are the names Spark setup understands today.

codex

OpenAI Codex

Best if you already use Codex or ChatGPT. Uses the Codex CLI sign-in route.

spark setup --llm-provider codex
anthropic

Anthropic Claude

Best if you already use Claude Code or have an Anthropic API key. Uses --anthropic-model (default sonnet) for both roles; pass opus explicitly when a role should use Opus.

spark setup --llm-provider anthropic
zai

Z.AI GLM

Good API-key path for GLM models and a strong one-provider setup.

spark setup --llm-provider zai --zai-api-key <key>
kimi

Kimi / Moonshot

OpenAI-compatible Moonshot route for chat, memory, and missions.

spark setup --llm-provider kimi --kimi-api-key <key>
minimax

MiniMax

Good if you already have a MiniMax key and want an OpenAI-compatible route.

spark setup --llm-provider minimax --minimax-api-key <key>
openrouter

OpenRouter

Useful when you want one gateway for many commercial and open models.

spark setup --llm-provider openrouter --openrouter-api-key <key>
huggingface

Hugging Face Router

Hosted open-model route using an HF token and OpenAI-compatible endpoint.

spark setup --llm-provider huggingface --huggingface-api-key <key>
lmstudio

LM Studio

Local desktop model server. Start LM Studio's server before testing Spark.

spark setup --llm-provider lmstudio --lmstudio-model <model>
ollama

Ollama

Terminal-friendly local model route. Best when Ollama is already running.

spark setup --llm-provider ollama --ollama-model <model>
openai

OpenAI API

For OpenAI API billing/accounts. Most ChatGPT users should start with Codex.

spark setup --llm-provider openai --openai-api-key <key>

Provider commands you will actually use.

See the menu

Use this before setup if you are unsure which provider fits your situation.

spark recommend llms

List what Spark supports

Shows provider IDs, auth type, and setup command for each supported provider.

spark providers list

Check what is currently selected

Use this after setup or after changing roles. It should show the providers you chose.

spark providers status

Test the Agent provider

Sends a tiny probe through the chat role so you know Spark can really talk through that provider.

spark providers test --role chat

Test the Mission provider

Use this when Mission Control or /run feels wrong.

spark providers test --role mission

Change your choice later

Rerun setup safely. You do not need to reinstall Spark just to switch models.

spark setup

Hosted Railway setup.

For always-on Railway or Docker installs, keep Spark API-first and boring. Railway should run Telegram, Spawner, Mission Control, previews, private relays, and persistent workspaces. The models should come from API providers or from a model server the container can reach.

Use the Railway/VPS operations page for the full service layout, environment checklist, smoke prompt, and hosted fix map.

Bot service

Uses long polling for Telegram and exposes the private mission relay.

TELEGRAM_RELAY_HOST=::

Spawner service

Runs Mission Control, state, workspaces, and provider execution.

SPAWNER_STATE_DIR=/data/spawner

Private bridge

Use one shared service key so the bot can call Spawner without public exposure.

SPARK_BRIDGE_API_KEY
Recommended hosted path

Use API providers

Z.AI, OpenAI, Anthropic, OpenRouter, Kimi, MiniMax, Hugging Face, and DeepSeek-style OpenAI-compatible routes are the cleanest Railway setup.

ZAI_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY
Safe Codex path

Codex CLI plus a service key

Codex CLI can run in the hosted Spawner image when it uses a dedicated OPENAI_API_KEY. Do not copy a personal desktop Codex OAuth session into Railway.

CODEX_HOME=/data/codex
Local models

Use reachable endpoints

Ollama, LM Studio, vLLM, TGI, or llama.cpp should run on your machine, a private server, or a GPU host. Railway connects to the endpoint; it should not download large models into the app container.

OLLAMA_URL / LMSTUDIO_BASE_URL 
SPAWNER_UI_URL=http://spawner-ui.railway.internal:<port>
SPAWNER_UI_PUBLIC_URL=https://<protected-spawner-public-domain>
TELEGRAM_RELAY_URL=http://spark-telegram-bot.railway.internal:8788/spawner-events
MISSION_CONTROL_WEBHOOK_URLS=http://spark-telegram-bot.railway.internal:8788/spawner-events
SPARK_BRIDGE_API_KEY=<same-long-secret-in-bot-and-spawner>
SPARK_UI_API_KEY=<different-long-secret-for-browser-login>

Public board links: SPAWNER_UI_URL is for private service-to-service calls. If it uses railway.internal, set SPAWNER_UI_PUBLIC_URL to the protected public Spawner domain so Telegram mission links open for humans.

Staging smoke: use TELEGRAM_SMOKE_MODE=1 on the bot and run a tiny Mission from Spawner. That verifies the private relay without calling Telegram. Production chat still needs a real BotFather token.

Deep smoke: inside Spawner, set SPARK_HEALTH_DEEP=1 and run npm run health:spark. Add SPARK_HEALTH_PROVIDER=zai, minimax, or another configured Mission provider when testing one route directly.

Provider runtime: API providers can run in hosted containers with keys. Codex CLI is safe for hosted use with a dedicated OpenAI API key. Claude Code OAuth and personal Codex OAuth stay local; use Anthropic API keys and OpenAI API keys for hosted services.

What good looks like.

Provider status: Agent and Mission show the provider or split you chose.

No surprise fallback: Spark should not call Ollama, LM Studio, or another local endpoint unless you selected it.

Telegram chat: A normal message gets a real answer from the selected Agent provider.

Build test: /run say exactly OK starts a mission and returns a result through Mission Control.

spark providers status
spark providers test --role chat
spark verify --onboarding