Profiles

A profile is a login that belongs to Frankensurf, not to one browser. You sign in once; after that, a read can carry the session through whichever tool gets the page, and signed-in reads climb the same escalation ladder as everything else.

• The session (cookies and local storage) is encrypted on disk. Your agent passes a profile name, never a cookie.
• Each profile covers a list of sites. Its cookies go only to those sites, and a profile read of any other site is refused.
• A profile pins one fingerprint (user agent, locale, timezone, window size), so the site sees the same browser every time.
• Each read saves the refreshed cookies back, so sessions stay current.

Create a profile

1. Sign in once.

   frankensurf profile-login shopping --site example-shop.com

   A Frankensurf browser window opens. Sign in as you normally would (2FA included), then close the window. Frankensurf never types or clicks here.

2. Check it.

   frankensurf profile-list

Usage

Python

page = await web.read("https://www.example-shop.com/orders",
                      policy_overrides={"profile": "shopping"})

CLI

frankensurf read https://www.example-shop.com/orders --profile shopping

MCP

{ "tool": "read", "arguments": { "url": "https://www.example-shop.com/orders", "profile": "shopping" } }

receipt.profile shows the profile, its version and the tool that carried it.

Which tools carry a profile

Sharing	Tools
local (default)	HTTP with the cookies, Chromium, Patchright
hosted	adds Steel, Browserbase, Hyperbrowser, Browserless, Kernel, Anchor

Choose with --sharing hosted on profile-login. hosted puts the session on that service’s servers while it reads. Camoufox is Firefox, so it would contradict a profile’s Chromium fingerprint and doesn’t carry profiles. Scrape APIs don’t carry them either.

When the session expires

A read that lands on a sign-in page fails with AUTH_REQUIRED, and receipt.next_step names the command that fixes it: frankensurf profile-login shopping --site example-shop.com. Signing in again updates the same profile.

Where it’s stored

Profiles are AES-GCM files in ~/.local/share/frankensurf/profiles, readable only by you. The key is FRANKENSURF_PROFILE_KEY (32 random bytes, base64) if you set it, which lets you keep it in a secrets manager such as Infisical; otherwise a key file is created at ~/.config/frankensurf/profile.key with mode 600. Without the key, the profile files are unreadable.

Note

Profiles and identities are separate. An identity reads through your own running Chrome and never moves its session. A profile is Frankensurf’s own copy of a login, so any capable tool can use it. Use an identity when the site must only ever see your real browser.

Commands

Command	Does
profile-login NAME --site SITE [--site ...] [--sharing local|hosted]	Sign in and save, or refresh an existing profile
profile-list	Names, sites, sharing level and cookie counts; never the session
profile-delete NAME	Remove a profile