Twins quickstart

Install and sign in

$ 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 catalog

blobfish login (alias of blobfish twin login) verifies an existing API key or prompts for an email address and mints a key into ~/.blobfish/credentials.json. Creating that credential does not start a subscription; use a key belonging to your signed-in workspace for hosted runs. Account scope is derived from that credential; the client cannot select another account’s project. twin catalog lists every twin with its live mounted status and, when the cluster plane is configured, the admitted provider manifest merged in.

Provision a twin

$ blobfish twin-runs create --twins salesforce --ttl 60 --wait

Hosted creation is asynchronous. --wait reads the run until the backend reports ready, including observed workload health for the Kubernetes runtime. A failed or expired run exits with an error. To choose other twins, use blobfish twin-runs create --twins trolley --ttl 60 --wait or --twins github,slack. To use a shared website-plane world explicitly, add --plane website. Prefer the interactive path? blobfish twin wizard picks twins, provisions, and rewrites your .env with a backup (see What the wizard does and Local testing).

Load the receipt

The CLI writes routing.env and a private.blobfish-twin-run.json receipt. Inspect the returned run ID with blobfish twin-runs inspect and list its actual endpoints with blobfish twin-runs gateway. A hosted Salesforce run provides BLOBFISH_TWIN_SALESFORCE_MCP at /api/v1/twin/environments/tenv_<id>/mcps/salesforce/mcp. For a website-plane environment the routes look like this:

BLOBFISH_TWIN_ENDPOINT=https://blobfish.ai/api/v1/sandbox/worlds/sbx_<world>/mcp
BLOBFISH_TWIN_SALESFORCE_MCP=https://blobfish.ai/api/v1/sandbox/worlds/sbx_<world>/services/salesforce/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

Keep the API key separate from this file. The receipt contains routes, never the credential. Every endpoint of an environment — per-service MCP, vendor-path REST, operations, reset, sessions, activity, CLI — is listed by GET /api/v1/twin/environments/twe_<id>/gateway (blobfish twin-runs gateway twe_<id>).

Connect an MCP client

$ set -a && source routing.env && set +a
$ curl -sS -X POST "$BLOBFISH_TWIN_SALESFORCE_MCP" \
    -H "X-API-Key: $BLOBFISH_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json, text/event-stream" \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Use the per-service URL written by your create command. Hosted runs have isolated provider state; create a separate hosted run when you need an independent baseline. In a website-plane environment, session-less calls use the shared seeded world. To isolate a rollout, create a session (POST /api/v1/sandbox/worlds/sbx_<world>/sessions) and preserve the Mcp-Session-Id it returns on later calls: each session mutates its own copy-on-write database. Calls cannot fall through to production.

Run it with the model you ship on

$ blobfish twin-runs run twe_<id> --model claude-sonnet-5 --prompt "List the open opportunities and close the largest one"
$ blobfish twin-runs run twe_<id> --model grok-4 --api-key-env XAI_API_KEY --prompt "…"
$ blobfish twin-runs run twe_<id> --provider custom --base-url https://vllm.example.com/v1 --api-key-env MY_MODEL_KEY --model my-finetune --prompt "…"

The commands above use the website-plane task runner. Claude, ChatGPT, Grok, DeepSeek, or any OpenAI-compatible endpoint of your own drive the twin’s real tools; every call lands in the ledger and the run record names the model and whose key served it. See Models.

Inspect and manage it

1. Open BLOBFISH_TWIN_CONSOLE_ENDPOINT for endpoints, lease, the call ledger, runs, scenario capture, and the environment graph.
2. Re-seed every service with blobfish twin-runs reset twe_<id>.
3. Extend the serving lease with blobfish twin-runs extend twe_<id> --ttl 60; read the ledger with blobfish twin-runs logs twe_<id>.
4. Terminate serving with blobfish twin-runs delete twe_<id>. The backing world remains protected retained data, but its endpoints stay revoked.
5. Hosted runs: replace the example twe_* IDs with the returned tenv_* ID. The Kubernetes receipt includes the namespace, pinned images, workload identities, and observed health. blobfish twin-runs delete with --wait waits for confirmed termination and namespace removal. A missing runtime or failed provisioning request reports an error; it does not silently switch to the website plane.

