Quickstart

Five minutes from signup to a provider SDK talking to your own copy of Resend. Every surface runs the same four moves: create an environment, wait for the twin, collect its credential, point your code at it.

Prerequisites

An account on console.twinbay.ai. Email address, no invite code.
Python 3.9+ with pip install resend to run the SDK step.

Console (UI)
CLI
MCP server
API

Open the console

Create an environment

Click Create environment. The first screen asks how it should start: pick a saved scenario, or Choose twins myself.From scratch, select Resend, change the suggested name to checkout-tests, and click Create environment. Tick Save these twins as a scenario to start every later run from it.

Take the URL and the key

The dialog follows each twin while Twinbay builds its container. Once a twin reads Ready, copy its Twin URL, such as https://resend-a1c93f.twinbay.run, then click Reveal API key.Keys stay collectable from the environment’s own page for as long as the twin runs, so one you skipped, closed the tab on, or lost is a click away.

Point the provider SDK at the twin

Change the base URL and the key. Nothing else.

import resend

resend.api_key = "re_twinbay_9f2a..."                 # the credential you collected
resend.api_url = "https://resend-a1c93f.twinbay.run"  # the twin's URL

sent = resend.Emails.send({
    "from": "onboarding@resend.dev",
    "to": "delivered@resend.dev",
    "subject": "Hello from the environment",
    "html": "<strong>It works.</strong>",
})

print(resend.Emails.get(sent["id"]))

Read back what your code sent

Open the environment and switch to Logs for every request your code made: method, path, status and latency. Click one for the full request and response bodies.

Install and sign in

curl -fsSL https://raw.githubusercontent.com/panoratech/twinbay-cli/main/scripts/install.sh | bash
twinbay auth login

auth login prompts for an organization API key, which you mint in the console under API keys, and stores it in your OS keychain. Windows and Go installs are on the CLI page.

Create an environment and wait for the twin

ENVIRONMENT=$(twinbay environments create \
  --name=checkout-tests \
  --twins='[{"twin":"resend"}]' \
  -o json | jq -r '.id')

TWIN=$(twinbay environments retrieve --environment-id="$ENVIRONMENT" -o json | jq -r '.twins[0].id')

BASE_URL=$(twinbay environment-twins retrieve \
  --environment-id="$ENVIRONMENT" --environment-twin-id="$TWIN" \
  --wait-for=ready --timeout=180s -o json | jq -r '.url')

--wait-for=ready holds the answer until the twin serves, so there is nothing to poll. The wait ends after two minutes and answers with whatever state it found, hence the raised --timeout.

Collect the credential

API_KEY=$(twinbay environment-twins collect-credential \
  --environment-id="$ENVIRONMENT" --environment-twin-id="$TWIN" -o json | jq -r '.api_key')

The twin mints a key shaped like the provider’s own. Twinbay hands it over on every call while the twin runs.

Point the provider SDK at the twin

Change the base URL and the key. Nothing else.

import resend

resend.api_key = "re_twinbay_9f2a..."                 # the credential you collected
resend.api_url = "https://resend-a1c93f.twinbay.run"  # the twin's URL

sent = resend.Emails.send({
    "from": "onboarding@resend.dev",
    "to": "delivered@resend.dev",
    "subject": "Hello from the environment",
    "html": "<strong>It works.</strong>",
})

print(resend.Emails.get(sent["id"]))

In a suite, pass the two values you just read instead of pasting them:

TWIN_BASE_URL=$BASE_URL TWIN_API_KEY=$API_KEY pytest

Read back what your code sent

twinbay environment-logs list --environment-id="$ENVIRONMENT" --output-format=table

twinbay environment-logs retrieve fetches one log with the full request and response bodies.

Connect your client

claude mcp add --transport http twinbay https://mcp.twinbay.ai/mcp

The first call opens a browser for sign-in through WorkOS AuthKit, so no API key goes into a config file. Cursor and Claude Desktop configs are on the MCP server page.

Ask for the environment

Create a Twinbay environment named checkout-tests with the resend twin. Wait
until the twin is ready, collect its credential, and tell me the URL and the
key.

