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
130
131
132
133
134
|
# 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.<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-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.
|
