AI providers

Peekaboo's agent runtime is provider-agnostic — it talks to any chat-completions-style backend through Tachikoma. You configure provider credentials once and pick a model per-run.

#Supported providers

This table is the central reference for user-facing provider docs. Link here from architecture, install, and README pages instead of duplicating provider lists in multiple places.

Other Tachikoma-supported providers also work — see the Tachikoma docs for the full list.

#Credentials

Credentials live in ~/.peekaboo/credentials, encrypted at rest with the macOS Keychain when available. Set them once via the CLI:

peekaboo config credential set OPENAI_API_KEY <key>
peekaboo config credential set ANTHROPIC_API_KEY <key>
peekaboo config credential set GEMINI_API_KEY <key>
peekaboo config credential set MINIMAX_API_KEY <key>
peekaboo config credential set MINIMAX_CN_API_KEY <key>
peekaboo config credential set MOONSHOT_API_KEY <key>
peekaboo config credential set OPENROUTER_API_KEY <key>

Environment variables override the stored values, which is handy in CI:

OPENAI_API_KEY=sk-... peekaboo agent "open a browser"

See configuration.md for the full precedence table.

#Picking a model

peekaboo agent --model gpt-5.6 "summarize this window"
peekaboo agent --model gpt-5.6-terra "summarize this window"
peekaboo agent --model claude-fable-5 "summarize this window"
peekaboo agent --model claude-sonnet-5 "summarize this window"
peekaboo agent --model claude-opus-5 "summarize this window"
peekaboo agent --model gemini-3-flash "summarize this window"
peekaboo agent --model minimax/MiniMax-M3 "summarize this window"
peekaboo agent --model minimax-cn/MiniMax-M3 "summarize this window"
peekaboo agent --model kimi/kimi-k2.7-code "summarize this window"
peekaboo agent --model openrouter/xiaomi/mimo-v2.5-pro "summarize this window"
peekaboo agent --model gpt-5-mini "click Continue and wait for the dialog"
peekaboo agent --model ollama/llama3.1:8b "open System Settings"
peekaboo agent --model lmstudio/openai/gpt-oss-120b "summarize this window"

Defaults come from agent.defaultModel and aiProviders.providers in ~/.peekaboo/config.json. New generated configurations select GPT-5.6 and Opus 5. If Anthropic credentials are discovered without any saved provider selection, Peekaboo keeps the compatibility fallback on Opus 4.8 for zero-retention organizations. Explicit CLI, configuration, and persisted-session model selections are never upgraded to a different model. The generic gpt, openai, and openai/gpt shortcuts select GPT-5.6 Sol; a concrete model such as gpt-5-mini stays GPT-5 Mini. Set a per-project default with PEEKABOO_AGENT_MODEL.

The app and CLI share agent.temperature and agent.maxTokens. Peekaboo clamps those requests to provider capabilities; Peekaboo currently catalogs Opus 5, Fable 5, and Sonnet 5 with 1M context windows and up to 128K output. See configuration.md.

#Tool calling

The agent requires a tool-calling capable model. Peekaboo rejects a configured model marked supportsTools: false; only opt that model into tools when its endpoint actually implements tool calling. Vision is a separate capability, so use peekaboo see --analyze only with a model that also supports vision. Ollama capabilities vary by model and tag; see the Ollama provider guide before assuming a locally installed model supports tools.

#On-device Ollama mode

To keep model inference on-device, run an Ollama model with tool calling and select it explicitly:

ollama pull llama3.1:8b
peekaboo agent --model ollama/llama3.1:8b "open System Settings"

The loopback endpoint only guarantees that Peekaboo talks to the local Ollama daemon. Ollama cloud-model tags can be automatically offloaded by that daemon. For strict on-device inference, select a locally installed model and disable Ollama cloud features with OLLAMA_NO_CLOUD=1 or disable_ollama_cloud in ~/.ollama/server.json. Model downloads, network-capable tools, and a remote Ollama base URL remain separate network paths. See the Ollama privacy boundary and Ollama's cloud documentation.

#Troubleshooting

• "401 Unauthorized" — credential isn't set, or env var overrides the saved one. Run peekaboo config get-credential <provider>.
• "context length exceeded" — long sessions accumulate history. Start a fresh run without --resume.
• "no tool-call support" — pick a different model. The error log lists the providers and models with confirmed tool-calling.