Skip to content

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.

The CLI manages impersonate.pro access and downloaded fingerprints. Set IMPERSONATE_API_KEY in your environment, or save it once:

Terminal window
brimp fingerprints config --api-key YOUR_API_KEY
brimp fingerprints update
brimp fingerprints list

Choose a name from the list and export a browser profile:

Terminal window
brimp fingerprints show TARGET_NAME --profile > browser-profile.json
brimp fetch https://example.com --profile browser-profile.json

brimp 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.

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 json
from pathlib import Path
import 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.

Terminal window
brimp profile capture --output browser-profile.json

Open 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:

Terminal window
brimp profile capture --plugin ./my-plugin.js --output browser-profile.json

Export the wrapper and its script for independent hosting:

Terminal window
brimp profile capture --directory capture-kit --no-serve --output browser-profile.json
python3 -m http.server 8766 --bind 127.0.0.1 --directory capture-kit

Visit 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.

Terminal window
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 json
from pathlib import Path
import 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.

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.

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.