Selenium quickstart

A MaxoPerf fleet speaks the W3C WebDriver protocol, so any Selenium client connects with a one-URL swap: replace your grid’s command_executor / server URL with the fleet’s WebDriver endpoint. Choose the browser with the standard browserName capability (ChromeOptions, FirefoxOptions, EdgeOptions).

Before you start

• A running fleet with at least one chrome, firefox, or edge browser. Create one from the console, an AI agent, or the REST API below.
• The fleet’s connection token (mpft_…) or an account API key (mpak_…).

For the protocol-agnostic version of this page (endpoint shapes, credential positions, and how a fleet’s protocols relate), see Connect a client.

The connection URL

Selenium clients pass credentials as basic auth in the URL — the fleet id is the username and the token is the password:

https://<fleetId>:<token>@app.maxoperf.com/browser-fleets/<fleetId>/wd/hub

Any mpak_… account key with access to the fleet works in the password position too.

Connect

Python

# pip install selenium
from selenium import webdriver
from selenium.webdriver.chrome.options import Options as ChromeOptions

driver = webdriver.Remote(
    command_executor="https://flt-a1b2c3d4e5:mpft_example_token@app.maxoperf.com/browser-fleets/flt-a1b2c3d4e5/wd/hub",
    options=ChromeOptions(),  # or FirefoxOptions() / EdgeOptions()
)
driver.get("https://example.com")
print(driver.title)
driver.quit()

Java

// selenium-java on the classpath
import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.remote.RemoteWebDriver;
import java.net.URL;

URL grid = new URL("https://flt-a1b2c3d4e5:mpft_example_token@app.maxoperf.com/browser-fleets/flt-a1b2c3d4e5/wd/hub");
RemoteWebDriver driver = new RemoteWebDriver(grid, new ChromeOptions());
driver.get("https://example.com");
System.out.println(driver.getTitle());
driver.quit();

JavaScript

// npm i selenium-webdriver
const { Builder } = require('selenium-webdriver');

const driver = await new Builder()
  .usingServer('https://flt-a1b2c3d4e5:mpft_example_token@app.maxoperf.com/browser-fleets/flt-a1b2c3d4e5/wd/hub')
  .forBrowser('chrome') // or 'firefox' / 'MicrosoftEdge'
  .build();

await driver.get('https://example.com');
console.log(await driver.getTitle());
await driver.quit();

Replace flt-a1b2c3d4e5 with your fleet id and mpft_example_token with your token.

Java: send basic-auth preemptively

The JDK HTTP client behind Selenium’s Java RemoteWebDriver does not send basic-auth credentials until the server challenges with 401. The fleet gateway does return a WWW-Authenticate: Basic challenge, so the URL form above works — but some Selenium/HttpClient setups drop the userinfo from the URL. If you hit a 401 loop, send the credentials explicitly as an Authorization: Basic header (base64 of <fleetId>:<token>) via your client’s HTTP layer, or pass the token as the maxoperf:options.token capability instead of URL basic auth.

Pick a browser and options

The browserName capability decides which fleet browser you get. Swap the options object per language:

• chrome — ChromeOptions (Python/Java) or .forBrowser('chrome') (JS)
• firefox — FirefoxOptions or .forBrowser('firefox')
• edge — EdgeOptions or .forBrowser('MicrosoftEdge')

Note

MaxoPerf strips vendor-specific automation capabilities before proxying to the browser, so keep your capabilities to the standard W3C set plus maxoperf:options. WebDriver on chrome and edge captures the full set — video, steps, HAR, and console.

Create a fleet from the REST API

If you’d rather script fleet creation than click through the console, POST /v1/fleets with a JWT or an mpak_… API key. Request browsers by count and location, and optionally set how many browsers pack onto each runner, a lifetime, and an idle timeout:

curl -X POST https://app.maxoperf.com/v1/fleets \
  -H "Authorization: Bearer mpak_example_key" \
  -H "X-Account-Id: acn-1234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "nightly-eu-grid",
    "browsers": [
      { "browser": "chrome", "count": 5, "location": "aws:us-east-1" },
      { "browser": "firefox", "count": 3, "location": "gcp:europe-west1" },
      { "browser": "edge", "count": 2, "location": "aws:us-east-1" }
    ],
    "browsersPerRunner": 5,
    "ttlMinutes": 120,
    "idleTimeoutMinutes": 15
  }'

The 201 response carries the fleet id, the run it created, every endpoint, the connection token (this is the one time it is returned inline — retrieve it later with GET /v1/fleets/<fleetId>/token), and the supported Playwright minors:

{
  "fleetId": "flt-a1b2c3d4e5",
  "runId": "run-9f8e7d6c5b",
  "status": "allocating",
  "endpoints": {
    "webdriver": "https://app.maxoperf.com/browser-fleets/flt-a1b2c3d4e5/wd/hub",
    "playwright": {
      "chromium": "wss://app.maxoperf.com/browser-fleets/flt-a1b2c3d4e5/playwright/chromium",
      "firefox": "wss://app.maxoperf.com/browser-fleets/flt-a1b2c3d4e5/playwright/firefox",
      "msedge": "wss://app.maxoperf.com/browser-fleets/flt-a1b2c3d4e5/playwright/msedge"
    },
    "cdp": "wss://app.maxoperf.com/browser-fleets/flt-a1b2c3d4e5/cdp"
  },
  "token": "mpft_example_token",
  "expiresAt": "2026-07-19T14:00:00Z",
  "supportedPlaywrightVersions": ["1.59", "1.58", "1.57", "1.56"]
}

browsersPerRunner is the fleet analogue of “virtual users per runner” on test create: 1 gives each session a full-screen solo video; higher values pack more browsers per runner with tiled video. It defaults to your plan’s browser policy and is clamped to your tier’s min/max. See Billing & limits.

Troubleshooting

• 401 Unauthorized — bad or missing credentials, or the fleet isn’t yours. In Java, see the preemptive basic-auth note above.
• invalid session id — the session already ended (idle timeout) or never existed. Start a new session.
• session not created after a pause — every browser was busy; the gateway queues new-session requests briefly and returns this W3C error if no slot frees up. Add browsers or lower concurrency.
• 410 Gone — the fleet has ended. Create a new one.