Route External WebDriver Sessions Through a Selenium Grid Relay Node

A Selenium Grid relay node makes an external WebDriver service look like managed Grid capacity. Clients keep one Grid endpoint, the Distributor matches their capabilities against relay stereotypes, and the relay forwards the selected session to an upstream service. This is useful for Appium servers, specialist platforms, and provider capacity that cannot run as a normal local Grid node.

The relay is a routing adapter, not a capacity generator. Its advertised slots, health endpoint, stereotype, transport, and upstream concurrency must agree. If Grid advertises more sessions than the service can create, requests pass matching and then fail at the most expensive boundary.

Trace the relayed session route

The official TOML configuration guide defines a [relay] section with an upstream URL, status endpoint, optional HTTP protocol version, and configuration pairs. Grid still owns its Router, queue, Distributor, and Session Map responsibilities; the upstream owns the actual browser or device runtime.

Once creation succeeds, the Session Map lets the Router find the owning Node for later commands. The relay then forwards those WebDriver commands upstream. Clients should not bypass Grid for ordinary commands, because doing so fragments ownership, authentication, logs, and teardown.

Define a relay-only node in TOML

Disable driver detection to avoid accidentally mixing local browser slots with relay slots. Each configuration consists of a quoted maximum-session count followed by a JSON stereotype. The example uses private custom capabilities with a vendor prefix so clients can select an upstream pool intentionally.

[node]
detect-drivers = false

[relay]
url = "https://webdriver.internal.example/wd/hub"
status-endpoint = "/status"
protocol-version = "HTTP/1.1"
configs = [
  "3", "{\"browserName\": \"safari\", \"platformName\": \"macOS\", \"example:pool\": \"desktop\"}",
  "2", "{\"browserName\": \"chrome\", \"platformName\": \"android\", \"example:pool\": \"mobile\"}"
]

The numbers are examples only. Set them no higher than the upstream service can accept for each configuration after accounting for other clients and provider quotas. If two stereotypes share the same physical pool, their individual maxima cannot be treated as independent capacity without an upstream admission control.

The protocol-version option applies to the HTTP client behavior used for service status communication. Set it only when the upstream or intermediary requires a specific version; otherwise avoid adding a constraint without evidence.

Design stereotypes as scheduling contracts

A stereotype is not documentation. It participates in capability matching. Every required custom value narrows the requests Grid can route to that slot. Browser name, platform name, browser version, and namespaced extensions must describe what the upstream will actually accept and return.

Prefer the smallest discriminator that separates genuinely different services. A custom example:pool field is useful when desktop and mobile endpoints need distinct routing even if other capabilities overlap. The prefix must be one your organization owns; unprefixed non-standard capabilities violate the WebDriver capability model.

Avoid putting test metadata such as build id or case name into the stereotype. Those values can remain request capabilities accepted by the upstream, but making them part of slot identity would require every client to match a constantly changing value.

Send a request that matches the relay

The client talks to Grid, not to the external URL. Its requested capabilities must include the values needed by the relay stereotype and any upstream-specific options. This raw new-session payload makes the matching boundary visible.

{
  "capabilities": {
    "alwaysMatch": {
      "browserName": "safari",
      "platformName": "macOS",
      "example:pool": "desktop",
      "se:name": "relay-account-settings"
    },
    "firstMatch": [{}]
  }
}

Do not copy the entire stereotype into every test by hand. Centralize approved options in a fixture or builder, but log the sanitized serialized request on session-creation failure. The response capabilities are authoritative evidence of what the upstream created.

If several relay configurations are acceptable, create deterministic matrix sessions when coverage requires all of them. firstMatch alternatives request one acceptable session, not one session per candidate.

Make health mean upstream readiness

The relay status-endpoint lets Grid check the external service, and the documented expectation is an HTTP 200 response. Confirm the final URL produced by the configured base URL and status path against the upstream service. Reverse proxies and legacy /wd/hub paths can otherwise make session creation reachable while status checks hit a different route.

