Skip to content

Launch options

The launch options not covered on the other pages: extensions, the Privacy Sandbox and the rest of the list.

More launch options

  • extensions — a list of unpacked-extension directory paths (emits --load-extension + --disable-extensions-except).
  • disablePrivacySandbox / disable_privacy_sandbox — set true to switch off the Privacy Sandbox APIs (Topics, FLEDGE / Protected Audience, Shared Storage, Private Aggregation, Fenced Frames). Off by default since 0.23: the default persona presents as Google Chrome, which ships all of them. Turn it on only when the persona is de-Googled Chromium. WebUSB is not affected.
  • agentTyping / agent_typing — the agent's keystroke cadence (human default / fast / instant). See Agent.
  • tlsProfile — keep the TLS ClientHello coherent with the persona's claimed Chrome version so the network layer follows the UA (not the build's native TLS). Default "match-persona" follows brandVersion; "native" leaves it untouched; "chrome-<major>" pins a major. See Fingerprint flags.
  • platform: "android" — a best-effort mobile persona (touch, coarse pointer, mobile screen/DPR, Mali/Adreno WebGL, phone viewport). On a desktop engine the GPU render stays desktop — pair with the canvas bridge for render coherence.
  • storageQuota, fingerprintProfile, canvasBridge, webrtcIp, acceptLanguage, disableGpuFingerprint, fingerprintNoise — see Fingerprint flags.

Newer options (licensed build)

These need the licensed build (Free with GitHub or Pro). The engine revision each needs is in brackets; on an older engine the SDK skips the 152 r22 ones with a warning, checks the engine for each 154 r32 one and leaves it off when the build lacks it, and the engine ignores the rest.

  • stockRuntime / stock_runtime / StockRuntime (or CLEARCOTE_STOCK_RUNTIME=1) — give Playwright the stock DevTools behaviour back for a debugging run: console and page-error events, page.setContent(), and exposeFunction() after a navigation. Off by default, because pages can observe it; an engine without the switch launches without it and the SDK warns once. Local and Docker launches only. See Events and debugging. [154 r32; SDK 0.41.0]
  • personaEnv / persona_env / PersonaEnv — on by default from SDK 0.41.0. The persona switches (the seed, every persona override, proxy credentials and the canvas-bridge token) reach the browser through its environment instead of its command line, which any local user can read in the process list (/proc/<pid>/cmdline on Linux, the process details on Windows). The engine keeps them off its helper processes' command lines too. false or CLEARCOTE_PERSONA_ENV=0 keeps them on the command line, for example for a tool of yours that reads them there. The Docker image does the same for the container's browser. [154 r32]
  • Persona token — on the licensed Chromium 156 build (r51 and newer) the SDK fetches a signed persona for your seed or profile from the Clearcote persona service at every launch and passes it to the browser along with the switches above. There is no option to turn this off; the browser does not start without it. Needs SDK 0.63.0, Profile Manager 0.27.0 or the matching Docker image. [156 r51; SDK 0.63.0]
  • Light or dark — from 154 r32 the persona decides the colour scheme (about one profile in three prefers dark), and CSS, matchMedia, the Sec-CH-Prefers-Color-Scheme request header and system colours all follow it. Playwright emulates light in every context it creates, which a dark persona would contradict, so from SDK 0.41.0 the contexts a local launch creates leave the colour scheme alone on such a build. Pass colorScheme / color_scheme / ColorScheme to emulate one anyway, or --fingerprint-color-scheme=light|dark in args to make the persona itself light or dark. An older build keeps Playwright's default. [154 r32]
  • allowThirdPartyCookies / allow_third_party_cookies — third-party cookies, allowed by default as in stock Chrome (SDK 0.45.0+); false blocks them. Embedded sign-in, payment and challenge frames rely on them. Builds before 152 r22 always block them. [152 r22]
  • transparentProxy / transparent_proxy — hide the proxy from request headers and connection timing (plain-HTTP requests carry no proxy header; proxied connections report timing like a reused connection). Needs a proxy. [152 r22]
  • fingerprintVoices: false / fingerprint_voices=False — keep this machine's own speech voices instead of the persona's list. [152 r22]
  • fingerprint: "off" — launch with no persona at all, for troubleshooting. [152 r22]
  • socks5Udp / socks5_udp — carry WebRTC's UDP through a socks5:// proxy, so voice, video and peer connections work and still leave from the proxy's address. The proxy must allow it; many residential pools don't. [151 r17]
  • portableProfile / encryptionKey — profiles you can copy between machines (above). [151 r14; Python, Node & .NET (0.58.0+)]
  • personaSchema / persona_schema — which identity model a seed derives. Leave it unset for the current model, 7 (served since 2026-10-26, r52): the graphics card sets the kind of machine (laptop or desktop), its processor, threads, memory and screen, each as common as in real browser traffic. 5 derives exactly what r45 to r51 did, 4 what 154 r37 to 155 r44 did, 3 what 154 r36 did and 2 what 153 r29 to 154 r35 did; set one to keep identities created on those builds. 1 is the original model from before r29. There is no 6. Every SDK accepts 5 and 7 from 0.64.1. See the same seed on different machines. Add realGpuHost / real_gpu_host only on a machine with a real graphics card. [151 r19; Python, Node & .NET]
  • shaderDialect: "hlsl" — on by default for a Windows persona on a Linux or macOS host since SDK 0.39.0; false turns it off. See Shader dialect. [151 r15]
  • profile: "auto" — launch a real captured fingerprint picked for this machine instead of a seed; tune it with profileSelect / profile_select. Python, Node & .NET (LocalProfile = "auto", 0.58.0+). In Node it works with the default launch(), launchPersistentContext() and serve() from SDK 0.31.1; 0.31.0 and older needed ephemeralProfile: false and failed with serve().

