Connect a client to a fleet

This page covers “connect a client” for every protocol at once: the endpoint and credential model that every fleet shares, whichever client library you use. For language-specific snippets you can copy, go to the Playwright quickstart or the Selenium quickstart.

What you need before connecting

1. A fleet. Create one from the console, the REST API, an AI agent, or Loadrigo. A fleet request lists browsers by count, engine (chrome, firefox, edge), and location. The fleet allocates them and returns endpoints once the first browsers are ready.

2. The fleet id. Every response and the fleet’s Connect tab show it as a flt-… identifier.

3. A credential. Use either the fleet’s own connection token (mpft_…, minted at create time or fetched with GET /v1/fleets/<fleetId>/token) or an account API key (mpak_…) with access to the fleet. Both go in exactly the same place in every protocol below. There is no separate credential format for fleets.

Pick your protocol

A fleet exposes the same set of running browsers through three protocols. Pick the one your existing client speaks. The choice is per session, not per fleet, so different sessions can use different protocols at the same time:

Your client speaks…	Use	Guide
W3C WebDriver (selenium-webdriver, selenium, Appium-style REST)	WebDriver: one URL, the browserName capability picks the engine	Selenium quickstart
Playwright’s connect()	Playwright: one WebSocket URL per engine (chromium/firefox/msedge)	Playwright quickstart
Chrome DevTools Protocol directly, or a Playwright/Puppeteer version you can’t pin to a supported minor	CDP: works with any version, Chromium only	CDP escape hatch

The endpoint shapes

All three use the same host and fleet id. Only the path and scheme differ:

https://app.maxoperf.com/browser-fleets/<fleetId>/wd/hub          # WebDriver
wss://app.maxoperf.com/browser-fleets/<fleetId>/playwright/<engine>   # Playwright — one per engine
wss://app.maxoperf.com/browser-fleets/<fleetId>/cdp               # CDP (Chromium only)

For the Playwright path, <engine> is one of chromium, firefox, or msedge. Staging and local (Tilt) environments use the same path shape on their own app host. Only the hostname changes.

You don’t have to build these URLs by hand. The fleet’s Connect tab in the console lists every endpoint for that fleet, ready to copy, alongside per-client snippets — including the three below.

WebDriver BiDi, Selenium’s se:cdp, and CDP over https

Three more connection shapes ride on top of the endpoints above, all reachable from the same Connect tab:

• WebDriver BiDi — ask for it with the webSocketUrl: true capability. Chrome, Edge and Firefox all support it, and a session only gets a BiDi endpoint back when it asks. The server rewrites the driver’s own webSocketUrl to a public, ticketed wss://…/wd/hub/session/<sid>/se/bidi URL your client connects to directly (driver.getBidi() in selenium-webdriver).
• Selenium se:cdp — Chrome/Edge sessions get a browser-level CDP endpoint automatically in the New Session response (se:cdp + se:cdpVersion capabilities), exactly like Selenium Grid 4. No extra capability needed — read it off driver.getCapabilities() and Selenium’s own DevTools helper (driver.createCDPConnection('page')) attaches to it.
• CDP over https — the same CDP escape hatch as the wss://…/cdp endpoint above, but reachable over plain https://…/cdp too: chromium.connectOverCDP('https://app.maxoperf.com/browser-fleets/<fleetId>/cdp?token=<token>') discovers the WebSocket itself, so you never have to copy a wss:// URL by hand.

Name a session

Give a session a name and it shows up on the fleet’s Sessions tab instead of a bare session id — handy once a fleet has run hundreds of them. One convention per protocol:

Protocol	How to set it
WebDriver	maxoperf:options.name capability (or se:name) in New Session
Playwright / CDP	x-maxoperf-session-name header, or ?name= on the connect URL

Names are trimmed and capped at 120 characters; characters other than letters, digits, spaces, _, ., : and - are dropped, and the reserved rollup labels COMBINED/ALL are ignored (they’d collide with the KPI rollup label), leaving the session unnamed.

Fleet Connect tab: every endpoint above, listed for one fleet. The connection token sits beside them, masked until you reveal it.

Credentials, per protocol

Each transport puts the credential in a different place, but the value (mpft_… token or mpak_… key) works in all of them:

Protocol	Where the credential goes
WebDriver	Basic-auth userinfo in the URL: fleet id as username, token as password
Playwright	?token=<token> query parameter on the WebSocket URL
CDP	?token=<token> query parameter on the WebSocket URL
Raw HTTP against the gateway	Authorization header, or maxoperf:options.token in a WebDriver capability

Under the hood: how a browser joins the fleet

The credential above is what your client presents to open a session. MaxoPerf’s own runners join the fleet a different way. When MaxoPerf provisions a browser for your fleet, that runner authenticates to the gateway with a short-lived JWT scoped to one audience (issued for aud=browser-fleet-runner). Only the platform mints and verifies it. You never see, configure, or rotate this internal join credential. Its only job is to authenticate runner-to-gateway traffic, and it has nothing to do with the mpft_…/mpak_… client token above.

Verify the connection

Once you have an endpoint and a credential, the quickest check is one session that opens a page and reads its title, in whichever client you use. The first code block in the Playwright or Selenium quickstart does this. A successful session appears right away as a live video tile on the fleet’s run in the console.

Inspect a session’s evidence

The fleet’s Sessions tab lists every session across every run the fleet has ever had — server-paginated, newest first — with its browser, protocol, name, capture chips (steps, HAR, console), and state. Expand a row to see that exact session’s evidence: the same video, step timeline, network (HAR), and console viewers the run page uses, seeked to that session’s window on the fleet runner’s recording. Open run on the expanded row takes you to the full run page for deeper analysis. Interaction steps are captured by default (a Capture interaction steps toggle on create and the Configuration tab turns it off — for example, against a strict content-security policy or anti-bot page — from the fleet’s next Start).

Capture coverage is per protocol and browser, not per client: WebDriver and Playwright sessions on Chrome, Edge and Firefox, and CDP sessions on Chrome and Edge (Firefox has no CDP endpoint), are all captured.

Next steps

• Playwright quickstart: projects per engine, version matching, CDP escape hatch.
• Selenium quickstart: Python, Java, JavaScript, and creating a fleet from the REST API.
• Billing & limits: session, idle, and lifetime timeouts, plus the full gateway error reference.