Oya Browser docs
Personas, CAPTCHA and MFA
A persona is one identity: a fingerprint, a cookie jar and a proxy, bound together. How to create one, rotate between personas, solve CAPTCHAs and complete MFA.
Personas
A persona is one identity: a fingerprint, a cookie jar and a proxy, bound together and stable for its life. One persona is one device.
There are two ways to get caught, and they are mirror images of each other:
| Shape | Signal |
|---|---|
| One account seen from many device fingerprints | Textbook bot farm |
| One device fingerprint across many accounts, or 1,000 concurrent sessions | Device farm |
Binding the fingerprint to your API key avoids the first and walks straight into the second. Binding it to each browser avoids the second and walks into the first. So the binding sits at the level that actually corresponds to a device:
persona = fingerprint + cookie jar + proxy # one identity, one device
API key = a group of personas # your fleetA persona's fingerprint is derived from a stored seed, so it is byte-identical across restarts, a returning session looks like a returning device, not a new one.
const p = await oya.personas.create({ name: "acme-ops" });
const browser = await oya.browser.start({ persona: p.id });
await oya.personas.list(); // includes activeBrowsers and maxConcurrent
await oya.personas.remove(p.id);Rotation and concurrency
Rotation means picking a different persona, never giving one persona a new fingerprint. persona: 'auto' selects the least recently used persona that is still under its concurrency cap.
Concurrency is capped per persona, because one laptop cannot be in a thousand places at once. Named personas default to 2 (a phone and a laptop is plausible); the default persona is uncapped so an existing fleet does not break on upgrade. Past the cap you get a clear 429 rather than a silent breach, and activeBrowsers is visible in the dashboard and as a Prometheus metric.
CAPTCHA
await browser.solveCaptcha(); // explicit
oya.browser.start({ captcha: 'auto' }); // solve as they appearDetects reCAPTCHA v2/v3, hCaptcha and Turnstile. Providers that solve natively, Anchor, Browserbase, Steel, Browser Use, are left to do it rather than paying twice and racing their attempt. Everything else goes to your configured solver (CapSolver or 2Captcha).
Returns { solved, method: 'provider' | 'solver' | 'none' }. A failure returns solved: false: a silent no-op that leaves an agent stuck is worse than a clear answer.
MFA
await oya.personas.setMfa(id, { type: 'totp', secret: 'JBSWY3DPEHPK3PXP' });
await oya.personas.setMfa(id, { type: 'email', url: 'https://mail.example/api/latest' });
const r = await browser.completeMfa();
if (!r.completed) open(r.liveViewUrl); // finish it by handTOTP is generated locally (RFC 6238). Email and SMS one-time codes are polled from a relay endpoint you supply, within a bounded window, because the code does not exist yet when the prompt appears. When nothing automated can answer, liveViewUrl is where a person finishes; that is also the only workable answer for push-approval MFA.