Quickstart

This page installs Apostate and launches a Windows persona from Python or Node. It needs Python 3.10 or later, or Node 22 or later, on Linux x64, Linux arm64, macOS on Apple silicon or Windows x64.

Install the package

pip install apostate

npm install @heretic-tech/apostate

The package brings Patchright, the driver it launches the browser with. Do not run playwright install. Apostate brings its own browser.

Download the browser

The first launch downloads the browser (about 150 to 200 MB, depending on the host) and checks its SHA-256. To download it now instead:

apostate install

npx apostate install

Both packages share one install in your user cache directory, so installing with one serves the other.

Install the Windows fonts (Linux and macOS hosts)

A Windows persona shows only Windows fonts that are installed on the host. On Linux or macOS, install them once:

apostate fonts install windows

It needs git. On Windows the fonts are already there. Fonts explains what this installs and where.

Launch a persona

from apostate import launch

browser = launch(fingerprint=42, fingerprint_platform="windows")
page = browser.new_page()
page.goto("https://example.com")
print(page.evaluate("""() => ({
    platform: navigator.platform,
    cores: navigator.hardwareConcurrency,
    screen: [screen.width, screen.height, screen.availWidth, screen.availHeight],
})"""))
browser.close()

import { launch } from "@heretic-tech/apostate";

const browser = await launch({ fingerprint: 42, fingerprintPlatform: "windows" });
const page = await browser.newPage();
await page.goto("https://example.com");
console.log(await page.evaluate(() => ({
  platform: navigator.platform,
  cores: navigator.hardwareConcurrency,
  screen: [screen.width, screen.height, screen.availWidth, screen.availHeight],
})));
await browser.close();

On an x86-64 host, seed 42 as a Windows persona is a desktop with a 1920x1080 screen whose taskbar takes 48 pixels. On an ARM host, such as an Apple silicon Mac, it is a laptop with a Qualcomm Adreno GPU and a 1536x864 screen at 125% scaling. ARM hosts explains why. Both outputs are from hosts with 14 cores:

x86-64 host
Apple silicon Mac

{'platform': 'Win32', 'cores': 12, 'screen': [1920, 1080, 1920, 1032]}

{'platform': 'Win32', 'cores': 12, 'screen': [1536, 864, 1536, 816]}

The core count depends on the host, because a persona never claims more cores than the host has. Seed 42 reports 12 on a host with 12 to 19 logical cores and the host’s own count on a host with fewer than 12. On an x86-64 host with 20 or more, it reports 20. The host cap explains why.Before the launch, the package looked up your IP address and gave the persona the timezone and language of its location. Behind a proxy it looks up the proxy’s exit instead.

Read the whole machine

--fingerprint-explain prints every value the seed chose and exits without opening a window:

apostate run -- --fingerprint=42 --fingerprint-platform=windows --fingerprint-explain

x86-64 host
Apple silicon Mac

apostate fingerprint composition

  chromium            155.0.8059.31
  ...
  platform persona    windows
  host platform       linux
  host cores          14
  ...
  seed                42
  seed source         --fingerprint (pinned by flag, identical on any machine)
  reproduce with      --fingerprint=42
  ...

surface                   layer             evidence               value
anchor                    anchor            physical-ground-truth  windows-d3d11-intel-79dfeb5b4f99
os_release                dispersion        physical-ground-truth  windows-11
gpu_identity              dispersion        catalogue-value        d3d11-intel-uhd-graphics-770-4680
webgpu                    anchor            physical-ground-truth  Intel(R) UHD Graphics 770
machine_class             dispersion        catalogue-value        win-sff-desktop
cpu                       dispersion        public-corpus          cores-12
memory                    dispersion        catalogue-value        gib-8
panel                     dispersion        public-corpus          fhd-1080p
...

apostate fingerprint composition

  chromium            155.0.8059.31
  ...
  platform persona    windows
  host platform       macos
  host cores          14
  ...
  seed                42
  seed source         --fingerprint (pinned by flag, identical on any machine)
  reproduce with      --fingerprint=42
  ...

surface                   layer             evidence               value
anchor                    anchor            physical-ground-truth  windows-d3d11-qualcomm-6388f9914f3f
os_release                dispersion        physical-ground-truth  windows-11
gpu_identity              dispersion        physical-ground-truth  d3d11-qualcomm-adreno-x1-85-gpu
webgpu                    anchor            physical-ground-truth  snapdragon-x-elite-crd8380x-chrome-152
machine_class             dispersion        catalogue-value        win-laptop-15
cpu                       dispersion        physical-ground-truth  cores-12
memory                    dispersion        catalogue-value        gib-32
panel                     dispersion        public-corpus          fhd-1080p-125
...

Keep a machine between runs

The same seed gives the same machine on every launch. Across hosts of the same CPU family, only the core count and memory can change. To keep cookies and logins as well, launch a persistent context. The first launch draws a machine and stores its seed in the directory. Every later launch presents the same machine.

from apostate import launch_persistent_context

context = launch_persistent_context("./profiles/shop-account", fingerprint_platform="windows")
page = context.new_page()
page.goto("https://example.com")
context.close()

import { launchPersistentContext } from "@heretic-tech/apostate";

const context = await launchPersistentContext("./profiles/shop-account", { fingerprintPlatform: "windows" });
const page = await context.newPage();
await page.goto("https://example.com");
await context.close();

Seeds and identity covers how long a machine lasts.

Next steps

Proxies

Route through an HTTP or SOCKS5 proxy, with the locale and timezone of its exit.

Linux servers

Run headless or headed on a server with no GPU and no display.

AI agents

Connect Claude Code, Codex or another agent to Apostate.

Examples

Runnable scripts for common jobs, in Python and Node.

Get started

Concepts

Configure

Run in production

Help