Generate, run, and verify synthetic RL worlds over HTTP.

You want a simulation environment where your agent practices long-horizon work — ERP, CRM, spreadsheet ops — and gets measurably better. /api/v1/environments is that path in five calls: create a world that mirrors the customer’s system, get every mock tool as a callable HTTP endpoint with OpenAI and Anthropic schemas already formatted, isolate state per eval run, and score with an executable verifier. Your production agent code does not need an MCP client, a JSON-RPC envelope, or any knowledge of our world model.

mode="deep" builds the research-backed world (anchors, tool-survival and task-acceptance gates — minutes).mode="preview" returns an ungrounded prototype in seconds for wiring up a harness; it is not production- or training-grade, and every response says so in its contract field. Both modes share one env_id and one polling contract, so switching is a one-word change.

# 1. Create a world that mirrors the customer's system.
curl -sX POST https://blobfish.ai/api/v1/environments \
  -H 'X-API-Key: bf_YOUR_KEY' -H 'Content-Type: application/json' \
  -d '{"prompt":"ERP for a mid-size industrial distributor: purchase orders, inventory receipts, three-way invoice match","mode":"deep"}'
# -> 202 {"env_id":"job_9f2c4b18aa","status":"building", ...}

# 2. Poll the SAME handle until the mock tools exist (one contract for both modes).
curl -s https://blobfish.ai/api/v1/environments/job_9f2c4b18aa -H 'X-API-Key: bf_YOUR_KEY'
# -> {"status":"ready","tools":[...],"openai_tools":[...],"anthropic_tools":[...],"tasks":[...]}

# 3. Isolate state for ONE eval rollout.
curl -sX POST https://blobfish.ai/api/v1/environments/job_9f2c4b18aa/sessions \
  -H 'X-API-Key: bf_YOUR_KEY' -H 'Content-Type: application/json' -d '{}'
# -> 201 {"session_id":"sess_4d9a1c77b0e3f2a5"}

# 4. Call a mock tool — POST the model's tool-call arguments verbatim.
curl -sX POST https://blobfish.ai/api/v1/environments/job_9f2c4b18aa/tools/approve_purchase_order \
  -H 'X-API-Key: bf_YOUR_KEY' -H 'X-Blobfish-Session: sess_4d9a1c77b0e3f2a5' \
  -H 'Content-Type: application/json' -d '{"order_id":4182,"approver":"j.reyes"}'

# 5. Score the rollout with the task's executable verifier (no LLM judge).
curl -sX POST https://blobfish.ai/api/v1/environments/job_9f2c4b18aa/verify \
  -H 'X-API-Key: bf_YOUR_KEY' -H 'X-Blobfish-Session: sess_4d9a1c77b0e3f2a5' \
  -H 'Content-Type: application/json' -d '{"task_id":"task_approve_blocked_po"}'
# -> {"passed":true,"reward":1,"verified_by":"vcode","assertions":[...]}

A complete, standalone project that creates a world and evaluates a production agent against its mock tools with Langfuse reporting lives at demo/frontier-lab-eval/. One dependency (httpx); the client is a single readable file.

# pip install httpx
from blobfish_eval import BlobfishClient, run_eval

with BlobfishClient(api_key="bf_YOUR_KEY") as client:
    env = client.create_environment(
        "ERP for a mid-size industrial distributor: purchase orders, "
        "inventory receipts, three-way invoice match, credit-hold approvals",
        mode="deep",          # "preview" = ungrounded prototype in seconds
    )
    env.wait_until_ready()    # same polling contract for both modes

    print(run_eval(env).summary())
    # environment : job_9f2c4b18aa  (mode=deep)
    # agent       : anthropic/claude-sonnet-5
    # pass rate   : 11/18  (61%)
    # mean reward : 0.611
    # langfuse    : https://cloud.langfuse.com/datasets/blobfish-job_9f2c4b18aa

Swap in your own agent — it is the only file you need to touch. Tool calls are a plain JSON POST of the model’s arguments object:

# Your production agent plugs in here — nothing else changes.
class MyProductionAgent:
    provider = "acme"
    model = "acme-planner-v7"

    def run(self, task, tools, session):
        # tools   -> name, JSON Schema, mutates flag, callable URL
        # session -> isolated state for THIS rollout
        response = anthropic.Anthropic().messages.create(
            model="claude-sonnet-5",
            max_tokens=2048,
            messages=[{"role": "user", "content": task.prompt}],
            tools=env.anthropic_tools,      # paste them straight in
        )
        for block in response.content:
            if block.type == "tool_use":
                session.call_with(block.name, dict(block.input))
        ...