What the wizard does

blobfish twin wizard is the interactive form of step 2: it provisions an environment and wires the current project to it. Concretely, in order:

1. Resolves your credential — BLOBFISH_API_KEY, else ~/.blobfish/credentials.json — and exits 2 with a blobfish login hint when neither exists.
2. Picks the twins: --twins github,slack, or, on a terminal, a numbered picker over the catalog entries that are mounted and available on this deployment. Without a terminal, --twins is required.
3. Provisions with POST /api/v1/twin/environments (services, ttl_minutes — default 60 — and an optional --name) under an Idempotency-Key it keeps in a local pending file until the receipt is durable, so a retried timeout cannot allocate a second environment.
4. Waits for ready (polling every 2 s, up to 600 s) and stops with the server’s error on failed, or if the run expires or enters teardown before it becomes ready.
5. Writes routing.env and .blobfish-twin-run.json into --out-dir (default: the current directory).
6. Composes a managed block for --env-file (default ./.env) — BLOBFISH_TWIN_ENV_ID plus every routing.env line between two marker comments — shows it, and asks Apply these changes? [Y/n]. --yes applies without asking; without a terminal and without --yes the file is left untouched.
7. Before the first write to an existing .env, copies it to .env.blobfish-backup. That backup is created once and never overwritten — it stays your pre-wizard original. An existing managed block is replaced in place; otherwise the block is appended.
8. Saves .blobfish-session.json (env_id, world_id, base, services, created_at, expires_at, env_file, env_backup, routing_env) so the session commands below know which environment they manage.
9. Prints the summary — console URL, one MCP URL per twin, expiry, the env file and its backup — and reminds you which files to add to .gitignore.

$ blobfish twin wizard --twins github,slack --ttl 60 --yes

# >>> blobfish twin wizard >>>
BLOBFISH_TWIN_ENV_ID=twe_<id>
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_GITHUB_MCP=https://blobfish.ai/api/v1/sandbox/worlds/sbx_<world>/services/github/mcp
BLOBFISH_TWIN_SLACK_MCP=https://blobfish.ai/api/v1/sandbox/worlds/sbx_<world>/services/slack/mcp
# <<< blobfish twin wizard <<<

Session management

Every session command reads .blobfish-session.json from --out-dir and talks to the base the environment was provisioned on. None of them re-provisions.

Re-run just the .env step

If the managed block was removed by hand, the env file moved, or you simply want routing.env regenerated from the current environment record, blobfish twin wizard env --yes rewrites both without touching the environment itself. It uses the env file recorded in the session (or --env-file), backs it up first if no backup exists yet, and updates the session file.

$ blobfish twin wizard env --yes

Restoring your original .env

The wizard never deletes anything from your .env; it only adds or replaces its own marked block. To go back to exactly what you had before the first wizard run, copy the backup over it — teardown prints this same command with the paths it recorded:

$ cp .env.blobfish-backup .env

.env.blobfish-backup exists only if a .env existed when the wizard first wrote to it. If there was none, the file is entirely the wizard’s: delete it, or remove the block between # >>> blobfish twin wizard >>> and # <<< blobfish twin wizard <<<.

Available twins

Projected from each twin’s own resolved spec, the same way blobfish twin catalog and the Twin reference read it. The --twins value is the service key, which differs from the catalog slug for the Google twins (googlecalendar, not google-calendar); an unknown key answers 422 twin_service_unavailable with the mountable list. Operations are the spec’s declared count; a one- or two-twin environment mounts up to 120 of them per twin.

Next

Local testing · Custom scenarios · Models · Twin reference · Start a twin run