Providers

A provider is the backend that runs a session’s agent — usually by driving a coding CLI installed on the host, sometimes over HTTP. PeckBoard ships eight first-party providers as built-in plugins, and the WASM provider API for anything else. Every model id carries its provider as a prefix, provider:model — claude:claude-opus-5, ollama:qwen2.5-coder — and a bare id defaults to claude:.

Provider Drives Sign-in
Claude The Claude Code CLI (claude), streaming JSON Host claude login, plus OAuth accounts in Settings
Codex The OpenAI Codex CLI (codex exec --json) ChatGPT device-code flow in Settings → Codex Accounts
Cursor The cursor-agent CLI in print mode Browser sign-in in Settings → Providers
Grok The Grok CLI (grok), streaming JSON Browser device flow in Settings → Grok Accounts
Kimi Moonshot AI’s Kimi Code CLI (kimi) Device flow or API key in Settings → Kimi Accounts
Ollama An Ollama server’s /api/chat HTTP API — no CLI None; configure server URLs in Settings
OpenAI-Compatible Any OpenAI /v1/chat/completions server (vLLM, llama.cpp, LM Studio, …) Optional API key in Settings
Mock Nothing — scripted scenarios for demos and tests None

None of them is active on a fresh install. The setup wizard’s Connect your AI step, also at the top of Settings → Providers, takes each CLI provider from nothing to usable: Install runs the vendor’s official installer on the server with no root and no working agent needed, Sign in connects your subscription, and the provider turns on by itself. On Windows, where the installers aren’t shell scripts, it shows the command to run instead. Providers can also be activated from Settings → Plugin Registry, the same flow as any plugin.

Accounts and Sign-in

Settings → Providers & Accounts holds each provider’s accounts. Claude, Codex, Grok, and Kimi support multiple accounts; each account’s models appear separately in the picker as [Account Name] Model, with an optional per-account budget and, where the provider reports it, subscription plan usage. The implicit “Default” account is whatever the CLI is signed into on the host. A session’s conversation is pinned to the provider and account it started on — resuming never silently switches either. An hourly keep-alive pings each signed-in login so tokens do not go stale (--keep-alive-hours, 0 disables).

Settings → Providers & Accounts with provider accounts, budgets, and plan usage

The Providers in Detail

Claude drives the Claude Code CLI in duplex stream-json mode and is the most fully-featured provider: effort levels, thinking, images, resume, and mid-turn message injection (the others queue mid-turn messages for the next turn). It seeds the current Claude catalog (Fable 5, Opus 5 and 4.x, Sonnet 5 and 4.6, Haiku 4.5) with pricing, then live-discovers what your CLI actually offers; Bedrock model ARNs from the standard ANTHROPIC_DEFAULT_*_MODEL environment variables are picked up too. Interrupts are soft — an in-band stop request first, a hard kill only after a grace window.

Codex runs one codex exec --json per turn. Sign-in is the CLI’s own ChatGPT device-code flow, run from Settings → Codex Accounts: create the account, click sign in, enter the one-time code at the URL shown. Supports effort levels, thinking, images, and resume.

Cursor drives cursor-agent in print mode with streamed partial output. Its catalog is whatever cursor-agent models reports — Cursor’s auto and Composer models plus hosted Claude, GPT, Gemini, and Grok variants. Sign in from Settings → Providers, or with cursor-agent login on the host. It is the host’s single login: there is no in-app account management. Effort levels are not offered (the CLI has no flag for them). Image attachments go through the CLI’s --image flag, which is hidden from --help and marked internal, so a CLI update could remove it; if it does, the turn fails with a message saying so. Other attachments are dropped with a notice. Every turn loads Peckboard’s tools, your Settings → MCP Servers entries, and the servers in the project’s .cursor/mcp.json (the one at the git root, which is the only one the CLI reads) plus ~/.cursor/mcp.json. All of them are approved automatically, so a repo’s .cursor/mcp.json can start its stdio servers on the first turn; review it in repos you don’t trust. A server that can’t be approved is named in the transcript. The CLI has no way to turn off its built-in question tool, so every turn tells the model to use Peckboard’s ask_user instead. That is an instruction, not a block: a model could still call the built-in tool. The rule is part of Cursor’s default base prompt, which is sent with every turn (resumed chats included, like the session’s own system prompt); replacing that prompt in Settings removes it.

Grok drives the Grok CLI with streamed JSON and a real system-prompt flag. The default model is grok-4.5 — grok-4.6 is offered but needs an OAuth login, not an API key. Sign in from Settings → Grok Accounts (a browser device flow the CLI runs).

Kimi drives the Kimi Code CLI in prompt mode. Models come from the CLI’s own config (kimi provider list); accounts support both a device flow and an API-key account, and the plugin’s settings can inject KIMI_API_KEY and a custom base_url directly.

Ollama talks HTTP to one or more Ollama servers — base_url plus optional named extra servers whose models appear as model@alias. It keeps multi-turn history itself (Ollama is stateless), probes each model’s capabilities before a turn so tool calls and images are only sent where supported, runs MCP tools through an internal tool loop, and prices everything at zero. A model-pull widget in Settings downloads new models to the server.

OpenAI-Compatible (openai-compat) talks the OpenAI Chat Completions API to vLLM, llama.cpp server, LM Studio, LocalAI, TGI, SGLang, or any other compatible server. Configure a default server URL (with or without the trailing /v1), an optional API key (sent as Authorization: Bearer), and optional named extra servers whose models appear as model@alias. Models are discovered from each server’s /v1/models, so ids like openai-compat:Qwen/Qwen3-32B work as-is. Like Ollama, it keeps multi-turn history itself and runs MCP tools as OpenAI function tools; if a server rejects tools for a model, the turn retries once without them. Mock is the scripted provider the test suite and demos use — each model id is a scenario (mock:happy-path, mock:echo, mock:crash, …) that replays a fixed event sequence with no network and no cost.

CLI locations, model discovery, and per-provider settings

Each CLI provider has a cli_path setting (default: the bare command name, with common install directories like ~/.local/bin and the Grok and Kimi installers’ ~/.grok/bin and ~/.kimi-code/bin probed as fallbacks), a discover_models toggle (default on — the live CLI catalog replaces the built-in seed), and an additional_models list for ids the discovery misses. The App Manager plugin can also install Claude Code, cursor-agent, and Ollama.

A provider turn runs under its own budget — default 300 seconds, raised with --provider-send-timeout-secs — rather than the short general plugin-call timeout.

Adding a Provider PeckBoard Does Not Ship

Any server that speaks the OpenAI Chat Completions API is covered by the built-in OpenAI-Compatible provider: point it at the /v1/chat/completions endpoint (vLLM, llama.cpp, LM Studio, LocalAI, TGI, SGLang, OpenRouter) and its models join the picker. For anything else, a WASM plugin can register a full provider through the provider.register and provider.send hooks — it owns entire agent turns, streams the same events first-party providers do, and can drive either HTTP or a host-managed CLI process. The internal architecture notes in the repository (docs/architecture/providers.md) document the hook contract.


Assembled with many small pecks.

This site uses Just the Docs, a documentation theme for Jekyll.