run_eval(env, agent=MyProductionAgent())

One session per rollout. A Langfuse dataset run executes many items concurrently; without a session per item they all mutate the same rows and every verifier result after the first scores someone else’s writes — the run stops being reproducible without ever looking broken.

# Each task runs in its OWN session, so concurrent rollouts never collide.
# Scores pushed to Langfuse are the environment's executable verifier output.
export LANGFUSE_PUBLIC_KEY=pk-lf-...  LANGFUSE_SECRET_KEY=sk-lf-...
export ANTHROPIC_API_KEY=sk-ant-...

python run_eval.py --mode deep --agent anthropic --workers 8

#   PASS  task_approve_blocked_po   reward=1.00  turns=5
#   FAIL  task_three_way_match      reward=0.00  turns=12
# -> dataset run with per-task traces + blobfish_reward / blobfish_passed scores

Generate a world, act in it, and score the result in eight steps. Commands run against https://blobfish.ai. Endpoints that depend on external infrastructure (RunPod deploy, Composio research, GPU training) return an explicit not_configured status when unavailable. Get a free API key for higher rate limits and world ownership, or try anonymously (10 generations/day).

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

# Returns: { "key": "bf_626c4b...", "tier": "free", "rate_limits": {...} }
# Then pass either header on all subsequent requests:
#   -H 'X-API-Key: bf_626c4b...'
#   -H 'Authorization: Bearer bf_626c4b...'

curl -sX POST https://blobfish.ai/api/v1/sandbox/jobs \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"law firm matter intake operations"}'

# Returns: { "job_id": "job_e78af19041f046eb", "status": "creating_world" }

# Option A: Poll
curl -s https://blobfish.ai/api/v1/sandbox/jobs/job_e78af19041f046eb
# Returns: { "job": { "status": "ready", "world_id": "sbx_..." } }
# On failure: { "job": { "status": "failed", "error": "Stage \"...\" failed: ..." } }

# Option B: SSE stream
curl -sN https://blobfish.ai/api/v1/sandbox/jobs/job_e78af19041f046eb/stream
# data: {"type":"progress","phase":"research","detail":"Discovering tools..."}
# data: {"type":"done","status":"ready","world_id":"sbx_..."}

curl -s https://blobfish.ai/api/v1/sandbox/worlds/sbx_9f3aa4bc \
  | python3 -m json.tool | head -40

# thesis.company, thesis.domain, thesis.roles
# tables[].name, tables[].columns, tables[].sample_rows
# tools[].name, tools[].type, tools[].source
# tasks[].task_id, tasks[].prompt, tasks[].required_tools
# verifiers[].task_id, verifiers[].assertions, verifiers[].vcode

curl -sX POST https://blobfish.ai/api/v1/sandbox/worlds/sbx_9f3aa4bc/run-task \
  -H 'Content-Type: application/json' \
  -d '{"task_id":"task_001"}'

# Returns: { "passed": true, "reward": 1, "runtime": "local",
#   "steps": [...], "verifier": { "passed": true, "assertions": [...] } }

curl -s https://blobfish.ai/api/v1/sandbox/worlds/sbx_9f3aa4bc/quality

# Returns: { "quality": { "degenerate_tasks": 0, "total_tasks": 14,
#   "grounding_coverage": { "coverage": 0.833 },
#   "difficulty": { "easy": 4, "medium": 6, "hard": 4 } },
#   "validity": { "training_ready": true, "blockers": [] },
#   "creation_calibration": { "summary": {...}, "tasks": [{"pass_rate": 0.5, "variance": {...}}] } }

curl -s 'https://blobfish.ai/api/v1/sandbox/worlds/sbx_9f3aa4bc/download?format=harbor' \
  -o harbor-tasks.tar.gz

mkdir harbor-release && tar xzf harbor-tasks.tar.gz -C harbor-release/
cd harbor-release
docker build -t blobfishai/world-sbx_9f3aa4bc:local world-image
uvx harbor run -p tasks -a oracle

# Option A: Run locally
cd my-world && docker build -t world . && docker run -p 8080:8080 world

# Option B: Deploy to RunPod
curl -sX POST https://blobfish.ai/api/v1/sandbox/worlds/sbx_9f3aa4bc/deploy
# Returns: { "status": "deployed", "url": "https://api.runpod.ai/v2/ep_abc" }

