Agent quickstart

Paste the prompt below into Claude Code, Cursor, Codex or any coding agent. It builds a working rayobrowse integration, points the browser at browserscan.net, saves a screenshot of the fingerprint result and prints a URL you can open to watch the session live.

The prompt asks you for your API key and proxy string before it runs anything. Step 1 below is where you get both.

The prompt

You are integrating rayobrowse, Rayobyte's cloud stealth Chromium browser.
Work in the current project.

FIRST: ask me for two values and wait for my answer. Do not guess them, do not
read them from the environment, and do not write them into any file you commit.

  1. My rayobrowse API key. It starts with rb_live_ and is 72 characters.
  2. My proxy string, in the form
     http://USERNAME:[email protected]:8000

Both are on one page: app.rayobyte.com -> Browser -> API access.

Then write and run a single script, rayobrowse_demo.py.

1. Install:
     pip install rayobrowse playwright
     playwright install chromium

2. Open a cloud browser with a live view. connect_url takes keyword arguments
   only:

     from rayobrowse import Rayobrowse
     client = Rayobrowse(api_key=API_KEY)          # endpoint defaults correctly
     ws_url = client.connect_url(os="windows", proxy=PROXY, vnc=True)

   A proxy is required on every launch. Without one the call returns 400 with
   PROXY_REQUIRED in the X-Error-Code header.
   Creation takes up to 120 seconds. The SDK already defaults to a 120 second
   timeout. Do not lower it.

3. IMMEDIATELY print client.last_vnc_url, labelled "LIVE VIEW:", and flush
   stdout, before navigating anywhere. That is an ordinary HTTPS page. I open it
   in my own browser and watch the session in real time. Printing it after the
   run defeats the point.
   If it is empty or None, do not print the word None. Say "LIVE VIEW: not
   returned for this session" and carry on. The browser is fine; only the live
   view is missing, and I need to know that plainly.

4. Attach Playwright over CDP and reuse the context that is already open. Do NOT
   call new_context() or new_page() on the browser, and do NOT set a user agent
   or a viewport. Any of those overwrite the session's fingerprint.

     from playwright.sync_api import sync_playwright
     with sync_playwright() as p:
         browser = p.chromium.connect_over_cdp(ws_url)
         context = browser.contexts[0]
         page = context.pages[0] if context.pages else context.new_page()

5. page.goto("https://www.browserscan.net/", wait_until="domcontentloaded",
   timeout=120000), then sleep 20 seconds. The detection panels fill in after
   load and are stable by about 10 seconds.

6. Save page.screenshot(path="browserscan.png", full_page=True).

7. Read the verdict out of the page text and print it:

     import re
     body = page.inner_text("body")
     bot  = re.search(r"Bot Detection:\s*(Yes|No)", body)
     auth = re.search(r"Browser fingerprint authenticity:\s*(\d+%)", body)

8. Print these five lines last, in this order:
     BOT DETECTION: <Yes or No>
     AUTHENTICITY:  <the percentage>
     SCREENSHOT:    <absolute path to browserscan.png>
     LIVE VIEW:     <client.last_vnc_url>
     SESSION:       <client.last_session_id>

9. Keep the browser open for 120 seconds after the screenshot so I can watch it
   in the live view, then call client.close(). Put the close in a finally block
   so a crash never leaves a browser running. client.close() ends the live view
   too, so closing early leaves me nothing to look at.

10. Finally, tell me in plain words what browserscan.net reported: whether it
    flagged the browser as a bot, the authenticity percentage, and any rows it
    marked as mismatched. Quote the page, do not summarise it from memory.

Error codes, so you do not guess:
  400 PROXY_REQUIRED    the proxy was not sent. Send it.
  401                   the key is wrong. Stop and tell me. Do not retry.
  429 CONCURRENCY_LIMIT 5 browsers already running. Close one first.
  429 RATE_LIMIT        honour the retry-after header.
  503 CAPACITY          the pool is busy. Wait, then retry once.

There is no screenshot endpoint in the API. The screenshot comes from Playwright
over the CDP connection above. Do not invent one.

If this project is JavaScript or TypeScript, do the same with
`npm i rayobrowse playwright` and the camelCase equivalents:
new Rayobrowse({apiKey}), await client.connectUrl({os: 'windows', proxy, vnc: true}),
client.vncUrl, client.sessionId, browser.contexts()[0],
await page.screenshot({path: 'browserscan.png', fullPage: true}),
await client.close().

Before you paste it

Get your key and proxy

Sign in to app.rayobyte.com, open Browser, then API access. The key starts with rb_live_ and is 72 characters long.

The same page shows a residential proxy string with a sticky session id already appended. The prompt needs both values.
Paste the prompt

The agent asks for the two values, writes rayobrowse_demo.py, installs the packages and runs it.
Open the live view while it runs

The agent prints LIVE VIEW: before it navigates. Open that URL in a normal browser tab. It is a noVNC page served over HTTPS, so nothing needs installing. You watch browserscan.net load and score the session.

What you get back

Three things:

browserscan.png in the project directory, a full-page screenshot of the fingerprint report.
A live view URL that stays open for two minutes after the screenshot.
The agent’s own reading of the Bot Detection row and the Browser fingerprint authenticity percentage.

Those two rows are the ones to look at. browserscan.net lists every check it ran and subtracts from the authenticity score for each mismatch it finds, naming the mismatch. A stock headless Chromium driven by Playwright reports Bot Detection: Yes and loses points for bot control and WebGL vendor mismatch. Run the same page through rayobrowse and compare the rows it flags.

If it did not work

401 Invalid API key. The gateway returns {"error":"Invalid API key"} for a key it does not recognise and {"error":"Missing API key"} when the header is absent. Re-copy the key from API access. Keys are 72 characters, so a truncated paste is the usual cause.

400 with PROXY_REQUIRED in the X-Error-Code header. The proxy parameter was dropped. Every launch needs one.

The agent reports LIVE VIEW: not returned for this session. The URL comes from the X-VNC-URL response header, which the gateway sets only when the backend that took the session actually returned one. The session itself is fine: the screenshot and the browserscan.net verdict still arrive. Close the session and launch again to get a live view, and make sure vnc=True was passed.

The live view URL does not load. It points at https://sb-NN.browser.rayobyte.com/vnc/... and carries a token tied to that one session. It stops working the moment the session closes, which includes the client.close() at the end of the script. Open it while the script is still in its 120 second hold.

ModuleNotFoundError: No module named 'rayobrowse'. The package is rayobrowse on PyPI and rayobrowse on npm. Nothing is scoped and there is no rayobyte- prefix.

The screenshot is 1280x720 and the fingerprint looks wrong. The script called new_context() or new_page() on the browser instead of reusing browser.contexts[0]. A new context applies Playwright’s default viewport emulation, which makes outerWidth disagree with innerWidth. See Playwright.

Quickstart: the same flow by hand, with curl.
Playwright: the attach rules in full.
Session management: keep-alive, reconnecting and lifetimes.

Was this page helpful?

Agent quickstart

The prompt

Before you paste it

What you get back

If it did not work

Next