humanbrowser

Virix Labs↗|v0.1.0

Stealth cloud browser-agent with residential proxies. You describe what you want in plain English — the server runs an LLM-driven browser on a residential IP and returns a concise answer plus a live viewer URL. Cookies and logins persist across runs automatically (see PERSISTENCE below). === HOW TO USE === minimal call: send a message/send with one TextPart containing your goal. Example: 'Log into adsy.com with the credentials below and report guest-post prices for these 5 domains: ...'. Credentials go in a DataPart with metadata.sensitive=true. The server returns a Task — poll tasks/get OR receive a push on metadata.callback_url. That's it. === WHAT THE SERVER HANDLES FOR YOU (do NOT pass knobs for these) === • CAPTCHA solving (recaptcha v2/v3, hCaptcha, Turnstile, Cloudflare WAF) — automatic via CapSolver + 2captcha race. • Cloudflare challenge bypass — automatic engine selection per site. • Anti-bot fingerprint — automatic stealth profile. • Residential proxy stickiness — automatic per-session sticky IP. • Engine choice (patchright/cloak), execution mode (fast/stealth), LLM model, warmup — automatic from goal + site-rules. • Profile / cookie persistence — automatic from goal domain (see below). You will NOT find these in the message/send metadata schema. If you think you need them you are usually wrong — call without them first; the right setting is picked from your goal text. (For genuine power-user overrides, see ADVANCED at the bottom.) === PERSISTENCE (automatic) === The server canonicalises a profile from the first domain in your goal: 'collaborator.pro' → profile 'collaborator', 'cp.adsy.com' → 'adsy', 'gogetlinks.net' → 'gogetlinks'. The profile lives in YOUR token's isolated namespace (cookies cannot leak to other tokens). On the FIRST goal mentioning a domain, the agent logs in and saves cookies; on subsequent goals mentioning the same domain, login is skipped and the agent lands directly on the authenticated page (typical first-run 3-8 min, cached-run 20-90 sec). Response includes metadata.profile so you can see exactly which profile was chosen. To use a different identity on the same domain (multi-account farms), see ADVANCED. WHAT PERSISTS across tasks on the same profile: HTTP cookies (per-row merged into the profile's master Chromium UserDataDir on every successful task — concurrent logins for the same site coexist without one wiping the others), saved logins, history, and Preferences. WHAT DOES NOT PERSIST across parallel tasks: localStorage, sessionStorage, IndexedDB and Service Worker registrations — these are Chromium LevelDB stores which OS-level forbid concurrent writers, so each task gets its own in-memory copy that is discarded at task end (this is the same restriction every production multi-session browser farm imposes). For COOKIE-based auth (the vast majority of sites — Adsy, GoGetLinks, Collaborator, Reddit, Quora, Twitter, most SaaS dashboards) parallel tasks work seamlessly. For LOCALSTORAGE-bound auth (Discord, Slack, Stripe Dashboard, AWS Console, some chat-app web clients) only ONE task at a time on a given profile retains the auth; resume that single task via referenceTaskIds for follow-up work instead of opening a parallel session. PARALLELISM: send N tasks on the same profile and the server allocates N independent Chromium sessions, each cloned from the warm master profile. Each session lands logged-in (if cookies are warm), reads the data you need, and merges new cookies back on done success. Failed/canceled tasks do NOT pollute master cookies. Concurrency cap per token = 5 by default; over-cap returns a 503 with retry_after_seconds. === VIEWER URL === Every response includes a live viewer URL of the form https://humanbrowser.cloud/a/s_<id>?k=<key>, returned as metadata.viewer_url and as the first artifact. A human can watch live and click through CAPTCHA / consent dialogs / 2FA modals if the agent gets stuck. Surface it to your end-user for interactive sessions or anything that may need human intervention. === HUMAN-IN-THE-LOOP (input-required) === When the agent needs something it can't derive autonomously (OTP code from an email inbox, magic-link URL, a credential you didn't pre-provide), it pauses with state=input-required and final=true. The SSE stream closes per A2A 1.0 spec; the task remains in the registry. Resume by sending a fresh message/send with message.referenceTaskIds=[taskId] and message.metadata.in_reply_to=<req_id>, with the answer as a TextPart or {decline:true,reason} DataPart. Exact resume contract is echoed in the input-required event's data part as `resume_hint`. While paused, a human operator can also answer directly from the viewer modal — first writer wins. Server-side timeout (default 300s, max 1800s) auto-declines. The agent asks ONCE and blocks; decline/timeout is terminal — no spam follow-ups. === MOBILE UA === For mobile-only flows (Instagram webviews, TikTok login, mobile-specific layouts) pass metadata.mobile_ua=true on message/send. Server launches the session with iPhone Safari fingerprint (393x852, touch, userAgentData.mobile=true). Default is desktop Chrome. Fixed at spawn time. === REPORTING CONTRACT — READ BEFORE RELAYING TO YOUR USER === A task is one of: working | submitted | input-required | completed | failed | canceled. ONLY the last four are terminal. While state=working, the task IS still running — do NOT tell your user it failed, do NOT generate a 'probably stuck on CAPTCHA' narrative; poll tasks/get and wait for a terminal state, or use metadata.callback_url for push delivery. Expected wall-clock duration: first-run authenticated tasks on hostile sites (Cloudflare/recaptcha-gated) 3–8 minutes; cached subsequent runs 20–90 seconds. status.message on a working task is a human-readable progress headline like 'Step 12/50 on collaborator.pro — Submit the goodmenproject.com search'. Quote it verbatim to your user; do not paraphrase or interpret. On terminal=failed, tasks/get attaches metadata.postmortem ({root_cause_category, observed_blockers, working_strategies, retry_recommendation}) within ~30 sec — quote those FACTS instead of inventing failure modes. NEVER fabricate that you 'tried mobile UA + DE proxy + warmup' unless you actually passed those params on the request you can prove. === ADVANCED (rarely needed) === Power-user overrides on message/send.metadata: profile=<slug> to pick a non-default profile (multi-account farms, A/B testing); country=<iso2> to force a proxy egress country (geo-blocked sites like BBC iPlayer→uk, Polymarket→jp); callback_url=<https://...> for push delivery of the terminal task envelope instead of polling. Other knobs (mode/engine/model/warmup/proxy) are accepted for backward compatibility but you should not need them — let the server choose.