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

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

#Credentials

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

peekaboo config set-credential openai     # interactive
peekaboo config set-credential anthropic

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 claude-opus-4-7 "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"

Defaults come from agent.defaultModel in ~/.peekaboo/config.json. Set a per-project default with PEEKABOO_AGENT_MODEL.

#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:

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.