Not tied to an engine build:

  • version / releaseChannel — pick a build; see choosing a build.
  • licenseKey / license_key / LicenseKey — the licence key, if it isn't in CLEARCOTE_LICENSE_KEY or ~/.clearcote/license.key.
  • licenseThroughProxy / license_through_proxy (or CLEARCOTE_LICENSE_THROUGH_PROXY=1) — send the licence calls through the launch's proxy instead of from this machine.
  • ephemeralProfile / userDataDir on launch() — see the note under The SDK way above.
  • widevine: true — DRM playback (both builds); see Widevine & DRM.
  • quiet — silence the SDK's launch warnings and progress output.
  • fontDirs / font_dirs / FontDirs — your own fonts on Linux; see below.

Your own fonts on Linux (fontDirs)

On Linux the browser sees only the fonts the SDK points it at: the release's bundle of Windows metric-compatible lookalikes (Arial→Arimo, Segoe UI→Selawik, Times New Roman→Tinos, …). No font installed on the host reaches it, so nothing on the machine can change what a page measures. From SDK 0.41.0 (Python, Node and .NET; launch(), persistent contexts and serve()) two settings add directories:

  • fontDirs / font_dirs / FontDirs, or CLEARCOTE_FONT_DIRS — your own fonts, typically a copy of a Windows machine's C:\Windows\Fonts, listed ahead of the bundle. On the licensed build from 154 r32, every family they provide renders as itself, under its own name, instead of its lookalike, and the names that stand for it on Windows follow: Helvetica, Times and Courier, and the CSS generics (sans-serif → Arial, serif → Times New Roman, monospace → Consolas, system-ui → Segoe UI). An older engine keeps drawing its lookalikes for the families a persona lists, and uses the directories only for characters nothing else covers. A path that is not a directory fails the launch at once, before a licence slot is taken.
  • CLEARCOTE_FALLBACK_FONT_DIRS — fonts used only for characters nothing else covers (CJK, Indic scripts, emoji, …), listed after the bundle. They take no family over. The Docker image sets it to the script fonts it ships.
from clearcote import launch

# a copy of a Windows machine's C:\Windows\Fonts, on the Linux host
browser = launch(fingerprint="acct-1", platform="windows", font_dirs=["/srv/windows-fonts"])
# or: CLEARCOTE_FONT_DIRS=/srv/windows-fonts (several directories: separate them with ":")
  • Both variables are lists separated by :. Family names are read from the font files themselves, so no fontconfig tools are needed. Never point either at all of /usr/share/fonts: the host's Latin families then compete with the bundle and change the widths a Windows persona reports.
  • clearcote info (Python and Node) reports, on Linux, which of 29 writing systems the fonts a launch would see can draw, your font directories, and which of the key Windows families they provide for real.
  • To keep the lookalikes even with your fonts listed, pass --disable-genuine-font-faces in args (154 r32+). The SDK sees it and keeps its own font rules as they are, so the engine and fontconfig agree on every family.
  • Ignored on Windows and macOS, which use their own fonts, and refused for a cloud launch and the macOS Docker launch: in your own container, mount the fonts and set CLEARCOTE_FONT_DIRS there (see Deployment). Only use fonts you are licensed to use.
  • Before 0.41.0 the .NET SDK did not point the browser at the bundle at all, so a .NET launch on Linux used the host's fonts and none of the lookalikes. It now matches Python and Node, which changes what a Windows persona measures there.