Skip to content

Configuring a runtime

A runtime is whatever LLM (or CLI agent) actually generates the replies in a chat. Hive doesn't talk to a single hard-coded provider — you configure as many runtimes as you want, and chats pick one per session.

Open Settings → Runtimes to add or edit.

Settings → Runtimes tab

Supported providers

Provider What it is Auth Tools?
ollama Local Ollama daemon none text-only today
openai OpenAI's API OPENAI_API_KEY env yes (Hive tools)
anthropic Anthropic's API ANTHROPIC_API_KEY env yes (Hive tools)
openrouter OpenRouter aggregator OPENROUTER_API_KEY env yes
claude-code Local claude CLI (uses your Claude Pro/Max sub) depends on Claude CLI yes (Claude Code's own tools)
aider Local aider CLI depends on aider's config yes (aider's own tools)
pi Local pi CLI depends on pi's config yes (pi's own tools)
subprocess Generic — any CLI you point Hive at depends depends
hive-daemon Remote hived instance bearer token passthrough
custom OpenAI-compatible HTTP endpoint varies varies

Provider presets

When you add a runtime in Settings → Models, the picker offers presets that pre-fill the endpoint and capability flags so you don't have to remember them:

  • OpenAI — api.openai.com.
  • OpenRouter — the OpenRouter aggregator.
  • Azure OpenAI — an Azure deployment endpoint (your https://<resource>.openai.azure.com URL + deployment name).
  • Ollama — your local Ollama daemon.
  • Custom — any other OpenAI-compatible HTTP endpoint; fill in the base URL yourself.

All five are OpenAI-wire-compatible, so the same multi-turn tool loop works across them. Pick the closest preset, then adjust the endpoint, model id, and API-key env var as needed.

Runtime config schema

Each runtime is a [[runtimes]] block in hive.config.toml. The Settings UI is a GUI over the same fields:

[[runtimes]]
id = "anthropic-claude"
name = "Anthropic Claude"
provider = "anthropic"
kind = "remote"
endpoint = "https://api.anthropic.com"
preferred_model = "claude-sonnet-4-5"
api_key_env = "ANTHROPIC_API_KEY"
supports_tools = true
performance_score = 9.5
cost_per_1m_input_tokens_usd = 3.0

For subprocess agents (aider, pi, custom), endpoint is the binary path:

[[runtimes]]
id = "aider"
name = "Aider"
provider = "aider"
kind = "local"
endpoint = "/usr/local/bin/aider"
preferred_model = "gpt-4o"
supports_tools = true

See the Configuration reference for every field.

API providers — environment variables

For API providers, Hive reads the credential from an environment variable you control. Set it in your shell config before launching:

# ~/.zshrc
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export OPENROUTER_API_KEY="sk-or-..."

Hive never writes API keys to disk — only the env var name lives in the config. Quitting and relaunching the app picks up new env vars.

Subprocess agents — installing the binary

Aider, pi, and other CLI agents are user-supplied:

pip install aider-chat
which aider
# → /usr/local/bin/aider

Then point Hive at /usr/local/bin/aider.

pip install promptflow
which pi
# → /usr/local/bin/pi

Any binary that reads a prompt and writes a response works. Use provider = "subprocess" with endpoint pointing at your binary. By default Hive pipes the prompt via stdin; per-provider invocation (e.g. pi's positional-arg form) lives in crates/hive-runtime/src/provider/dispatch.rs.

Picking which runtime a chat uses

When you create a new chat, Hive picks the workspace's default_runtime. Switch per chat from the Workspace Bar at the top of the window — click the runtime pool segment to swap.

To make an agent always use a specific runtime, configure a Workspace Agent: give the agent an @handle and pin it to one runtime.