Profile anatomy

A profile is a JSON document in the profiles/ catalog. It describes a target browser identity across several layers. STATIC resolves the file, materializes seeded choices once per process, and shares the resulting active profile between requests and the local control API.

Read a profile from the outside in

The shipped chrome-windows.json, edge-windows.json, and firefox-windows.json profiles are concrete examples. This shape omits most real values:

{
  "profile_identity": { "family": "chromium-like", "variant": "chrome", "platform": "windows" },
  "extends": ["primitives/windows-tcp.json"],
  "replace": [["User-Agent", "…"]],
  "replaceDynamic": [["Accept", { "default": "…", "text/html": "…" }]],
  "pass": ["Cookie", "Authorization"],
  "fingerprint": { "user_agent": "…", "platform": "Win32" },
  "tls": { "schema_version": 1, "hello_variants": [], "http2": {} },
  "seeded_overlays": { "screen_profiles": [], "hardware_profiles": [] }
}

Section	Reader’s question	Consumer
`profile_identity`	Which family, variant, and presented platform?	Catalog, family checks, JS runtime, packet defaults.
`extends`	Which parent JSON should be merged first?	Profile loader; relative paths and cycle detection.
`remove`, `replace`, `replaceArbitrary`, `replaceDynamic`, `set`, `append`, `pass`	Which HTTP request headers are targeted?	Header stage; `pass` is parsed but the current stage does not actively filter on it.
`fingerprint`	Which values and feature flags should the page runtime use?	Browser-side configuration and coherence validation.
`tls`, including `http2`	Which supported outbound transport behavior is desired?	TLS plan and `wreq` fetcher.
`seeded_overlays`	Which screen, hardware, media-device, or packet variant is chosen?	Materializer before a Flow is processed.

Resolution and selection

The loader recursively discovers JSON profiles, skips non-runtime files such as manifest.json and primitives, resolves extends, and deep-merges parents before applying the child. Seeded overlays are chosen using a startup seed and merged into the materialized profile. That choice stays stable in the running process; a restart may choose another variant. This is not a new random persona per HTTP request.

Proxy startup requires an explicit --profile or configured default profile. The control plane can later select another catalog entry. New Flows read the shared selection; already active Flows retain the profile metadata they captured. Manual operators should use a Chromium-family profile on a Chromium browser and a Firefox-family profile on Firefox. STATIC logs coherence warnings but does not reject every mismatch.

Keep layers coherent

When editing a profile, compare its User-Agent header with fingerprint.user_agent, Client Hints with fingerprint.ua_data, TLS hello variants with browser family, and HTTP/2 settings with the TLS ALPN candidates. A profile value is a target, not a guarantee that the browser, transport library, or packet path can express it.

Follow the same profile into Request headers, TLS, HTTP/2, and JavaScript runtime. See the shipped profiles and ProfileStore implementation.