94 lines
4.5 KiB
Markdown
94 lines
4.5 KiB
Markdown
---
|
|
title: AI providers
|
|
summary: 'Configure model providers and credentials for the Peekaboo agent runtime.'
|
|
description: Configure OpenAI, Anthropic Claude, xAI Grok, Google Gemini, MiniMax, 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 | Models we test | Credential |
|
|
| --- | --- | --- |
|
|
| **OpenAI** | gpt-5, gpt-5-mini, gpt-4.1 | `OPENAI_API_KEY` |
|
|
| **Anthropic** | claude-fable-5, claude-opus-4-8, claude-sonnet-4-6, 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-M2.7, MiniMax-M2.7-highspeed | `MINIMAX_API_KEY` |
|
|
| **MiniMax China** | MiniMax-M2.7, MiniMax-M2.7-highspeed | `MINIMAX_CN_API_KEY` or `MINIMAX_API_KEY` |
|
|
| **OpenRouter** | any tool-calling OpenRouter model ID | `OPENROUTER_API_KEY` |
|
|
| **Ollama** | any local model with tool-calling | runs at `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](https://github.com/steipete/Tachikoma) 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:
|
|
|
|
```bash
|
|
peekaboo config set-credential OPENAI_API_KEY <key>
|
|
peekaboo config set-credential ANTHROPIC_API_KEY <key>
|
|
peekaboo config set-credential GEMINI_API_KEY <key>
|
|
peekaboo config set-credential MINIMAX_API_KEY <key>
|
|
peekaboo config set-credential MINIMAX_CN_API_KEY <key>
|
|
peekaboo config set-credential OPENROUTER_API_KEY <key>
|
|
```
|
|
|
|
Environment variables override the stored values, which is handy in CI:
|
|
|
|
```bash
|
|
OPENAI_API_KEY=sk-... peekaboo agent "open a browser"
|
|
```
|
|
|
|
See [configuration.md](configuration.md) for the full precedence table.
|
|
|
|
## Picking a model
|
|
|
|
```bash
|
|
peekaboo agent --model claude-fable-5 "summarize this window"
|
|
peekaboo agent --model claude-opus-4-8 "summarize this window"
|
|
peekaboo agent --model gemini-3-flash "summarize this window"
|
|
peekaboo agent --model minimax "summarize this window"
|
|
peekaboo agent --model minimax-cn/MiniMax-M2.7 "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 "describe this screenshot"
|
|
peekaboo agent --model lmstudio/openai/gpt-oss-120b "summarize this window"
|
|
```
|
|
|
|
Defaults come from `agent.defaultModel` in `~/.peekaboo/config.json`. Anthropic defaults stay on Opus 4.8 for zero-retention compatibility; select Fable explicitly when your Anthropic organization allows it. 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; Fable supports a 1M context window and up to 128K output. See
|
|
[configuration.md](configuration.md#agent-generation-settings).
|
|
|
|
## Tool calling
|
|
|
|
The agent expects tool-calling capable models. If your provider doesn't support it (some tiny local models), Peekaboo falls back to a structured-output prompt — slower and less reliable. Stick with mainstream tool-calling models for production runs.
|
|
|
|
## Local-only mode
|
|
|
|
Want everything on-device? Run an Ollama model with tool calling and point the CLI at it:
|
|
|
|
```bash
|
|
ollama run llama3.1:8b
|
|
peekaboo agent --model ollama/llama3.1:8b "open System Settings"
|
|
```
|
|
|
|
No network requests leave the machine. Captures, AX queries, and reasoning all stay local.
|
|
|
|
## 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 screenshots. Start a fresh session with `peekaboo agent --new`.
|
|
- **"no tool-call support"** — pick a different model. The error log lists the providers and models with confirmed tool-calling.
|