Start a twin run

Create your account

Your account is an API key: a bf_ credential minted for an email address. Mint it in the browser on the portal, or — once the CLI is installed in the next step — from the terminal. blobfish login --email you@company.com mints the key non-interactively and stores it in ~/.blobfish/credentials.json (mode 600). The key is printed once and never shown again; every later blobfish twin … command reads it from that file, or from BLOBFISH_API_KEY when that is set.

$ blobfish login --email you@company.com
API key (shown once — it will not be shown again): bf_…
logged in as you@company.com
credentials saved to ~/.blobfish/credentials.json (chmod 600)

Run blobfish login again at any time to verify the stored key against the API. Keep the key out of source control; the twin’s receipt files below never contain it.

Install the CLI

The CLI is a Python 3.12+ tool installed with uv. The twin commands are dependency-free (standard-library HTTP), and the install line below is the one every twin page on this site renders from the same source.

$ uv tool install --with "blobfish-sdk @ https://blobfish.ai/sdk/blobfish_sdk-0.6.2-py3-none-any.whl" "blobfish-cli @ https://blobfish.ai/sdk/blobfish_cli-0.1.13-py3-none-any.whl"
$ blobfish twin catalog

blobfish twin catalog lists every twin with its live mounted status on this deployment — the same table as Available twins.

Start your first twin run

$ uv tool install --with "blobfish-sdk @ https://blobfish.ai/sdk/blobfish_sdk-0.6.2-py3-none-any.whl" "blobfish-cli @ https://blobfish.ai/sdk/blobfish_cli-0.1.13-py3-none-any.whl"
$ blobfish login
$ blobfish twin-runs create --twins salesforce --ttl 60 --wait

1. --twins salesforce names the twin(s) to mount — comma-separated or repeated; up to six per environment. One or two twins mount their full operation slice.
2. --ttl 60 is the lease in minutes, between 5 and 10080. Expiry is bookkeeping: the console and API label the environment expired; nothing is destroyed. Extend it later with blobfish twin-runs extend twe_<id> --ttl 60.
3. --wait polls until the environment reports ready or failed. A website-plane create is assembled synchronously, so it normally returns ready at once; the flag matters for the blank-harness path.
4. Optional: --name, --out-dir for the receipt files, --idempotency-key so a retried CI request cannot allocate twice, and --scenario-id / --scenario-prompt to seed the exact starting state (see Custom scenarios).

What you get back

twin-runs create prints the environment, its mounted twins, and its endpoints, then writes two files into the current directory:

env: twe_<id>
status: ready
name: Twin: salesforce
mounted services:
  salesforce (first_party_ir · 52 tools · 9 tables · 52 ops)
endpoints:
  mcp       https://blobfish.ai/api/v1/sandbox/worlds/sbx_<world>/mcp
  services  https://blobfish.ai/api/v1/sandbox/worlds/sbx_<world>/services
  cli       https://blobfish.ai/api/v1/twin/environments/twe_<id>/cli
  console   https://blobfish.ai/twin/twe_<id>
expires_at: <60 minutes from now, ISO 8601>
Environment assembled: per-service REST, MCP, and CLI surfaces are serving seeded state.
routing: routing.env
run record: .blobfish-twin-run.json

BLOBFISH_TWIN_ENDPOINT=https://blobfish.ai/api/v1/sandbox/worlds/sbx_<world>/mcp
BLOBFISH_TWIN_RUN_ENDPOINT=https://blobfish.ai/api/v1/twin/environments/twe_<id>
BLOBFISH_TWIN_CONSOLE_ENDPOINT=https://blobfish.ai/twin/twe_<id>
BLOBFISH_PRODUCTION_FALLBACK=0
BLOBFISH_TWIN_SALESFORCE_MCP=https://blobfish.ai/api/v1/sandbox/worlds/sbx_<world>/services/salesforce/mcp

BLOBFISH_TWIN_ENDPOINT is the environment’s world-level MCP server; one BLOBFISH_TWIN_<TWIN>_MCP variable per mounted twin points at that twin’s own MCP server; BLOBFISH_PRODUCTION_FALLBACK=0 is the contract that no call can fall through to the real vendor. The environment also answers at these URLs:

Open the console link (/twin/<env_id>) for the endpoint card, the lease, the call ledger, model runs, and scenario capture. Every MCP call carries your key in X-API-Key; vendor-path REST calls use the same header plus X-Blobfish-Session when you want an isolated fork of the seeded state.

Next steps

1. Twins quickstart — the wizard that wires .env for you, session management, and the full twin table.
2. Local testing — point your SDK or MCP client at the twin, worked Stripe and Slack examples, CI tips.
3. Custom scenarios — seed the exact rows, states, and edge cases your test needs, or describe them in plain language.
4. Models — run the twin with Claude, ChatGPT, Grok, DeepSeek, or your own endpoint, and train an open-weight model on it.
5. Gateway & health — every URL the environment serves and a real health probe.