No hosted job needed. The blobfish skill turns any Claude-Code-driven repo into a local practice 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. Prefer clicking to typing? Build in the browser from the portal.

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

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

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

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

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

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

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 — then fork one isolated session per rollout.

# Fast shared preview
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": "…" } }

# Deep composite company world (asynchronous)
curl -sX POST https://blobfish.ai/api/v1/sandbox/jobs \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: bf_…' \
  -H 'Idempotency-Key: northstar-mutual-v1' \
  -d '{"mode":"deep","company_type_key":"insurance_carrier","company_instance_key":"northstar_mutual","prompt":"Northstar Mutual: sales, claims, underwriting, HR, finance, and compliance workflows"}'

curl -s https://blobfish.ai/api/v1/sandbox/jobs/<jobId> \
  -H 'X-API-Key: bf_…'
# → { "status":"succeeded", "world_id":"sbx_…", ... }

curl -siX POST https://blobfish.ai/api/v1/sandbox/worlds/<worldId>/sessions \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: bf_…' \
  -d '{}'
# → Mcp-Session-Id: sess_…
# → { "session_id":"sess_…", "mcp_url":"…/mcp" }

curl -sX POST <mcp_url> \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: bf_…' \
  -H 'Mcp-Session-Id: sess_…' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

curl -sX POST https://blobfish.ai/api/v1/sandbox/worlds/<worldId>/sessions/<sessionId>/reset \
  -H 'X-API-Key: bf_…'

63 endpoints grouped into 11 categories. Click Try it on any endpoint to send a live request from this page.

{
  "world_id": "sbx_9f3aa4bc6f684ff3",
  "thesis": {
    "company": "Meridian Legal Partners",
    "domain": "legal",
    "vertical": "legal_services",
    "roles": [
      "partner",
      "associate",
      "paralegal"
    ]
  },
  "tables": [
    {
      "name": "matters",
      "columns": [
        "id",
        "title",
        "status",
        "assigned_to"
      ],
      "row_count": 12
    }
  ],
  "tools": [
    {
      "name": "open_matter",
      "type": "write",
      "target_tables": [
        "matters"
      ]
    }
  ],
  "tasks": [
    {
      "task_id": "task_001",
      "prompt": "Open matter MAT-2024-0031 and assign to associate Chen",
      "required_tools": [
        "open_matter"
      ]
    }
  ],
  "verifiers": [
    {
      "task_id": "task_001",
      "assertions": [
        "matters_mat_2024_0031_status_is_open",
        "matters_mat_2024_0031_assigned_to_is_chen",
        "no_collateral_matters",
        "reads_before_writes"
      ]
    }
  ]
}

curl -sX POST https://blobfish.ai/api/v1/sandbox/generate \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"law firm matter intake operations","anchor_files":[{"filename":"matter-intake-prd.md","content":"# Matters Schema\n- title: string\n- status: enum open closed\n# Clients Schema\n- name: string\n- email: string"}]}'

{
  "job_id": "job_e78af19041f046eb",
  "status": "creating_world",
  "stages": [
    {
      "key": "create_world",
      "label": "Creating world",
      "status": "running"
    },
    {
      "key": "make_package",
      "label": "Making executable package",
      "status": "pending"
    },
    {
      "key": "launch_sandbox",
      "label": "Launching sandbox",
      "status": "pending"
    },
    {
      "key": "run_first_test",
      "label": "Running first agent test",
      "status": "pending"
    }
  ]
}

curl -sX POST https://blobfish.ai/api/v1/sandbox/jobs \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: campaign-request-001' \
  -d '{"prompt":"insurance carrier operations","company_instance_key":"northstar_mutual","target_failure_rate":0.5,"anchor_files":[{"filename":"CUSTOMER_PRD.md","content":"# Requirements"}],"fresh":true}'

{
  "job": {
    "job_id": "job_e78af19041f046eb",
    "status": "ready",
    "world_id": "sbx_9f3aa4bc6f684ff3",
    "stages": [
      {
        "key": "run_first_test",
        "label": "Running first test",
        "status": "completed"
      }
    ]
  }
}

curl -s https://blobfish.ai/api/v1/sandbox/jobs/job_e78af19041f046eb

{
  "job": {
    "job_id": "job_e78af19041f046eb",
    "status": "running_first_test"
  },
  "queue": "job_table",
  "retry_replayed": false
}

curl -sX POST https://blobfish.ai/api/v1/sandbox/jobs/job_e78af19041f046eb \
  -H 'Content-Type: application/json' \
  -d '{"action":"retry"}'

data: {"type":"stage","stage":"creating_world"}