The agent works inside the organization you signed in to, and each tool scopes its queries the way an HTTP request does.

Watch which tools it calls

list_twins
create_environment      a name, and either twins or a saved scenario
get_environment_twin    wait_for=ready, then take its url
collect_environment_twin_credential

One habit keeps an agent out of trouble: read a not modelled refusal as the edge of a twin rather than as a bug to work around.

Point the provider SDK at the twin

Change the base URL and the key. Nothing else.

import resend

resend.api_key = "re_twinbay_9f2a..."                 # the credential you collected
resend.api_url = "https://resend-a1c93f.twinbay.run"  # the twin's URL

sent = resend.Emails.send({
    "from": "onboarding@resend.dev",
    "to": "delivered@resend.dev",
    "subject": "Hello from the environment",
    "html": "<strong>It works.</strong>",
})

print(resend.Emails.get(sent["id"]))

Ask the agent to write the URL and the key into your test configuration and run the suite.

Read back what your code sent

list_request_logs returns every request the code under test made, and get_request_log returns one with its bodies, so the agent asserts on traffic instead of on its own summary. advance_environment settles a queued email or moves a workflow forward without waiting.

Mint an API key

Open API keys in the console and create one. The token is readable once, so copy it now.

export TWINBAY_API_KEY="tb_..."

Every request sends it in X-API-Key. A key acts with the role of the member who created it.

Create an environment

Name the twins you want, or send a saved scenario instead of a list.

curl -sX POST https://api.twinbay.ai/environments \
  -H "X-API-Key: $TWINBAY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "checkout-tests",
    "twins": [{ "twin": "resend" }]
  }' | jq

The response is a 202: Twinbay recorded the environment and queued each twin for provisioning. Keep the ids.

export ENVIRONMENT=<environment id>
export TWIN=<twins[0].id>

Wait for the twin to report ready

curl -s "https://api.twinbay.ai/environments/$ENVIRONMENT/twins/$TWIN?wait_for=ready" \
  -H "X-API-Key: $TWINBAY_API_KEY" | jq '{state, url}'

wait_for=ready holds the answer until the twin serves, so there is nothing to poll. The url is the private hostname your code will call, such as https://resend-a1c93f.twinbay.run. The wait itself ends after two minutes and answers with whatever state it found, so send the same request again if state is not ready yet; a twin that never serves comes back failed, with a failure telling you why.

Collect the credential

curl -sX POST \
  https://api.twinbay.ai/environments/$ENVIRONMENT/twins/$TWIN/credential \
  -H "X-API-Key: $TWINBAY_API_KEY" | jq -r .api_key

The twin mints a key shaped like the provider’s own. Twinbay hands it over on every call while the twin runs, so read it wherever your test run needs it.

Point the provider SDK at the twin

Change the base URL and the key. Nothing else.

import resend

resend.api_key = "re_twinbay_9f2a..."                 # the credential you collected
resend.api_url = "https://resend-a1c93f.twinbay.run"  # the twin's URL

sent = resend.Emails.send({
    "from": "onboarding@resend.dev",
    "to": "delivered@resend.dev",
    "subject": "Hello from the environment",
    "html": "<strong>It works.</strong>",
})

print(resend.Emails.get(sent["id"]))

Read back what your code sent

curl -s "https://api.twinbay.ai/environments/$ENVIRONMENT/logs" \
  -H "X-API-Key: $TWINBAY_API_KEY" \
  | jq '.items[] | {method, path, status_code, duration_ms}'

Fetch one log by id for the full request and response bodies.

Advance environment time

Turn a queued email into a delivered or bounced one without waiting.

Edit environment state

Replace a record the provider would never let you write.

Available twins

What Resend and Linear model, and where each stops.

Scenarios

Save an environment definition and start every CI job from it.

Stuck? Write to hi@twinbay.ai.

Getting Started

Concepts

Interfaces

Request a twin

Prerequisites

Next

Advance environment time

Edit environment state

Available twins

Scenarios

​Prerequisites

​Next

Advance environment time

Edit environment state

Available twins

Scenarios

Prerequisites

Next