Connect

Browsers run on your machines. A worker (the Local API) is the thing that launches them; your automation connects to it over the Chrome DevTools Protocol.

One worker serves one surface, so there is nothing to turn on. A fleet is the same worker replicated behind the cluster-manager load balancer, and you connect to the balancer instead of to a box.

Two ways to start a browser

Both authorize the launch against your plan, apply the profile's browser build and proxy, and hand back the same CDP endpoint.

import puppeteer from "puppeteer-core";

const env = {
  VEIL_KEY: "<organization-api-key>",
  // Launch an existing cloud profile…
  profileId: "<profile-uuid>",
  // …or create one from criteria:
  // spec: { os: "win", browserVersion: 147 },
};

const browser = await puppeteer.connect({
  browserWSEndpoint:
    "wss://connect.example.com/launch?env=" +
    encodeURIComponent(JSON.stringify(env)),
});
const page = await browser.newPage();
await page.goto("https://example.com");

curl -X POST https://worker.example.com/sessions/profile \
  -H "X-API-Key: $WORKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "profileId": "<profile-uuid>" }'

const { data } = await res.json();
const browser = await puppeteer.connect({
  browserWSEndpoint: data.webSocketDebuggerUrl,
});

The CDP URL

Whichever door you came in, webSocketDebuggerUrl is addressed to the worker:

wss://<host>/browsers/<launchId>/devtools/browser/<guid>?ct=<capability>

It resolves from anywhere that can reach the worker, and the ct query parameter is the per-launch capability the /browsers/* routes require — treat it as a secret. Behind the load balancer the path is prefixed with /w/<workerId> so reconnects reach the box holding that browser. A standalone worker that cannot infer its own public address needs VEIL_SERVER_ORIGIN.

Ask the session about itself

The URLs for watching and inspecting a session come back from a single CDP call, so a client never has to construct them:

const client = await page.createCDPSession();
const { vncUrl, devtoolsFrontendUrl } = await client.send("Veil.getBrowserURLs");

The worker answers these itself and passes everything else through to Chromium, so they work from a browser-level or a page-level session. Every URL comes back with this launch's capability already embedded, so either viewer URL is ready to paste into a browser tab.

Reconnect and address one browser

Give a launch a stable referenceId and you can come back to it. The Auth column names the credential each route needs; see Authentication.

Watching a session

/browsers/<id>/view frames the two raw surfaces and puts the session's facts beside them: launch id, worker, profile, operating system, display and idle timeout. It opens on DevTools and switches to VNC when the browser has a pooled display; a headless browser gets DevTools only.

DevTools is served by the browser binary itself and proxied through the worker, so it needs no internet access and always matches the running Chromium. It carries a screencast panel, so it doubles as a way to watch and drive the page. VNC is the wider view: the whole desktop, including native dialogs, extension popups and anything outside the page viewport.

Each headful browser gets its own KasmVNC X server from a pool sized by VEIL_DISPLAY_COUNT, which is therefore also the cap on concurrent headful sessions per worker. Set VEIL_VNC_MODE to viewonly to make streams non-interactive, or off to disable them. Those servers bind to loopback behind HTTP basic auth, and the worker generates that password for itself at boot: the proxy is the only holder, and it is never forwarded to a viewer.

Operators get the same two viewers, fleet-wide and behind console login, on the cluster manager's Live sessions page.

Orchestration

Provision profiles through the cloud API or the dashboard; launch and stop them on workers. Design automation so a session can be retried safely: launch, do one unit of work, stop, move on.

Every launch calls the cloud before spawning. If the cloud is unreachable or the organization is at its concurrency limit the launch is refused — running sessions are never killed. Budget for one cloud round-trip per launch. See Licensing & concurrency.

Next steps

• Authentication — which credential opens what.
• API reference — full request and response shapes.
• CLI — drive profiles and sessions from the terminal.
• SDK — typed clients for both surfaces.
• Errors — the response envelope and error codes.