Connect a client to a fleet

This page is the protocol-agnostic version of “connect a client” — the shared endpoint and credential model behind every fleet, regardless of which client library you use. For copy-pasteable, language-specific snippets, jump straight 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 specifies browsers by count, engine (chrome, firefox, edge), and location — the fleet allocates and returns endpoints once the first browsers are ready.

2. The fleet id. Every response and the fleet detail page show it — a flt-… identifier.

3. A credential. 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 slot into the exact same place in every protocol below — there is no separate “fleet-only” credential shape to learn.

Pick your protocol

A fleet exposes the same set of running browsers through three protocols. Pick whichever matches your existing client — you don’t need to pick one for the whole fleet, and different sessions can use different protocols concurrently:

Your client speaks…	Use	Guide
W3C WebDriver (selenium-webdriver, selenium, Appium-style REST)	WebDriver — one URL, 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 — version-agnostic, Chromium only	CDP escape hatch

The endpoint shapes

All three share the same host and fleet id, differing only in path and scheme:

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)

<engine> for the Playwright path is one of chromium, firefox, or msedge. Staging and local (Tilt) environments expose the identical path shape on their env-equivalent app host — only the hostname changes.

Credentials, per protocol

The credential position differs by transport, but the value (mpft_… token or mpak_… key) is interchangeable everywhere:

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 connect a session — it is not the same thing as how MaxoPerf’s own runners join the fleet internally. When MaxoPerf provisions a browser for your fleet, that runner authenticates to the gateway with a short-lived, audience-scoped JWT (issued for aud=browser-fleet-runner) that only the platform mints and verifies. You never see, configure, or need to rotate that internal join credential — it exists purely to keep runner-to-gateway traffic authenticated and is unrelated to the mpft_…/mpak_… client token you use above.

Verify the connection

Once you have an endpoint and a credential, the fastest sanity check is a single “open a page, read the title” session in whichever client you’re using — see the first code block on the Playwright or Selenium quickstart. A successful session shows up immediately as a live video tile on the fleet’s run in the console.

Next steps

• Playwright quickstart — per-engine projects, 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.