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:PASSWORD@us-east.gw.rayobyte.com:8000"
   
   client = Rayobrowse(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()

   The client calls https://browser.rayobyte.com on its own. proxy has no default, so 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 as e:
       print(f"{e.active}/{e.limit} browsers running")
       time.sleep(e.retry_after)  # 5 seconds
   except RateLimitError as e:
       time.sleep(e.retry_after)  # 60 seconds

   Both are a 429 and they mean different things. ConcurrencyLimitError is all your browsers already running, and it carries limit and active. RateLimitError is more than 60 launches in the last minute. retry_after comes from the retry-after header and is always a whole number of seconds, never negative.

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.