A shallow status response may prove only that a process is listening. Add an independent synthetic session probe at an interval the upstream can afford if operations need end-to-end readiness. Keep that probe outside normal Grid capacity or give it a reserved policy so monitoring does not exhaust the very slots it observes.

Distinguish node registration, relay health, and session creation. A registered relay node can later lose upstream connectivity. A healthy status endpoint can still reject a particular capability. A created session can fail during browser commands. Alert messages should name the boundary that failed.

Protect the external transport and credentials

Place the upstream endpoint on a restricted network path and use TLS with verified certificates. A relay centralizes access but does not automatically make an externally reachable Grid or WebDriver service safe. Firewall Grid user-facing routes, relay-to-upstream routes, and internal component ports according to their separate trust boundaries.

Do not commit provider tokens in TOML or embed them in URLs that appear in process listings and logs. Use the upstream's supported secret-delivery method, a protected intermediary, or deployment-time credential injection. Redact authorization headers and namespaced capability values before preserving requests.

Basic authentication on Grid protects client entry but is separate from upstream authentication. Node registration secrets protect Grid component registration and are separate again. Document all three identities so rotating one does not unexpectedly break another path.

Align advertised and actual capacity

Relay slot counts should reflect enforceable upstream concurrency, not a marketing quota or theoretical device count. Measure session-start latency and rejection behavior under realistic parallel creation. If the provider queues internally, Grid may see slots as occupied while the browser does not yet exist, so dashboards need both Grid and upstream timing.

When multiple Grid relay nodes point to the same service, coordinate their totals. Five slots on each of three relays are fifteen advertised opportunities even if the upstream accepts only five. The same concern applies when direct clients use the provider outside Grid.

Draining a relay node should stop new assignment while existing sessions complete. Coordinate maintenance with the upstream so sessions are not terminated behind Grid's Session Map. Confirm that DELETE /session/{id} reaches the external service and releases its capacity.

Diagnose relay failures in routing order

An unsupported-capability or queue timeout begins with the request and stereotype set. Compare names, types, casing, extension prefixes, and free slots. A relay marked unavailable begins with registration logs, status URL resolution, DNS, TLS, protocol compatibility, and the upstream health response.

If forwarding reaches the service but new-session creation fails, inspect the upstream response and its browser or device logs. Common categories include exhausted provider capacity, unavailable platform, malformed vendor options, and authentication rejection. Increasing the Grid session queue timeout does not make an impossible upstream capability valid.

If later commands fail, retain Grid session id, upstream session id when exposed safely, node id, request path, response status, and timestamps. A failed quit deserves explicit cleanup handling because the Grid slot and upstream resource may disagree about whether the session ended.

Choose relay when one Grid endpoint adds value

Relay nodes simplify client configuration, centralized matching, and a combined Grid view across local and external capacity. They also add another proxy hop and require careful health and capacity modeling. Direct provider sessions may be simpler when no local Grid capacity is involved and the provider already supplies the required routing, observability, and access controls.

Use relay for a deliberate control-plane benefit, not merely to hide an endpoint string. The team operating Grid becomes responsible for diagnosing both sides of the boundary.

Relay deployment checklist

• Disable local driver detection on a relay-only node.
• Configure the exact upstream WebDriver base URL and tested status path.
• Advertise only stereotypes the upstream can create.
• Prefix every non-standard capability with an owned namespace.
• Keep relay slot totals within shared upstream concurrency.
• Send clients to Grid and preserve returned capabilities.
• Separate Grid client auth, node registration trust, and upstream credentials.
• Verify TLS, DNS, proxies, and HTTP status behavior from the relay host.
• Monitor registration, health, creation, commands, and teardown independently.
• Drain relays before upstream maintenance.
• Reconcile leaked sessions when Grid and upstream teardown disagree.

Route only what you can account for

A relay is dependable when every advertised slot maps to real upstream capacity, every request can be explained by its stereotype, and every failure can be placed before or after the forwarding boundary. Keep the contract small, the transport protected, and teardown observable. Then Grid can extend to external platforms without disguising where sessions actually run.