Capture browser profiles
A browser profile configures values such as user agent, language, screen size, and audio sample rate. Capture a profile from a real browser when you want Brimp to use its measured values, or supply a partial profile to change a few settings. Unspecified settings use defaults.
Capturing a value does not add a missing browser capability. For example, a screen size configures what page scripts read; it does not create a layout engine.
Pro fingerprints
Section titled “Pro fingerprints”The CLI manages impersonate.pro access and downloaded
fingerprints. Set IMPERSONATE_API_KEY in your environment, or save it once:
brimp fingerprints config --api-key YOUR_API_KEYbrimp fingerprints updatebrimp fingerprints listChoose a name from the list and export a browser profile:
brimp fingerprints show TARGET_NAME --profile > browser-profile.jsonbrimp fetch https://example.com --profile browser-profile.jsonbrimp fingerprints show TARGET_NAME prints the raw fingerprint JSON instead.
Updates are explicit and replace fingerprints.json only after all pages download
and validate successfully. Requests never download fingerprints or read the catalog.
An exported profile is self-contained, so it can be deployed without the catalog
or API key.
The CLI shares curl_cffi’s configuration directory: $IMPERSONATE_CONFIG_DIR
when set, otherwise $XDG_CONFIG_HOME/impersonate or ~/.config/impersonate on
Linux/macOS, and %APPDATA%\impersonate on Windows. It uses config.json for the
stored key and fingerprints.json for downloaded targets. IMPERSONATE_API_KEY
overrides the saved key. IMPERSONATE_API_ROOT or update --api-root selects the
API root; the default is https://api.impersonate.pro/v1.
Editable fingerprints in Python
Section titled “Editable fingerprints in Python”brimp.Fingerprint has the same data fields and defaults as curl_cffi’s
Fingerprint, including TLS, HTTP/2, HTTP/3, QUIC and WebSocket settings. Load
raw JSON exported by the CLI, edit it and supply it as a profile:
import jsonfrom pathlib import Pathimport brimp
fingerprint = brimp.Fingerprint(**json.loads(Path("fingerprint.json").read_text()))fingerprint.headers["X-Client"] = "my-agent"with brimp.Session(profile=fingerprint) as session: page = session.get("https://example.com") print(page.status_code)To combine transport settings with a captured browser environment, place the
object at profile["values"]["network"]["fingerprint"]. JSON profiles use a plain
object at the same path; brimp.AsyncSession accepts the same inputs.
An explicit fingerprint takes precedence over network.impersonation and selects
its preferred http_version. Its User-Agent, Accept and Accept-Encoding headers
supply missing profile defaults. Explicit browser identity fields and request
headers take precedence. A transport fingerprint does not capture screen, audio,
WebGL or other browser environment values; use a captured profile for those.
Capture from your browser
Section titled “Capture from your browser”brimp profile capture --output browser-profile.jsonOpen the printed localhost URL in the browser you want to measure. Keep the window at the size you want to capture, then click Capture. The page displays each result and submits the profile to the local command, which validates it against the selected interfaces and saves it. The command exits after a successful save. The page also offers Download profile.
Use --overwrite to replace an existing output. The server binds to 127.0.0.1;
--port 8766 chooses a port and --timeout 5m changes the waiting deadline.
Ctrl-C stops the command. A rejected submission leaves the destination unchanged
and the server available for another attempt.
The default browser plugins participate automatically. Repeated --plugin flags
select a complete set, and --no-plugins selects core only. A JavaScript plugin
file can register its own profile values and capture recipe:
brimp profile capture --plugin ./my-plugin.js --output browser-profile.jsonExport the wrapper and its script for independent hosting:
brimp profile capture --directory capture-kit --no-serve --output browser-profile.jsonpython3 -m http.server 8766 --bind 127.0.0.1 --directory capture-kitVisit http://127.0.0.1:8766, click Capture, then download the profile. An
independently hosted kit does not submit to the CLI. Without --no-serve, the
command both exports the kit and starts its own saving endpoint.
Load and inspect a profile
Section titled “Load and inspect a profile”brimp fetch https://example.com --profile browser-profile.json --eval 'navigator.userAgent'import {readFile} from 'node:fs/promises';import {createSession} from '@brimp/brimp';const profile = JSON.parse(await readFile('browser-profile.json', 'utf8'));const session = await createSession({profile});try { const page = await session.newPage(); console.log(await page.profileReport()); console.log(await page.profileContract());} finally { await session.close();}import jsonfrom pathlib import Pathimport brimp
profile = json.loads(Path('browser-profile.json').read_text())with brimp.Session(profile=profile) as session: page = session.new_page() print(page.profile_report()) print(page.profile_contract())Rust pages expose profile_contract() and profile_report(). All bindings return
the same document keys, including custom plugin names; Python does not rename
keys inside these documents. Contracts include the registered interfaces, their
owners and versions, field defaults/constraints and serialized capture recipes.
Reports include defaultsUsed paths and the supplied capture metadata. These
are host APIs; neither the registry nor a private bridge is exposed to page scripts.
Profiles are partial. Missing object fields use interface defaults; supplied arrays replace the default arrays. Unknown fields, invalid types and scopes for unloaded interfaces are rejected. For example, an audio profile requires the audio plugin to be selected when loading it. A small explicit override is also valid:
{"values":{"audio":{"sample_rate":48000,"max_channel_count":8}}}Native HTTP identity and JavaScript navigator identity use the same resolved core values. Host identity options can override individual identity fields. Plugin options remain explicit runtime configuration and can override their corresponding profile values.
Understand the measurements
Section titled “Understand the measurements”The saved envelope has format: "brimp-profile", version: 1, values, and
capture metadata. Metadata records the tool version, capture time, user agent,
selected plugins, interface recipe versions, result statuses and defaulted paths.
Only successful measurements enter values:
| Status | Meaning |
|---|---|
captured |
A measured value passed the interface’s validation. |
absent |
The browser did not expose the requested value. |
permission-required |
The browser denied access with a permission/security error. |
failed |
The probe threw or returned a value that could not be accepted. |
unavailable |
No page-level measurement exists for this setting. |
Absence is metadata, not an instruction to remove APIs. Runtime compatibility placeholders and plugin selection are independent of capture results. Unmeasured settings use defaults and appear in the load report.
Font capture tests candidate families using text-width comparisons and measures
average advances; it does not enumerate every installed font or reproduce shaping.
Canvas/WebGL/audio capture requires creating those browser objects. Media device
capture does not request microphone or camera permission, so labels may be empty.
HTTP header defaults and TLS impersonation cannot be inferred reliably from page
JavaScript and remain explicitly unmeasured; capturing a browser does not capture
its TLS stack. To avoid pairing a Chromium user agent with a WebKit handshake, the
transport target is derived from the user-agent family when the profile does not set
network.impersonation — Chromium and Edge map to chrome150, Firefox to
firefox147, WebKit to safari270. An explicit value always wins, and it is also
what makes deliberate fingerprint-mismatch experiments possible. Version fidelity is
not implied: the derived target is the nearest available handshake, not the exact
build the user agent names.
Define values in a plugin
Section titled “Define values in a plugin”An installer receives profile alongside global, host and other plugin context.
Use the returned values in the implementation so defaults, overrides and probes
stay together:
({global, profile}) => { const values = profile.values('example', {answer: 42}, { version: 1, fields: {answer: {minimum: 0, integer: true}}, capture: ({read}) => ({answer: read(() => navigator.hardwareConcurrency)}), }); global.exampleAnswer = () => values.answer;}Types are inferred from defaults. Field hints can specify type, nullable,
items, additionalProperties, minimum, maximum, integer, enum and
nonempty. An empty array needs an explicit items hint if its items require
validation. A null default needs a type hint when it represents an optional typed
value. Scope names must be unique across the loaded core and plugins.
Recipes receive {read, readRecord, defaults}. read(() => value) classifies access failures
and rejects values that cannot be represented as JSON; it also accepts an async
getter. An async recipe can await those results. readRecord({key: getter, ...})
collects independent object entries and retains their individual failure statuses.
Asynchronous probe/field waits time out after ten seconds so later interfaces can proceed. Return an object mapping registered
field names to results. Omit settings that cannot be observed in a browser.
Increment version when the meaning of the interface or its recipe changes.
On load, recorded interface owners and versions must match the selected definitions;
a mismatch requests a fresh capture instead of silently interpreting old values.
A recipe must be self-contained: its source is exported without the installer, closed-over variables, host handlers or private bridge. Put required helpers inside the recipe. The exported kit contains capture functions, defaults and validation, not the runtime plugin implementations. A captured value must be serializable; functions, BigInt, undefined members and non-finite numbers are not silently coerced.