Providers & harnesses

PrismaLens doesn’t run its own model. It rents a coding-agent binary — a harness — to do the read-only investigation work, then calls a model itself to write the final report. Both are BYO-key: no PrismaLens account, no subscription. You bring credentials for whichever provider you want, and PrismaLens reads them from your environment.

There are two independent choices to make:

1. Harness — which agent binary PrismaLens drives (deepagents, claude-code, or codex).
2. Model provider — whose model backs that harness, and which credential it needs.

This page is the compatibility matrix for both, plus how to point PrismaLens at the provider you want.

Harnesses

Harness	Binary on PATH	Install	Read-only guarantee	Status
deepagents (default)	deepagents-acp	npm install -g deepagents-acp @langchain/openai	Cooperative — the harness auto-approves its own permission prompts; no OS-level enforcement yet	Available
claude-code	claude	npm install -g @anthropic-ai/claude-code	Enforced — a tool deny-list blocks write/edit tools at the SDK level	Available
codex	codex	—	Enforced (planned)	Not yet available — selecting it exits with an error

Pick a harness with --harness on prismalens investigate, or set agent.default in prismalens.config.yaml. Whichever harness you pick, its binary must be on PATH — prismalens doctor checks this before every run.

Model providers

Model credentials are separate from the harness. PrismaLens never stores a key — it reads it fresh from the environment on every run (ADR-0006).

What a run costs

An investigation drives a coding-agent harness through multiple tool calls, so a single run can burn a large number of tokens — and that cost accrues on your own provider bill, not PrismaLens’s (there’s no PrismaLens account or subscription to meter it). If you want to try PrismaLens before spending real money, local Ollama or Ollama Cloud’s free tier are the cheapest way in.

deepagents — OpenAI-protocol only

deepagents speaks the OpenAI API shape, so it works with anything that exposes that protocol: Ollama, OpenAI itself, Groq, or a self-hosted OpenAI-compatible endpoint.

Provider	API key env var	Base URL env var	Notes
Ollama Cloud (default)	OLLAMA_API_KEY	OLLAMA_BASE_URL (defaults to https://ollama.com/v1)	Works with just the key set — no base URL override needed
Local Ollama	OLLAMA_API_KEY (usually unneeded)	OLLAMA_BASE_URL=http://localhost:11434/v1	The default base URL points at Ollama Cloud, not localhost — you must set this to run against a local server
OpenAI	OPENAI_API_KEY	OPENAI_BASE_URL=https://api.openai.com/v1	Set both — without the base URL override, your OpenAI key is sent to the Ollama Cloud endpoint by default
Groq / other OpenAI-compatible	OPENAI_API_KEY (the endpoint’s key)	OPENAI_BASE_URL=<endpoint>	For Groq: https://api.groq.com/openai/v1

OLLAMA_API_KEY/OLLAMA_BASE_URL win over OPENAI_API_KEY/OPENAI_BASE_URL when both are set. Set only the pair for the provider you actually want.

# Local Ollama
export OLLAMA_BASE_URL=http://localhost:11434/v1

# OpenAI directly
export OPENAI_API_KEY=sk-...
export OPENAI_BASE_URL=https://api.openai.com/v1

# Groq
export OPENAI_API_KEY=gsk_...
export OPENAI_BASE_URL=https://api.groq.com/openai/v1

These exports apply to the current shell only; add them to your shell profile (~/.bashrc, ~/.zshrc) to persist them.

claude-code — an Anthropic account

claude-code uses the Claude Agent SDK, which authenticates the same way the Claude Code CLI does:

• Signed in — run claude once after installing and follow the browser prompt. PrismaLens picks up the resulting ~/.claude/.credentials.json automatically.
• API key — set ANTHROPIC_API_KEY instead.

npm install -g @anthropic-ai/claude-code
claude   # follow the login prompt once, or set ANTHROPIC_API_KEY instead

The report-synthesis step needs an OpenAI-compatible credential too

This is easy to miss: claude-code only covers the investigation itself (Tier-2). The final report — the ordered-evidence writeup — is always synthesized by an OpenAI-compatible model call (Tier-1 reduce), regardless of which harness you picked. So a claude-code run still needs OLLAMA_API_KEY or OPENAI_API_KEY set, on top of your Anthropic credential, or the run finishes the investigation but fails to synthesize the report.

Choosing a harness and model

# Use claude-code for this run instead of the config default
prismalens investigate --harness claude-code -q "checkout latency spike"

# Override the model (a bare id — PrismaLens applies the harness's own provider prefix)
prismalens investigate --model gpt-oss:120b -q "OOMKilled in payments pod"

Or set them in prismalens.config.yaml:

agent:
  default: deepagents            # deepagents | claude-code | codex
  model: gpt-oss:120b            # a BARE id — the chosen harness applies its own provider prefix

--harness and agent.default accept codex, but selecting it throws immediately — it isn’t wired up yet.

Checking your setup

prismalens doctor runs before every investigation and checks:

• the configured harness’s binary is on PATH,
• some LLM credential is present — any of ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY, OLLAMA_API_KEY, GROQ_API_KEY, CUSTOM_LLM_API_KEY, or a signed-in Claude Code session,
• the workspace directory is writable.

That credential check is intentionally broad — it’s a smoke test, not a guarantee your chosen harness will actually work. Only OLLAMA_API_KEY/OPENAI_API_KEY (for deepagents and the report-synthesis step) and ANTHROPIC_API_KEY/Claude Code login (for claude-code) are ever actually read during a run. Setting GOOGLE_API_KEY, for example, satisfies doctor but won’t make anything work.

prismalens doctor

Next steps

• Run your first investigation: CLI overview
• See every flag on investigate: CLI commands
• Full prismalens.config.yaml reference: Configuration