From bbd58e8d77f7c996add29b69f600e835a922542e Mon Sep 17 00:00:00 2001 From: Claude Sonnet 5 Date: Fri, 3 Jul 2026 09:02:35 +0000 Subject: docs: add API key setup guide for Groq, OpenRouter, OpenAI, Google, Anthropic MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Covers signup flow, current free-tier limits, and where credentials land in config.toml for every provider the harness redesign targets. Written earlier but never committed, so it was invisible to the Phase 1/2 implementation worktrees — landing it now before Phase 2 merges to avoid two divergent versions of this file. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01V1moSNCJRcP6kykA4tyUSs --- docs/api-keys-setup.md | 129 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 docs/api-keys-setup.md (limited to 'docs') diff --git a/docs/api-keys-setup.md b/docs/api-keys-setup.md new file mode 100644 index 0000000..bf58f1e --- /dev/null +++ b/docs/api-keys-setup.md @@ -0,0 +1,129 @@ +# API Key Setup Guide + +This guide covers getting an API key for each cloud provider claudomator's multi-role harness can escalate to, and where the key goes once you have it. It does **not** cover local models (Ollama/vLLM/LM Studio etc. — those use `[local_model]` in `config.toml` and generally need no key). + +Providers, in escalation-ladder order (cheapest/free first): + +| Provider | Status | Cost | Wire format | +|---|---|---|---| +| Groq | to add | free tier (real, no card required historically) | OpenAI-compatible | +| OpenRouter | to add | free tier (rate-limited) + pay-as-you-go | OpenAI-compatible | +| OpenAI | to add | prepaid credit, no ongoing free tier | OpenAI-compatible (native) | +| Google (Gemini) | already have paid account | paid | native (Gemini API) | +| Anthropic (Claude) | already have paid account | paid | native (Messages API) | + +> Note on freshness: signup flows and free-tier limits change without much notice. Treat the specific numbers below (rate limits, credit thresholds) as "true as of when this was written" and double-check the provider's own pricing/limits page before relying on them for capacity planning. + +--- + +## Where keys go + +Once you have a key, it lands in `~/.claudomator/config.toml` under a `[providers.]` table: + +```toml +[providers.groq] +endpoint = "https://api.groq.com/openai/v1" +api_key = "gsk_..." +default_model = "llama-3.3-70b-versatile" + +[providers.openrouter] +endpoint = "https://openrouter.ai/api/v1" +api_key = "sk-or-..." +default_model = "meta-llama/llama-3.3-70b-instruct:free" + +[providers.openai] +endpoint = "https://api.openai.com/v1" +api_key = "sk-..." +default_model = "gpt-4o-mini" + +[providers.anthropic] +api_key = "sk-ant-..." +default_model = "claude-sonnet-4-5" + +[providers.google] +api_key = "AIza..." +default_model = "gemini-2.5-flash" +``` + +`config.toml` is not committed to the repo (it lives in the claudomator data dir, `~/.claudomator/` by default) — this is the same place `local_model.api_key` already lives today, so no new secret-handling pattern, just more provider entries. + +**Do not** put these keys in `credentials/claude/` or `credentials/gemini/` — those directories hold CLI OAuth session state for the `claude`/`gemini` command-line tools (`ContainerRunner`'s path) and are a different kind of credential from a plain bearer API key. + +--- + +## Groq + +Free tier, no credit card required to start. Good first escalation rung above local models — fast inference, real (if modest) daily limits. + +1. Go to `console.groq.com` and sign in (Google/GitHub/email). +2. Left nav → **API Keys** → **Create API Key**. Name it something identifying claudomator (e.g. `claudomator-harness`). +3. Copy the key immediately — Groq only shows it once (`gsk_...`). +4. Rate limits (free tier, vary per model): roughly 30 requests/minute, 6K–70K tokens/minute, 1K–14.4K requests/day, 100K–500K tokens/day depending on the specific model. Check `console.groq.com/settings/limits` for your account's current numbers per model — this varies enough by model that it's worth checking directly rather than trusting a fixed table here. +5. Put the key in `config.toml` under `[providers.groq]` as shown above. `endpoint` is Groq's OpenAI-compatible base: `https://api.groq.com/openai/v1`. + +--- + +## OpenRouter + +Aggregates many providers/models behind one key, including models with a `:free` suffix. Useful as a second free-tier rung, or to reach models Groq doesn't host. + +1. Go to `openrouter.ai` and sign in. +2. **Keys** (in account settings) → **Create Key**. Name it, copy it (`sk-or-...`) — shown once. +3. Free-tier limits: **without any credit purchase**, 50 free-model requests/day total across all `:free`-suffixed models. **With $10+ in purchased credits**, that jumps to 1000 requests/day (a one-time credit purchase, not a subscription) — worth doing once your usage grows past the bare free tier, since it's a 20x limit increase for a fixed cost, not a recurring charge. +4. Pick a free model when configuring the harness — model IDs ending in `:free` (e.g. `meta-llama/llama-3.3-70b-instruct:free`) don't draw down credits. Browse current free models at `openrouter.ai/models?max_price=0`. +5. `endpoint` is `https://openrouter.ai/api/v1`. + +--- + +## OpenAI + +No meaningful ongoing free tier at this point — expect to prepay. Included in the ladder mainly for model diversity/fallback, not as a cost-saving rung. + +1. Go to `platform.openai.com`, sign in, create an org if prompted. +2. **Settings → Billing** — add a payment method and some prepaid credit before making real calls (some new accounts get a small trial credit, but it's not guaranteed or large). +3. **Dashboard → API keys** (`platform.openai.com/api-keys`) → **Create new secret key**. Name it, copy it (`sk-...`) — shown once. +4. Consider setting a spend limit under **Billing → Limits** so a runaway harness escalation can't produce a surprise bill — this matters more here than for Groq/OpenRouter's free tiers. +5. `endpoint` is `https://api.openai.com/v1`. + +--- + +## Google (Gemini) — you already have a paid account + +The existing `credentials/gemini/` directory holds an OAuth session for the `gemini` CLI (used by `ContainerRunner`). The native-API path this harness adds is separate: a plain API key from Google AI Studio, used directly against the Gemini API rather than through the CLI. + +1. Go to `aistudio.google.com/apikey` (Google AI Studio), signed in with the same Google account as your paid plan. +2. **Create API key** — choose the Google Cloud project tied to your paid billing if prompted, so usage bills correctly rather than falling back to any free-tier project quota. +3. Copy the key (`AIza...`). +4. `[providers.google]` needs no `endpoint` override (the adapter defaults to the native Gemini API base) — just `api_key` and `default_model`. + +If you'd rather use Vertex AI (GCP's enterprise entry point to Gemini, with IAM-based auth instead of a bare API key) that's a heavier setup (service account, GCP project, `gcloud` auth) — not necessary for this harness unless you specifically want Vertex's quota/governance features. AI Studio's simple API key is sufficient for what's being built here. + +--- + +## Anthropic (Claude) — you already have a paid account + +Same situation as Gemini: `credentials/claude/` holds the `claude` CLI's OAuth session (`ContainerRunner`'s path). The native-API path needs a separate Console API key. + +1. Go to `console.anthropic.com`, sign in with your paid account. +2. **Settings → API Keys** → **Create Key**. Name it, select the workspace tied to your billing if you have more than one. +3. Copy the key (`sk-ant-...`) — shown once. +4. `[providers.anthropic]` needs no `endpoint` override — just `api_key` and `default_model` (e.g. `claude-sonnet-4-5` for the escalation ladder's cloud rung, or a Haiku-tier model for a cheaper intermediate rung before Sonnet). +5. Since this is a separate credential from the CLI's OAuth session, keep an eye on Console usage/billing separately from whatever the `claude` CLI itself reports — they draw from the same account but are tracked as distinct API consumers. + +--- + +## Sanity-checking a key works + +Once phase 1/2/4 of the harness redesign land (native `Provider` adapters), the quickest check is submitting a trivial role-typed task pinned to a single rung, e.g. via the CLI: + +```bash +./claudomator run - <<'EOF' +name: "provider smoke test" +agent: + type: "groq" # or anthropic / google / openai / openrouter + model: "llama-3.3-70b-versatile" + instructions: "Reply with the word OK and nothing else." +EOF +``` + +and checking `GET /api/budget` afterward to confirm the provider's spend/usage was recorded. Until then, you can at minimum confirm the key itself is valid with a raw `curl` against the provider's chat-completions endpoint using the docs above. -- cgit v1.2.3