Python quickstart

1. Install

   pip install rayobrowse playwright

   Python 3.10 or newer. Skip playwright install: the browser runs on Rayobyte’s side, so there is no local browser to download.

2. Launch a browser

   from rayobrowse import Rayobrowse
   from playwright.sync_api import sync_playwright
   
   PROXY = "http://USERNAME:[email protected]:8000"
   
   client = Rayobrowse(endpoint="https://browser.rayobyte.com", api_key="rb_live_YOUR_KEY")
   ws_url = client.connect_url(os="windows", proxy=PROXY)
   
   try:
       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()
           page.goto("https://quotes.toscrape.com/")
           print(page.title())  # Quotes to Scrape
   finally:
       client.close()

   endpoint is the gateway you are calling and belongs on every client you build. proxy has no default either. Leaving it out raises BrowserCreateError with status_code 400 and a body that starts A proxy is required for this account.

   client.close() in finally ends the session even when the page load raises. Playwright’s browser.close() only detaches from a browser it did not launch.

3. Watch it run

   ws_url = client.connect_url(os="windows", proxy=PROXY, vnc=True)
   print(f"CDP:  {ws_url}")
   print(f"Live: {client.last_vnc_url}")

4. Handle the limits

   import time
   from rayobrowse import ConcurrencyLimitError, RateLimitError
   
   try:
       ws_url = client.connect_url(os="windows", proxy=PROXY)
   except (ConcurrencyLimitError, RateLimitError) as e:
       time.sleep(e.retry_after)  # 5 s for a full account, 60 s for the rate limit

   A 429, too many running browsers or too many creates in a minute, raises one of these two. Catch both: in 2.2.0 the class does not reliably say which limit was hit. retry_after comes from the retry-after header and is right for either.

client.close() closes the browser from the most recent connect_url() call, or the session id you pass it. Skip it and the session runs until maxLifetime, 7,200 seconds by default, and all of it counts against your browser hours.

Next: Python reference and Limits.