# 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 (works once configured — Phase 1's `openaicompat` adapter, no dedicated phase needed) | free tier (real, no card required historically) | OpenAI-compatible | | OpenRouter | to add (same as Groq) | free tier (rate-limited) + pay-as-you-go | OpenAI-compatible | | OpenAI | to add (same as Groq) | prepaid credit, no ongoing free tier | OpenAI-compatible (native) | | Google (Gemini) | **wired up (Phase 4)** — `agent.type: "google"` works as soon as a key is in `config.toml` | paid (already have account) | native (Gemini API) | | Anthropic (Claude) | **wired up (Phase 2)** — `agent.type: "anthropic"` works as soon as a key is in `config.toml` | paid (already have account) | 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-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, and this one's live too Same situation as Anthropic below: 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 `generateContent` 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` (e.g. `gemini-2.5-flash` for a cheap/fast rung, `gemini-2.5-pro` for a more capable one). 5. Since this is a separate credential from the CLI's OAuth session, keep an eye on AI Studio/Cloud Console usage separately from whatever the `gemini` CLI itself reports — they draw from the same account but are tracked as distinct API consumers. This is intentional: `executions.agent = "google"` (native path) and `"gemini"` (CLI-subprocess `ContainerRunner` path) are tracked as **separate budget buckets** even though both bill the same account — set `[budget].provider_5h_usd.google` independently of `.gemini` if you want different caps on each. 6. As soon as the key is set, `claudomator serve`/`run` registers `agent.type: "google"` as a usable runner — no restart-time flag needed beyond having the key present. To turn it off without removing the key, set `[runners] google = false`. 7. Verify it's live: submit any task with `agent.type: "google"`, then check `GET /api/budget` for a distinct `"google"` row once the execution completes. 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, and this one's live 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 — **do not** try to reuse the CLI's OAuth session or a `claude setup-token` credential here: Anthropic's own Agent SDK terms say subscription/OAuth auth is for Claude Code (or the Agent SDK, i.e. Claude Code as a library) specifically, not for powering a separate third-party product's API calls, which is what claudomator's native adapter is. Use a real 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-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. This is intentional: `executions.agent = "anthropic"` (native path) and `"claude"` (CLI-subprocess `ContainerRunner` path) are tracked as **separate budget buckets** even though both bill the same account — set `[budget].provider_5h_usd.anthropic` independently of `.claude` if you want different caps on each. 6. As soon as the key is set, `claudomator serve`/`run` registers `agent.type: "anthropic"` as a usable runner — no restart-time flag needed beyond having the key present. To turn it off without removing the key, set `[runners] anthropic = false`. 7. Verify it's live: submit any task with `agent.type: "anthropic"`, then check `GET /api/budget` for a distinct `"anthropic"` row once the execution completes. --- ## 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.