# Twin Browser

> The browser execution layer for LLM agents — a token-efficient browser API that
> turns a goal into deterministic, replayable action.

## The wedge (why Twin exists)

Most browser infrastructure re-runs the LLM on every execution, so cost climbs with
usage. Twin compiles a task once (cold compile), matches re-phrased requests to it
with a semantic dispatch cache, and replays deterministically with zero LLM calls —
so marginal cost trends toward zero the more your agents run. A cross-tenant skill
corpus compounds the savings: a skill compiled once can be safely reused across tenants.

marginal cost -> 0

## How it works

1. DOM -> indexed-state compiler turns a live page into a compact, numerically-indexed
   map of interactive elements (under a token budget) instead of raw HTML.
2. A planner picks actions toward the goal.
3. A successful run compiles into a *skill*.
4. Re-runs hit the semantic dispatch cache and replay deterministically (no LLM).
5. A 2FA wall auto-resolves when a credential is connected — an emailed code from a
   connected inbox, or a texted code from a bring-your-own phone number. Otherwise a
   sign-in run PARKS BY DEFAULT (it never just fails): it returns { status:"paused",
   sessionId } and is resumed out of band via POST /api/v1/runs/:id/resume (or a texted/
   typed code via /live/resume on the streaming path). Pass hitl:false to opt out.
6. Four ways out of a paused run: send a CODE (/runs/:id/resume {code}); send the
   CREDENTIALS as fields (/runs/:id/resume {secrets:{email,password}} — merged into
   the parked browser, redacted from every frame/log, and vaulted for next time);
   DRIVE the page yourself (/runs/:id/input, watching /runs/:id/stream); or hand the
   sign-in to a HUMAN (/connect/sessions → a one-time link they open). Prefer
   {secrets} when YOUR app can collect the credential; use a connect link when the
   password belongs to someone whose credentials you should not hold, or when the
   site blocks automated login outright even with correct credentials.
7. A run that needs a credential you have not stored returns code:"credential_missing"
   with the secret name — store it via /api/v1/secrets, or send the user a connect link.

## If you are an AGENT

Read https://twin-browser.com/agents.md — the operational guide: which call to reach for, how to get a
credential in without it passing through the model, what to do when a run pauses, and
which errors are terminal. Over MCP the same text is the twin://guide resource.
Machine contract: https://twin-browser.com/api/v1/openapi.

## Capabilities (shipped)

semantic dispatch cache · deterministic replay · cross-tenant skill corpus ·
token-efficient DOM state · 2FA auto-fill (emailed + texted codes) ·
sign-in pause+resume by default on a 2FA/approval wall (API + MCP) ·
premium /agent full anti-detection stack (Pro) · real-time live view +
session video (durable storage) · agent/skill library · credential vault ·
proxy support (IPRoyal) · usage-based credit billing with pay-as-you-go auto top-up.

Deep pages (one per capability):
- https://twin-browser.com/capabilities/semantic-cache
- https://twin-browser.com/capabilities/deterministic-replay
- https://twin-browser.com/capabilities/skill-corpus
- https://twin-browser.com/capabilities/dom-state
- https://twin-browser.com/capabilities/hitl-handoff
- https://twin-browser.com/capabilities/live-view
- https://twin-browser.com/capabilities/skill-library
- https://twin-browser.com/capabilities/credential-vault
- https://twin-browser.com/capabilities/proxy
- Overview: https://twin-browser.com/capabilities

## Pricing

