Skip to content

providers.md

Latest commit

 

History

History
119 lines (94 loc) · 6.48 KB

providers.md

File metadata and controls

119 lines (94 loc) · 6.48 KB
Raw
title AI providers
summary Configure model providers and credentials for the Peekaboo agent runtime.
description Configure OpenAI, Anthropic Claude, xAI Grok, Google Gemini, MiniMax, Kimi, OpenRouter, and local providers for the Peekaboo agent.
read_when
configuring model credentials or provider selection
debugging agent model, tool-calling, or local Ollama setup

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.

Provider Example model IDs Credential
OpenAI gpt-5.6, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.4-nano, gpt-5, gpt-5-pro, gpt-5-mini, gpt-5-nano OPENAI_API_KEY
Anthropic claude-opus-5, claude-fable-5, claude-sonnet-5, claude-opus-4-8, claude-opus-4-7, claude-opus-4-5, claude-sonnet-4-6, claude-sonnet-4-5, claude-haiku-4-5 ANTHROPIC_API_KEY
xAI grok-4 XAI_API_KEY
Google gemini-3.1-pro-preview, gemini-3-flash GEMINI_API_KEY
MiniMax MiniMax-M3, MiniMax-M2.7, MiniMax-M2.7-highspeed MINIMAX_API_KEY
MiniMax China MiniMax-M3, MiniMax-M2.7, MiniMax-M2.7-highspeed MINIMAX_CN_API_KEY or MINIMAX_API_KEY
Kimi kimi-k2.6, kimi-k2.7-code, kimi-k2.7-code-highspeed MOONSHOT_API_KEY or KIMI_API_KEY
OpenRouter any tool-calling OpenRouter model ID OPENROUTER_API_KEY
Ollama ollama/<tool-capable-model> No key; native server defaults to http://localhost:11434
LM Studio any local OpenAI-compatible model with tool-calling runs at http://localhost:1234/v1

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

Credentials

Credentials live in the owner-only ~/.peekaboo/credentials file. Set them once with the CLI's no-echo prompt:

peekaboo config credential set OPENAI_API_KEY
peekaboo config credential set ANTHROPIC_API_KEY
peekaboo config credential set GEMINI_API_KEY
peekaboo config credential set MINIMAX_API_KEY
peekaboo config credential set MINIMAX_CN_API_KEY
peekaboo config credential set MOONSHOT_API_KEY
peekaboo config credential set OPENROUTER_API_KEY

For noninteractive use, pipe one line or point to an owner-only regular file (mode 0400 or 0600):

printenv OPENAI_API_KEY | \
  peekaboo config credential set OPENAI_API_KEY --credential-stdin --no-input
peekaboo config credential set ANTHROPIC_API_KEY \
  --credential-file /secure/path/anthropic.key --no-input

Environment variables still override stored values for Agent runs. Avoid placing values in argv: the legacy positional credential is deprecated and visible to process-listing tools.

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.