Skip to Content

DocsConcepts

Browser identities

A browser identity is one persistent Chrome profile that an agent drives, with settings that stay the same between sessions.

View source

This page explains what a browser identity is and what turno keeps the same about it from one session to the next. To set one up, follow the guide.

One identity, one Chrome profile

turno-browser drives the Google Chrome you have installed, headed, with a persistent user data folder per identity and no injected scripts. You sign into a site once by hand; the cookies stay in that identity's profile, and the agent works there afterwards.

turno identity add browser:school     # an identity and its mcp.toml entry
turno identity login browser:school   # sign in by hand once; cookies persist
turno identity list

Identities live under ~/.local/share/turno/browser/. They hold live cookies of the sites you signed into: treat that folder as credentials.

Settings that do not change

Each identity keeps an identity.json next to its profile with what should stay the same between sessions: time zone, languages, locale and region.

turno identity add browser:school --languages es-ES,es,en          # pinned to this time zone
turno identity set browser:school --timezone Europe/Madrid
turno identity show browser:school

They are applied at every Chrome start: languages go to Chrome's own --accept-lang, the locale to --lang, and the time zone is emulated only when it differs from the machine's. An identity without the file uses Chrome's defaults.

One Chrome per identity

While a server drives an identity's Chrome it holds a runtime lock. A second session on the same identity gets an error that names the process holding it and how to stop it, instead of Chrome's "Browser is already in use". That is also why an identity is declared as a shared, exclusive server (Scopes).

Lifecycle

WhenWhat happens
15 minutes without a tool callChrome closes; it opens again with the same profile on the next call (TURNO_BROWSER_IDLE changes it, "0" keeps it open)
The server sits idle for idlemcpd stops the server, sooner under memory pressure
mcpd stops the serverit closes the server's stdin and waits 5 seconds before SIGTERM, so Chrome closes and writes its profile on its own
A server was killed and left Chrome openthat Chrome is closed the next time the identity starts

Tabs

While the agent works, turno keeps the identity's Chrome from piling up pages:

WhatDefaultWhy
At most max pages open8past it, the least recently used page closes (never the agent's current tab)
Popups that open while no tool call runsclosedpop-unders and ads; a window the agent's own click opened stays
A page unused for park5 minutesit goes to about:blank and stops running; it loads its page again when the agent uses it
A page unused for close15 minutesit closes

Change them in identity.json (format 2), with turno identity set, or with the server's flags, which win over the file:

{
  "version": 2,
  "tabs": { "max": 4, "popups": "keep", "park": "2m", "close": "0" }
}
turno identity set browser:school --tabs-max 4 --tabs-popups keep --tabs-park 2m --tabs-close 0
turno-browser-mcp --identity school --max-tabs 4 --popups keep --park-after 2m --close-after 0

An empty value removes one key (--tabs-park "") and --no-tabs the whole group; --dry-run --json shows the file set would write without writing it.

"0" turns a stage off and max: 0 removes the cap. What turno closed or parked is listed at the end of the next tool result. Tabs in the background run at full speed, as Playwright launches Chrome; "backgroundThrottling": true (turno identity set browser:school --background-throttling true, or the server's --background-throttling) lets Chrome slow them down and brings the agent's tab to the front before each call. It suits a headless browser or a window left in view: a covered headed window stops rendering. See ADR 0048.

Actions

turno adds browser_batch to the browser tools: it runs several actions (browser_type, browser_click, browser_select_option, ...) in order in one call, stops at the first one that fails, and returns one line per action plus, when asked, one snapshot at the end. A form filled in one call costs the agent one round trip instead of one per field.

When a click or a type fails because of the page, the error says why: the element that covers the target (a cookie banner, a dialog) with its buttons, or that the target is hidden or disabled, and the next step. Playwright waits 500 ms after each action for the work it started; "settle": "100ms" in identity.json (turno identity set browser:school --settle 100ms) shortens that wait (Playwright's own --timeout-settle wins over it). See ADR 0051.

Blocking and the resource cache

Both are off until identity.json asks for them, per identity:

{
  "version": 2,
  "block": { "trackers": true, "types": ["image", "font"], "patterns": ["ads.example", "*/promo/*"] },
  "cache": { "maxSize": "100MB" }
}
turno identity set browser:school --block-trackers true --block-types image,font \
  --block-patterns 'ads.example,*/promo/*' --cache-max-size 100MB
turno identity set browser:school --no-block --no-cache   # both off again

trackers blocks a short built-in list of ad and analytics hosts; types takes image, media and font; a pattern is a host name (with its subdomains) or a URL with *. The page itself is never blocked. The cache keeps images, fonts, stylesheets and scripts on disk for this identity only, as long as their Cache-Control allows, and never a response with Set-Cookie or a request with Authorization. Requests still go out through Chrome. Turn the cache on with blocking: blocking turns Chrome's own cache off. See ADR 0052.

Credential vault

An identity can keep a username, a password and a TOTP secret per site, only in the OS secret store (the macOS Keychain or the Linux Secret Service):

turno browser vault add school mail --url https://mail.example.com/login --username alice --totp
turno browser vault list school

The password and the TOTP secret are asked with hidden prompts (or read from stdin). An agent then calls browser_login with the site name on that sign-in page: the tool fills the username, the password and the current one-time code without the agent seeing them, only on the origins given with --url, and hides the values from every later result. It does not submit the form unless you run turno browser vault submit school auto. See ADR 0054 and the threat model in SECURITY.md.

Moving a session

turno browser export school --out school.session --expires 2d
turno browser import school.session --as school-laptop

The export holds the identity's cookies, localStorage and IndexedDB, encrypted with a passphrase you type (asked twice, or the first line of stdin), and is refused after its expiry (7 days by default, at most 90). It never holds vault credentials. Importing into an identity that exists replaces its session, so turno asks first (or needs --yes). See ADR 0055.

By default Chrome encrypts an identity's cookies with a fixed key that is the same on every machine, so the profile folder is as sensitive as the sessions in it. "keychain": "system" in identity.json makes Chrome use the macOS Keychain or the Linux Secret Service instead. Changing it signs the identity out (its cookies were encrypted with the other key): export first and import after. See ADR 0059.

Session health

An optional health check names a page and what it shows only when signed in:

turno identity set browser:school --health-url https://mail.example.com/ --health-text Inbox

When Chrome starts (at most every 30 minutes while it passes) turno checks it. If the proof is missing, the identity is NEEDS_AUTH: tool calls fail with a message that asks you to run turno browser login <id>.

Reputation log

Each captcha, "verify it's you" or block page the identity meets is one line in its state folder, with the site's host name only: no path, no page content.

turno browser reputation school    # counts per site, and whether they go up or down

Doctor

turno browser doctor          # Chrome and its version, a test launch, and each identity's settings, lock and sign-in
turno browser doctor --fix    # clears stale locks and a Chrome left running with no server

Each finding has its own page under Troubleshooting.

Acceptable use

Use it with your own accounts, on sites whose terms allow automated access by you, and at a human pace. Do not use it to get around access controls, paywalls, CAPTCHAs or rate limits, to scrape at scale, or to access accounts that are not yours. How you use the browser on third-party sites is between you and each site's terms.

On this page