Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Getting started

Install

cargo install canact --locked --features cli

Prebuilt archives ship on GitHub Releases (macOS, Linux, Windows x64):

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/canact/canact/releases/latest/download/canact-installer.sh | sh

brew trust canact/tap
brew install canact/tap/canact

Windows (Scoop, x64):

scoop bucket add canact https://github.com/canact/scoop-bucket
scoop install canact/canact

Library (runtime only, no CLI):

canact = { version = "0.10", default-features = false, features = ["runtime"] }

MSRV is Rust 1.95.

First probe

canact probe --provider ollama --model llama3.2:3b --cheap --json

The built-in Ollama URL is http://127.0.0.1:11434/v1. That string is the crate constant OLLAMA_BASE_URL. Nothing reads an environment variable of that name. Pass --base-url to use a different URL.

--cheap is --suite=policy (host-policy fields, 4k ladder). --full adds sequencing and the 8k/16k ladder. --suite=all adds diagnostics.

Cloud hosts need a key before any HTTP call. The first match in this table wins. --api-key is visible in shell history and the process list; prefer an env var. canact probe --no-login skips stored Grok and Claude Code logins. Env vars still apply. canact probe --dry-run prints the provider, redacted base URL, suite, and probe names, then exits. It does not read a login, the cache, or the network. canact probe --fail-on weak exits 2 when a finished row is Weak. --fail-on degraded also exits 2 for Medium. A skipped row or a probe error does not count. An unknown value exits 1.

Provider labelDefault URL when --base-url is omittedWhat is tried, first match winsStored login
emptyhttps://api.openai.com/v1, unless a key selects the xAI, Anthropic, or OpenRouter host--api-key, else OPENAI_API_KEY, else XAI_API_KEY then GROK_API_KEY then Grok login, else ANTHROPIC_AUTH_TOKEN then ANTHROPIC_API_KEY then Claude Code login, else OPENROUTER_API_KEYGrok login unless --api-key, OPENAI_API_KEY, OPENROUTER_API_KEY, XAI_API_KEY, or GROK_API_KEY is set. An Anthropic env key does not skip it. Claude Code login runs only when nothing earlier matched. --no-login skips only those two helpers.
xai, grok, api.x.ai, x.aihttps://api.x.ai/v1--api-key, else XAI_API_KEY, else GROK_API_KEY, else Grok login. Ignores OPENAI_API_KEY.~/.grok/auth.json. A named xAI provider still loads it when OPENAI_API_KEY is set.
grok-build, xai-grok-build, cli-chat-proxy.grok.com, and the -messages pairhttps://cli-chat-proxy.grok.com/v1Same xAI packSame Grok login
claude, anthropic, api.anthropic.comhttps://api.anthropic.com/v1--api-key, else ANTHROPIC_AUTH_TOKEN, else ANTHROPIC_API_KEY, else Claude Code. Ignores OpenAI and xAI.Claude Code login
openrouter, openrouter.aihttps://openrouter.ai/api/v1--api-key, else OPENAI_API_KEY, else OPENROUTER_API_KEY. No stored login.none
groq, api.groq.comhttps://api.groq.com/openai/v1--api-key, else GROQ_API_KEY. No stored login.none
amazon-bedrock, bedrockhttps://bedrock-runtime.us-east-1.amazonaws.com--api-key, else AWS_BEARER_TOKEN_BEDROCK. No stored login.none
openai-codex, codexhttps://api.openai.com/v1--api-key, else OPENAI_API_KEY. No stored login.none
ollama, localhost, 127.0.0.1, ::1, 0.0.0.0http://127.0.0.1:11434/v1 (this constant, not an environment variable)nonenone
lmstudiohttp://127.0.0.1:1234/v1nonenone
vllmhttp://127.0.0.1:8000/v1nonenone

Auth, a missing model, and connect failures abort the suite.

--json prints the host-policy envelope. Field definitions and the rest of that object are in Read the card. Dry runs that do not call a model live in the repo examples/ directory.