Options and identities

What you can set when you start a hosted browser: the options, the stealth defaults and identities, profiles that keep you signed in, a pinned release and the start page.

Options

All optional. Send them as the JSON body of the create call.

Stealth defaults and identities

Every session starts from the settings on the recommended settings page: lightStealth on, a seed, and timezone and language that follow the exit IP. With lightStealth (the default) the seed picks the device profile from a small set that varies CPU cores, memory and pixel ratio; canvas, WebGL and audio are those of the machine the session runs on. Set lightStealth: false for a full per-seed persona: canvas and WebGL readbacks get per-site noise from the seed, and the GPU strings, screen and audio settings (sample rate, latency) follow the persona. Without an identity or fingerprint, each session gets a random seed and a new IP.

Pass identity: "account-42" to come back with the same device profile, on the same IP for as long as that residential IP stays online, in later sessions, which is what a logged-in account expects. Identities are private to your account: another customer using the same label gets their own seed and IP. On its own an identity does not keep cookies: for that, use a profile.

Profiles: sign in once

A profile keeps a session's cookies, localStorage and IndexedDB under a name, so the next session on that name starts signed in. Pass profile: { name: "shop-account", persist: true } to load it and save it back when the session ends, or just profile: "shop-account" to load it read-only. The first session on a new name starts empty and creates it.

// Every run: the same body. The first one starts signed out; sign in, then close the browser
// and the session saves the cookies and site storage. Every later run starts signed in.
const res = await fetch("https://www.clearcotelabs.com/api/v1/browsers", {
  method: "POST",
  headers: { authorization: "Bearer cc_live_...", "content-type": "application/json" },
  body: JSON.stringify({ profile: { name: "shop-account", persist: true }, country: "de" }),
});

• Same device, same IP. A profile brings its own identity (profile:<name>), so the site sees the same fingerprint, and the same residential IP while that IP stays online, like a returning customer. Pass identity or fingerprint yourself to choose otherwise, and keep the country the same between runs.
• One writer at a time. Only one running session may save to a profile; a second one with persist: true gets 409 PROFILE_IN_USE. Read-only sessions can run alongside it and see the last saved state.
• Saved when the session ends, whether you close the browser, disconnect, stop it or a limit ends it. If the browser crashed, the previous saved state is kept rather than replaced by a partial one. Session cookies (those without an expiry) are dropped, as a real browser drops them on restart.
• Up to about 3.5 MB compressed. If a site's IndexedDB makes it larger, IndexedDB is left out; cookies and localStorage are still saved.
• Private. A profile is yours alone (another customer's “shop-account” is a different profile), stored encrypted, and only handed to the server running your session. List them with GET /api/v1/browsers/profiles, delete one with DELETE /api/v1/browsers/profiles/<name>, or use the dashboard.

Already signed in somewhere else? Cookie sync copies those cookies into a profile, so the first session starts signed in too.

Pinning a release

Sessions run the current Clearcote release. To run an older one, pass version: the full release ("152.0.7977.82-r21"), just the rebuild ("r21"), a Chromium version or major ("152" picks the newest build of it), or "latest". These are the same releases the SDK's version option downloads, so a hosted session and a local run on the same pin use the same build.

const res = await fetch("https://www.clearcotelabs.com/api/v1/browsers", {
  method: "POST",
  headers: { authorization: "Bearer cc_live_...", "content-type": "application/json" },
  body: JSON.stringify({ identity: "account-1", version: "152.0.7977.82-r21" }),
});
const { connectUrl, engine, warnings } = await res.json();
// engine   -> { version: "152.0.7977.82", revision: "r21", pinned: true }
// warnings -> [ "This session runs 152.0.7977.82-r21, older than the current ... " ]

• Check warnings. An older release does not have what later releases added. Options and fixes that came after it may be missing, or silently ignored instead of rejected, so a setting that works on the current release can quietly do nothing on a pinned one.
• The response's engine always says which release the session runs, pinned or not.
• A release that does not exist is a 400 with code UNKNOWN_VERSION, and the message lists the releases you can pick.
• The first session on a release our servers have not used yet can take up to a minute longer to start while the build is fetched. Later sessions on it start as fast as any other.

Start page and ad blocking

• url opens a page in the first tab before you connect, so it is already loading when your script attaches.
• adblock: true refuses requests to well-known ad, ad-verification and analytics hosts before they are made, so they are never billed. The list is deliberately conservative (tag managers, consent tools, login SDKs and CAPTCHAs are left alone), but a few sites notice missing ads; leave it off where that matters.