Get Started · agents & API

Install the Blobfish skill. Generate your API key.

Two ways in: install the Claude Code skill and your agent generates local practice/eval worlds for its own domain/vertical — database, MCP tools, verifiable tasks, personas — then practices on them (attempt → verify → distill a skill → measure the lift). Production model training goes through Research-backed hosted jobs with grounding, quality, and calibration gates. Or skip the checkout and use the hosted API with an API key.

Free API key in one call — generated right on this page

Installer: skills/blobfish/install.sh

Agents train over MCP: task_start → tools → task_verify

Executable VCode rewards — no LLM judge, no free passes

1 · Generate an API key

One key unlocks world ownership and higher rate limits on the hosted API. Name it, give an email (used only to list/revoke your keys), and copy the key once — it is never shown again.

Free tier, no card. The key is created instantly and shown once. Anonymous access also works for quick tests (lower rate limits). Limit: 5 keys/hour per IP.

Prefer curl?

curl -sX POST https://blobfish.ai/api/v1/auth/keys \
  -H 'Content-Type: application/json' \
  -d '{"name":"my-agent","email":"you@company.com"}'

# check the key / your usage any time:
curl -s https://blobfish.ai/api/v1/auth/me -H 'X-API-Key: bf_…'

2 · Install the Claude Code skill

The blobfish skill turns any Claude-Code-driven repo into a local practice/eval ground: generate a world for your vertical (SQLite database + validated tools + verifiable tasks + personas, split practice/heldout), serve it over stdio MCP, practice tasks with executable-verifier rewards, and distill what worked into a skill for your repo. Fully offline — the keyless engine needs no LLM. Once installed, the full workflow lives in the skill's own SKILL.md.

Get the repo

The skill ships inside the blobfishai monorepo (requires repo access). Python 3.12+ on your machine; no API keys needed for generation.

git clone

git clone git@github.com:blobfishai/blobfishai.git ~/workplace/blobfishai

Install the skill into your repo

Copies the skill into your repo's .claude/skills/blobfish and pins BLOBFISH_HOME. Use --link instead to symlink (auto-updates with the checkout). Dev-time shell-out only — your repo gains no runtime dependency.

skills/blobfish/install.sh

bash ~/workplace/blobfishai/skills/blobfish/install.sh /path/to/your-repo
# → installed blobfish skill → /path/to/your-repo/.claude/skills/blobfish

Health check

Verifies Python, the checkout, and every pipeline import. Run this first whenever something misbehaves.

blobfish doctor

bash /path/to/your-repo/.claude/skills/blobfish/scripts/blobfish doctor
# python: 3.12.x ✓ · blobfish home ✓ · imports ✓ · doctor: OK

Generate a world for your vertical

Built-in offline presets: wonson_erp (trading ERP + channel order import), pmi_labor_agency (CPMI case management), shoebox_manufacturing (make-to-order production). Or pass --brief naming >=3 concrete entities. These are local practice/eval worlds; production training worlds require Research-backed hosted jobs with grounding and calibration gates.

blobfish generate

cd /path/to/your-repo
bash .claude/skills/blobfish/scripts/blobfish generate \
  --vertical shoebox_manufacturing --tenant acme --out ./blobfish_worlds
# world: env_acme_shoebox_manufacturing_…  · 11 tables · 24 tools · tasks split train/heldout

Connect your agent over MCP

The stdio MCP server exposes the world's tools plus the verified-episode lifecycle: task_list → task_start → (tool calls on the episode's scratch DB) → task_verify. Rewards are executable VCode — no LLM judge.

claude mcp add

claude mcp add blobfish-world -- \
  bash /path/to/your-repo/.claude/skills/blobfish/scripts/blobfish \
  serve /path/to/your-repo/blobfish_worlds/<world_dir> --run training-day1

Practice, distill, measure

Baseline first (oracle ≈ ceiling, random ≈ floor), practice the local split over MCP, distill verified successes into a draft skill for your repo, then re-eval on the heldout split and compare runs. Queue model training only through the hosted Research-backed sandbox training gates.

blobfish eval · distill · report

BF=.claude/skills/blobfish/scripts/blobfish
bash $BF eval  ./blobfish_worlds/<world_dir> --policy oracle --run oracle-base
bash $BF eval  ./blobfish_worlds/<world_dir> --policy random --run random-base
# …practice over MCP under --run training-day1, then:
bash $BF distill ./blobfish_worlds/<world_dir> --run training-day1 --out ./drafts
bash $BF report  ./blobfish_worlds/<world_dir> --compare training-day1,training-day2-with-skill

3 · No local checkout? Use the hosted API

The hosted API exposes both Quick Preview worlds and Research-backed sandbox jobs. Use POST /api/v1/worlds for evaluation previews, or POST /api/v1/sandbox/jobs with mode=deep for production-quality training candidates with grounding, quality, and calibration gates. Full reference on the API docs page.

Create a hosted preview over HTTP

No checkout needed — this prompt path returns a hosted Quick Preview with a stable worldId. Use /api/v1/sandbox/jobs mode=deep for Research-backed production/training worlds.

POST /api/v1/worlds

curl -sX POST https://blobfish.ai/api/v1/worlds \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: bf_…' \
  -d '{"prompt":"shoebox manufacturer work orders and QC"}'
# → { "worldId": "…", "links": { "mcp": "…" } }

Point any MCP client at it

The hosted world speaks JSON-RPC MCP over HTTP: initialize, tools/list, tools/call.

POST /api/v1/worlds/{worldId}/mcp

claude mcp add --transport http blobfish-hosted \
  https://blobfish.ai/api/v1/worlds/<worldId>/mcp

Act and verify

Call tools through MCP (or REST), then score real state changes with the world's verifiers.

POST /api/v1/worlds/{worldId}/verify

curl -sX POST https://blobfish.ai/api/v1/worlds/<worldId>/verify \
  -H 'Content-Type: application/json' -H 'X-API-Key: bf_…' -d '{}'