1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
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.<name>]` 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.
|