Usage-based credits. Free to start; entry plan from $29/mo. LLM cost is metered and
passed through at 1x (transparent rate card at https://twin-browser.com/api/v1/pricing).

## Key URLs

- Home: https://twin-browser.com/
- Product: https://twin-browser.com/product
- Capabilities: https://twin-browser.com/capabilities
- Pricing: https://twin-browser.com/pricing
- REST API: https://twin-browser.com/api
- MCP server: https://twin-browser.com/mcp
- Docs: https://twin-browser.com/docs
- Develop guide: https://twin-browser.com/docs/develop
- MCP setup: https://twin-browser.com/docs/mcp
- Skills: https://twin-browser.com/skills
- Use cases: https://twin-browser.com/use-cases
- Compare: https://twin-browser.com/compare
- Alternatives: https://twin-browser.com/alternatives
- Integrations: https://twin-browser.com/integrations
- Glossary: https://twin-browser.com/glossary
- Guides: https://twin-browser.com/guides
- Why Twin: https://twin-browser.com/why
- How it works: https://twin-browser.com/how-it-works
- FAQ: https://twin-browser.com/faq
- Security: https://twin-browser.com/security
- Blog: https://twin-browser.com/blog
- OpenAPI: https://twin-browser.com/api/v1/openapi
- Sitemap: https://twin-browser.com/sitemap.xml

## REST API (how to call it)

Base: https://twin-browser.com/api/v1
Auth: Bearer API key — header `Authorization: Bearer <YOUR_KEY>`. The tenant is
always derived from the key, never the request body. Every call is authenticated,
metered, and written to an audit log.

Core endpoints:
- POST /api/v1/run             Run a goal synchronously on an authorized target. (~10 credits) Add {"stealth":true,"authorized":true} for the PREMIUM anti-detection stack (Pro/Enterprise plan; per-success surcharge).
- POST /api/v1/agent           DEPRECATED alias for /run with {"stealth":true} — prefer /run. Forces the full anti-detection stack (stealth + human mimicry + sticky residential proxy); same gates (Pro plan + {authorized:true}) now enforced by /run.
- POST /api/v1/dispatch        Semantic cache: match to a compiled skill (hit) or compile + cache (miss).
- POST /api/v1/jobs            Submit a goal as an async background job (202 + job id).
- GET  /api/v1/jobs/:id        Poll an async job; settles credits on first terminal read.
- POST /api/v1/skills          Compile a skill (discover + minimize). (~50 credits)
- GET  /api/v1/skills          List this tenant's compiled skills.
- POST /api/v1/skills/:name/run  Deterministically replay a compiled skill — no LLM. (~1 credit)
- GET  /api/v1/library         Search the cross-tenant shared skill corpus (metadata only). (free)
- POST /api/v1/observe         Serialize a page into indexed DOM state without acting. (~1 credit)
- POST /api/v1/live            Run a goal and stream the live browser view as SSE. (~10 credits)
- POST /api/v1/live/resume     Hand a 2FA code back to a live run waiting on it {token, code}. (not billed)
- POST /api/v1/runs/:id/resume Continue a paused (HITL) run after an out-of-band approval {sessionId}.
- POST /api/v1/runs/:id/input   Drive a paused run's browser by hand {event:{kind:"click",x,y}} — coords are 0..1 viewport fractions. (not billed)
- GET  /api/v1/runs/:id/stream  Watch a paused run's browser live (SSE frames) so you can drive it. (not billed)
- POST /api/v1/connect/sessions Mint a one-time link for a HUMAN to sign in; the session is captured for later runs. (not billed)
- GET  /api/v1/connect/sessions Status of each connect link (pending|active|connected|failed|expired).
- POST /api/v1/tenants          Reseller: create a subtenant + mint its key (needs the tenants:provision scope).
- GET|POST|DELETE /api/v1/email-inbox  Connect an IMAP inbox {host,user,pass} so sign-in runs auto-fill the emailed 2FA code (no HITL pause). (not billed)
- GET  /api/v1/pricing         Public credit rate card (no key required).

Example:

  curl https://twin-browser.com/api/v1/run \
    -H "Authorization: Bearer $TWIN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url":"https://app.example.com","prompt":"export this month invoices","success":"a CSV is downloaded"}'

## MCP server

Twin Browser ships an MCP (Model Context Protocol) server that exposes the browser as
native tools over stdio for Claude Desktop, Claude Code, Cursor, and Cline. Tools
include run_goal, compile_skill, run_skill, search_library, observe_page,
solve_captcha, submit_verification (hand a 2FA code to a waiting run), control_run
(click/type on a paused run's page yourself), and connect_account (get a link your
USER opens to sign in by hand, for sites an agent cannot log into). Setup:
https://twin-browser.com/docs/mcp.

## Integrations

REST API under /api/v1/* (Bearer key) · MCP server · LangChain and AutoGen tool adapters.

## For agents

- This file and https://twin-browser.com/api/v1/openapi are the machine-readable entry points; the
  /api/v1/pricing rate card is public and needs no key.
- Compile a skill once, then prefer /api/v1/dispatch or skills/:name/run for repeats —
  cost per run falls as the same workflow runs more often.
- Authorization model: Twin automates the web where you are authorized (first-party
  sites, operator-approved automation, internal RPA, accessibility, authorized testing).
  The run's target URL is the authorization signal; auth, billing, and audit logging
  run on every call. It is not a CAPTCHA-bypass-for-hire / anti-bot-evasion service.
- Backend: multi-tenant Supabase with default-deny RLS, per-tenant API keys, an audit
  log, and an encrypted credential vault.

## Contact

Start free: https://twin-browser.com/signup