00 Setup

Instructor notes for module 00 — timing, talk track, common failures, and reset steps.

Facilitator companion to the learner lesson 00 Setup.

Before the session — provision a shared learner key (fair usage)

For a public, instructor-led run, don't hand a room of strangers your personal OpenRouter key or an uncapped one. OpenRouter has a Management (provisioning) API that mints purpose-made keys with a hard credit cap, programmatically — so the workshop's spend is bounded and fair.

1. Create a Management key (one time). OpenRouter → Settings → Management API Keys (openrouter.ai/settings/management-keys) → Create New Key. This key can create, inspect, and delete other keys and spend on your account — treat it as an admin credential.

export OPENROUTER_PROVISIONING_KEY=sk-or-v1-<management-key>   # instructor only — never share

2. Provision the shared learner key with a hard cap. The repo ships a helper (scripts/provision_workshop_keys.py) that calls POST https://openrouter.ai/api/v1/keys/:

# one shared key the whole room uses, capped at $20 total (reset daily at 00:00 UTC):
python -m scripts.provision_workshop_keys --name "AgentArena $(date +%F)" --limit 20 --daily

The create response prints the key string once — copy it and give it to learners as their OPENROUTER_API_KEY. Afterwards only its hash is retrievable (to inspect or delete). Prefer raw curl? Same call:

curl -s https://openrouter.ai/api/v1/keys/ \
  -H "Authorization: Bearer $OPENROUTER_PROVISIONING_KEY" \
  -H "content-type: application/json" \
  -d '{"name":"AgentArena workshop","limit":20}'

Fairer for large cohorts. One shared key means a single learner can burn the whole budget. For 20+ people, mint one capped key per learner instead — each bounded on its own:

python -m scripts.provision_workshop_keys --name "AgentArena $(date +%F)" --limit 2 --count 30

That creates 30 keys, each capped at $2. Distribute one per learner.

3. Watch and clean up. Inspect spend mid-session and delete keys when done:

python -m scripts.provision_workshop_keys --list
python -m scripts.provision_workshop_keys --delete <keyHash>

The Management key can spend and create/delete keys on your account. Keep it in the instructor's .env only — never in learner handouts, slides, or the shared repo. Learners only ever receive the provisioned learner key (a normal, capped sk-or-v1-…).

Sizing: the roster is the cheap flash-lite tier and the grid is only 6 × 3 = 18 configs, so a $20 shared cap comfortably covers a full room running the Arena a few times — the cap is a guardrail against runaway loops, not a tight budget.

Timing

~20 minutes total.

5 min — create the three accounts (OpenRouter, LangFuse Cloud, ClickHouse Cloud) if learners haven't done this the day before.
5 min — clone the repo, create the virtualenv, install dependencies.
5 min — fill in .env.
5 min — source .env && scripts/arena.sh up, confirm the dashboard loads at http://localhost:5174.

Talk track

Open by naming all three accounts up front — OpenRouter, ClickHouse Cloud, LangFuse Cloud — and say explicitly that LangFuse is one of them, in the very first module, before a single model has been picked. That's the whole point: LangFuse isn't a production add-on bolted on in Module 04, it's the tool that runs the contest next module.
Point at the architecture diagram and name the one shared code path: agents/ is used by both eval/harness.py (the benchmark) and serving/api.py (production) — so nothing measured today diverges from what ships in Module 04.
Narrate what scripts/arena.sh up actually does while it runs: creates the arena database, creates the arena_ro read-only user, generates synthetic e-commerce data directly into ClickHouse, builds the v_* views, and starts the dashboard API + web UI.
Set the expectation that the Leaderboard tab will be empty at the end of this module — that's correct, not a bug, and it's the cliffhanger into Module 01.

Common failures

Placeholder OPENROUTER_API_KEY left as sk-or-... — the harness will fail with a 401 the first time it calls a model in Module 01, not during setup itself. Ask learners to double check .env has a real key now, before it's expensive to debug later.
ARENA_RO_PASSWORD left blank — scripts/arena.sh up will still create the arena_ro user, but with an empty password, which the agent's read-only client may reject depending on the ClickHouse Cloud service's password policy. Have learners set any non-empty value.
ClickHouse Cloud service still provisioning — a freshly created service can take a minute or two to accept connections; scripts/arena.sh up will fail fast with a connection error if run too soon. Just wait and re-run.
.env not sourced before running the script — source .env && scripts/arena.sh up is one line for a reason; running scripts/arena.sh up on its own in a fresh shell fails on missing CLICKHOUSE_CLOUD_* env vars.
Port 5174 (or 8000) already in use — leftover process from a previous run. scripts/arena.sh stop clears local servers before re-running up.

Reset steps

Re-seed from scratch: source .env && scripts/arena.sh up — it is idempotent and ClickHouse-only (no Aurora, no ClickPipes, no ClickStack in this path); it recreates the arena database, the arena_ro user, the synthetic data, and the v_* views, then restarts the dashboard API and web UI.
If only the local servers are wedged (not ClickHouse), scripts/arena.sh stop followed by scripts/arena.sh serve is faster than a full up.
Verify state at any point with scripts/arena.sh status — it reports whether the dashboard API and web UI are up, and prints row counts for each v_* view.
If a learner's .env still has placeholder values, there is no shortcut — get the real key/credential and re-run scripts/arena.sh up.