Providers & runtimes

Ringmaster treats agents as interchangeable execution engines. A workflow names a runtime by a short ID; swap the ID and the same workflow runs somewhere else. Runtimes come in three shapes: CLI agents you've installed, local model servers running on your machine, and hosted APIs. Settings → Runtimes shows which are available right now, with a hint telling you what to do if one isn't.

Quick reference

Runtime ID	Name	Type	Setup
claude-code	Claude Code CLI	CLI agent	Install the claude CLI on your PATH
codex-cli	Codex CLI	CLI agent	Install codex; set OPENAI_API_KEY
copilot-cli	GitHub Copilot CLI	CLI agent	Install copilot; set GH_TOKEN (or GITHUB_TOKEN)
gemini-cli	Gemini CLI	CLI agent	Install gemini; set GEMINI_API_KEY (or GOOGLE_API_KEY)
kiro-cli	Kiro CLI	CLI agent	Install kiro-cli; sign in through Kiro
lm-studio	LM Studio	Local server	Run the LM Studio server; load a model
ollama	Ollama	Local server	ollama serve; ollama pull <model>
vllm	vLLM	Local server	vllm serve <model>
llama-cpp	llama.cpp	Local server	llama-server -m <model.gguf>
gemini-api	Gemini API	Hosted API	Add an API key in Settings → Gemini
openrouter	OpenRouter	Hosted API	Add an API key in Settings → OpenRouter
nvidia	NVIDIA NIM	Hosted API	Add an API key in Settings → NVIDIA
custom-openai:<id>	Custom OpenAI-compatible	Hosted API	Define a profile in Settings → OpenAI
custom-anthropic:<id>	Custom Anthropic-compatible	Hosted API	Define a profile in Settings → Anthropic

CLI agents

These shell out to an agent CLI you've installed. Ringmaster looks for the executable on your PATH (including the usual Homebrew locations), and the Runtimes panel shows it as available once it's found.

• Claude Code (claude-code): install the claude CLI. It uses its own auth; if you've signed in through Claude Code, Ringmaster uses that. Models: sonnet (default), opus, haiku — stable aliases the CLI resolves to its current versions.
• Codex (codex-cli): install codex and set OPENAI_API_KEY.
• Copilot (copilot-cli): install copilot and set GH_TOKEN (or GITHUB_TOKEN).
• Gemini (gemini-cli): install gemini and set GEMINI_API_KEY (or GOOGLE_API_KEY).
• Kiro (kiro-cli): install kiro-cli and sign in through Kiro's own login. It manages its own model.

For Codex, Copilot, and Gemini, the model picker offers (use CLI default) — the tool's own current default — plus a Custom field for any model ID the CLI accepts. Ringmaster deliberately doesn't ship a hardcoded model list for these: the CLIs update faster than any list would, and a stale pin is worse than none.

If a CLI isn't found, the Runtimes panel says so and tells you the command it expected. Install it, put it on your PATH, and reselect the runtime.

Local model servers

These run a model on your own machine and Ringmaster talks to them over HTTP. Nothing leaves the Mac, and there's no API key, which makes them a good fit for getting started and for private work.

• LM Studio (lm-studio): install the app, open the Developer tab, start the server, and load a model. Default endpoint http://localhost:1234. Ringmaster lists whatever models you've loaded.
• Ollama (ollama): run ollama serve, then ollama pull <model> (for example ollama pull llama3.1). Ringmaster discovers your pulled models automatically.
• vLLM (vllm): start it with vllm serve <model>. Default endpoint http://localhost:8000.
• llama.cpp (llama-cpp): start llama-server -m <path/to/model.gguf>. Default endpoint http://localhost:8080.

If a server isn't reachable or has no model loaded, the Runtimes panel says which and how to fix it. LM Studio and llama.cpp serve one request at a time, so Ringmaster runs their executions one after another even inside a parallel stage.

Hosted APIs

These call a provider's API over the network. You add the key once in Settings; it's stored in your macOS Keychain. After you add or rotate a key, Ringmaster asks you to relaunch so it picks up the new value.

• Gemini API (gemini-api): add a key in Settings → Gemini (create one at aistudio.google.com/apikey). Ringmaster lists the current Gemini models.
• OpenRouter (openrouter): add a key in Settings → OpenRouter (create one at openrouter.ai/keys). OpenRouter brokers hundreds of models from many providers; openrouter/auto lets it choose.
• NVIDIA NIM (nvidia): add a key in Settings → NVIDIA (create one at build.nvidia.com). NVIDIA's hosted catalog (Llama, Nemotron, DeepSeek, Qwen, Mistral) behind one OpenAI-compatible endpoint, with free credits to start. Ringmaster lists the current NIM models.

Custom endpoints

If you run your own gateway, a proxy, or any service that speaks the OpenAI or Anthropic wire format, add it under Settings → OpenAI (OpenAI-compatible) or Settings → Anthropic (Anthropic-compatible). A profile has a name, the base URL, an API key (kept in the Keychain), and, if the endpoint doesn't advertise its models, a manual list of model IDs. Each profile becomes a runtime: custom-openai:<your-id> or custom-anthropic:<your-id>, usable in any workflow. Public endpoints must use HTTPS; http:// is allowed only for local hosts.

Pinning models in a workflow

Any runtime that supports model selection can be pinned per stage, or per agent in a multi-agent stage, with model:. Ringmaster passes the model ID straight through, so anything the provider accepts works; you're not limited to the ones listed above. An ID the provider rejects fails at run time with the provider's own error.

    runtime: openrouter
    model: anthropic/claude-opus-4.5