data: {"type":"progress","stage":"create_world","phase":"research","detail":"Discovering MCP tools...","iteration":1,"maxIterations":3}

data: {"type":"heartbeat","job_id":"job_e78af19041f046eb","status":"creating_world","updated_at":"2026-08-04T14:00:54.241Z"}

data: {"type":"thesis_preview","thesis":{"company":"Meridian Legal","domain":"legal"}}

data: {"type":"done","status":"ready","world_id":"sbx_9f3aa4bc6f684ff3"}

# Failure is equally terminal — never an infinite stream:
# data: {"type":"done","status":"failed","error":"Stage \"Creating world\" failed: ..."}
# data: {"type":"timeout"}  (stream safety-closes after 30 minutes)

curl -sN https://blobfish.ai/api/v1/sandbox/jobs/job_e78af19041f046eb/stream

{
  "jobs": [
    {
      "job_id": "job_e78af19041f046eb",
      "status": "ready",
      "world_id": "sbx_9f3aa4bc6f684ff3",
      "prompt": "law firm matter intake"
    },
    {
      "job_id": "job_a1b2c3d4e5f60718",
      "status": "creating_world",
      "prompt": "dental clinic scheduling"
    }
  ]
}

curl -s https://blobfish.ai/api/v1/sandbox/jobs

{
  "world_id": "sbx_1767ddbd5dcd",
  "url": "/w/sbx_1767ddbd5dcd",
  "target": "sandbox",
  "counts": {
    "tables": 36,
    "rows": 745,
    "tools": 113,
    "tasks": 11,
    "verifiers": 11
  },
  "warnings": []
}

# JSON import (sandbox):
curl -sX POST https://blobfish.ai/api/v1/sandbox/worlds/import \
  -H 'Content-Type: application/json' --data-binary @world_payload.json

# tar.gz import (hosted world store):
tar czf world.tar.gz -C ./blobfish_worlds env_myapp_mirror_x
curl -sX POST https://blobfish.ai/api/v1/sandbox/worlds/import \
  -H 'X-API-Key: bf_yourkey' \
  -F world=@world.tar.gz -F label="My App Mirror"

# JSON import into hosted store:
curl -sX POST "https://blobfish.ai/api/v1/sandbox/worlds/import?target=hosted" \
  -H 'Content-Type: application/json' --data-binary @world_payload.json

{
  "world_id": "env_nario_mock",
  "status": "ready",
  "created": true,
  "archive_sha256": "4d3c…",
  "validation": {
    "sqlite_integrity": "ok",
    "scenario_count": 8,
    "verifier_count": 42
  },
  "tool_count": 117,
  "task_count": 42,
  "mcp_url": "/api/v1/worlds/env_nario_mock/mcp",
  "evaluate_url_template": "/api/v1/worlds/env_nario_mock/tasks/{task_id}/evaluate",
  "runtime": "fleet_sandbox",
  "ownership": "api_key"
}

# Fast path from an app-mirror skill bundle:
blobfish mirror publish ./worlds/env_nario_mock \
  --base https://blobfish.ai --api-key bf_YOUR_KEY --out ./nario-world.tar.gz

# Equivalent raw API call:
curl -sX POST https://blobfish.ai/api/v1/worlds/import \
  -H 'X-API-Key: bf_YOUR_KEY' \
  -F world=@nario-world.tar.gz -F label="Nario exact mock"

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "serverInfo": {
      "name": "fleet-world-factory-mcp",
      "version": "1.0.0"
    }
  }
}

curl -i -sX POST https://blobfish.ai/api/v1/worlds/env_nario_mock/mcp \
  -H 'X-API-Key: bf_YOUR_KEY' -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}'

# Reuse the Mcp-Session-Id response header:
curl -sX POST https://blobfish.ai/api/v1/worlds/env_nario_mock/mcp \
  -H 'X-API-Key: bf_YOUR_KEY' -H 'Mcp-Session-Id: SESSION_ID' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

{
  "world_id": "env_nario_mock",
  "task_id": "task_invite_member",
  "passed": true,
  "reward": 1,
  "steps": [
    {
      "step": 1,
      "tool": "inviteMember",
      "arguments": {
        "email": "new@example.com"
      }
    }
  ],
  "verifier_detail": {
    "kind": "exact_call_trace",
    "scored": true
  }
}

curl -sX POST https://blobfish.ai/api/v1/worlds/env_nario_mock/tasks/task_invite_member/evaluate \
  -H 'X-API-Key: bf_YOUR_KEY'