Profiles and Proxies

Why Profiles Matter

A default automated browser is easy to spot. It reports a clean, generic fingerprint, it has no history, and if you run ten sessions they all look identical. Sites notice all three of those things.

Profiles fix this by giving each identity a realistic, stable fingerprint drawn from common real-world hardware: a plausible viewport and screen size, a matching user agent and platform, a real GPU vendor and renderer string, a timezone, a locale, and consistent CPU and memory values. The fingerprint is generated once when the profile is created and then reused forever, so the same identity looks like the same machine every visit, which is exactly what a real user looks like.

Sessions run through Playwright with stealth patches applied on top, so the usual automation giveaways in the browser environment are covered before the first page even loads.

What a Profile Stores

Each profile is one JSON file with three parts:

• identity is free-form data about the persona: a name, an email, a company, whatever your automation needs to fill in forms. The bot does not interpret it, it just hands it back to you.
• fingerprint is the browser identity: user agent, viewport, screen, timezone, locale, platform, canvas seed, WebGL vendor and renderer, hardware concurrency, and device memory.
• browser_state is the saved cookies and storage origins, which is what keeps you logged in between runs.

Creating and Updating Profiles

A profile is created the first time you open a session with a new name, and you can also create one up front without launching a browser:

{"command": "create_profile", "name": "researcher", "identity": {"name": "Sam Reyes", "email": "sam@example.com"}}

Read one back with get_profile, which returns the identity, the fingerprint, and whether the profile has saved browser state. Patch fields with update_profile, and list what exists on disk with list_profiles. Full argument details are in the command reference.

Persisting Logins

Log in once by hand, and the profile keeps the session. Open a session with the profile, take control of it in the live viewer, log into the site yourself, then save the state:

{"command": "save_profile", "session_id": "a1b2c3d4"}

That writes the session's cookies and storage into the profile. Every future session on that profile starts already logged in, so your automation never has to handle the login flow, the two-factor prompt, or the CAPTCHA that usually guards it.

Proxy Providers

Proxies are optional. Omit provider on new_session and the session runs direct from your own IP, which is the default and is fine for testing, internal tools, and sites you own.

To route a session through a proxy, drop a provider JSON file into the providers directory and name it in the command:

{
  "host": "proxy.example-provider.com",
  "port": 22225,
  "username": "your-customer-username",
  "password": "your-password",
  "country": "us"
}

{"command": "new_session", "profile": "researcher", "provider": "example-provider"}

The file name is the provider name, so providers/example-provider.json becomes "provider": "example-provider". The format targets residential and ISP proxy services that use username-encoded routing, which most major providers do.

Sticky Sessions and Rotation

When a provider is attached, the bot builds the proxy username with a country tag and a random sticky session token, which tells the provider to keep giving you the same exit IP. That matters: an IP that changes mid-flow, between the login page and the dashboard, looks broken to the site and gets flagged.

The sticky IP is held for 25 minutes. Past that, the bot rotates to a fresh sticky token on the next navigation, because residential IPs are not meant to be held forever and providers expire them anyway. When a rotation happens during a request, the response includes a notice so your code knows the exit IP changed:

{"success": true, "data": {"title": "...", "url": "...", "html": "..."},
 "notice": "Sticky IP rotated during this request"}

You rarely need to act on it. It is there so that if a site suddenly asks you to log in again or shows a location-based interstitial, you know why.

Practical Advice

• One profile per identity, not per run. A profile that visits a site weekly for a year looks far more real than a fresh one every time.
• Match the proxy country to the fingerprint timezone. A US residential IP paired with a European timezone is a contradiction sites look for.
• Keep profile files private. They hold live session cookies and any credentials you put in the identity block, so treat them like secrets and never commit them.
• Do not over-rotate. Constantly changing IPs and fingerprints looks more suspicious than a stable identity behaving normally.