turno-browser
Every turno-browser command, with the help text it prints.
turno-browser is the command of the turno-browser package: the identity commands on their own, without turno. Inside turno the same commands run as turno browser <command> (see turno browser); setup, secret and background are turno-browser's alone, and its do goes through the identity's background server instead of mcpd.
turno-browser: a browser your agents use with your accounts. It stays light on your machine, and the
model never sees your passwords.
Usage
turno-browser <command> [flags] manage identities: persistent Chrome profiles
your agents sign in with
turno-browser <command> --help the flags and examples of one command
turno-browser-mcp --identity <id>
the MCP server an agent runs for one identity
(--help)
Identities
list list browser identities and whether they are in use
add create an identity (pinned to this time zone) and print how an
agent uses it
show an identity's settings, session health and who holds it
set change an identity's identity.json (an empty value removes a
setting)
login open the identity's Chrome to sign in by hand once
remove delete an identity, its saved logins and its vault
Connect an agent
setup print the MCP config that gives an agent an identity (Claude Code,
Codex, Cursor...)
Sign-ins and sessions
vault credentials browser_login fills without showing them to the agent
secret store the secrets identity.json names as keychain:<item> (never
printed)
export write an identity's cookies and site storage to a file encrypted
with a passphrase
import replace an identity's session with an export (asks first), or
create it
Flows and recordings
record what an identity records (flows, traces, screenshots); turn it on
or off
flows an identity's saved flows; name one to see its steps, --remove to
delete it
replay run a saved flow on the identity's Chrome, without an agent
traces an identity's recordings (traces, screenshots); --open shows a
trace in the viewer
Watch and take over
live watch the agent in an identity's browser and take the controls
(opens the live view)
pause pause the agent in an identity's browser: its next call waits
until you resume
resume give the browser back to the agent; each waiting call is told what
changed
From the shell
do one action on an identity's browser from the shell: open,
snapshot, click, type, read...
background the background server do starts per identity: status, start, stop
Checks
doctor check Chrome, a test launch and every identity (settings, lock,
sign-in), with fixes
reputation challenges each identity met per site (captcha, verify it's you,
block) and their trend
bench check how each browser engine loads reference test pages and your
URLs (asks first)
Flags of every command
--json machine output, on commands that read
(--json=fields lists the fields)
--dry-run say what a command that writes would do, and do
nothing
--no-input never ask a question (also TURNO_NO_INPUT=1)
--color auto|always|never colors in the output (also NO_COLOR, TURNO_COLOR)
--version the turno-browser version
turno-browser help <command> prints the same as turno-browser <command> --help.turno-browser list
Usage:
turno-browser list [--json] list browser identities and whether they are in
useturno-browser add
Usage:
turno-browser add <id> [--timezone <zone>] [--locale <tag>] [--languages
<tag,...>] [--region <CC>] [--health-url <url> --health-text <text>]
[--dry-run]
create an identity (pinned to this time zone) and print how an agent uses it
Examples:
$ turno-browser add school --languages es-MX,es,enturno-browser show
Usage:
turno-browser show <id> [--json] an identity's settings, session health and
who holds it
Examples:
$ turno-browser show schoolturno-browser set
Usage:
turno-browser set <id> [--timezone <zone>] [--locale <tag>] [--languages
<tag,...>] [--region <CC>] [--health-url <url>] [--health-text <text>]
[--health-selector <css>] [--no-health] [--tabs-max <n>] [--tabs-popups
close|keep] [--tabs-park <duration>] [--tabs-close <duration>] [--no-tabs]
[--background-throttling true|false] [--settle <duration>]
[--block-trackers true|false] [--block-types image,media,font]
[--block-patterns <host|glob>,...] [--no-block] [--cache]
[--cache-max-size <size>] [--no-cache] [--humanize
off|light|full|adaptive] [--sharing session|tabs] [--tab-lock-wait
<duration>] [--tab-lock-release <duration>] [--engine chrome|lightpanda]
[--attach auto|<dir>|<url>] [--record-flows true|false] [--record-traces
true|false] [--record-screenshots true|false] [--record-max-size <size>]
[--no-record] [--act] [--act-sampling true|false] [--act-provider
chat-completions] [--act-endpoint <url>] [--act-model <name>] [--act-key
keychain:<item>] [--act-max-steps <n>] [--act-max-tokens <n>]
[--act-timeout <duration>] [--no-act] [--captcha-provider task-api]
[--captcha-endpoint <url>] [--captcha-key keychain:<item>]
[--captcha-timeout <duration>] [--no-captcha] [--live true|false]
[--live-wait <duration>] [--no-live] [--user-agent coherent]
[--proxy-server <url>] [--proxy-username <name|keychain:item>]
[--proxy-password keychain:<item>] [--no-proxy] [--dry-run] [--json]
change an identity's identity.json (an empty value removes a setting)
Each flag writes one key of identity.json; an empty value (--settle "") removes it, and
--no-health, --no-tabs, --no-block and --no-cache remove a whole group. A flag of a group
changes only its part: the rest of that group stays.
How the host runs this identity's Chrome (read at every Chrome start):
--tabs-max <n> most tabs open at once, 0 for no cap (default 8)
--tabs-popups close|keep close popups the agent did not open (default close)
--tabs-park <duration> park an unused tab on about:blank, "0" never (default 5m)
--tabs-close <duration> close an unused tab, "0" never (default 15m)
--background-throttling <bool> let Chrome slow tabs that are not in front (default false)
--settle <duration> wait after each action for the work it started, "0" to "10s"
--block-trackers <bool> block a built-in list of ad and analytics hosts
--block-types <list> block image, media and font requests (never the page itself)
--block-patterns <list> block host names (and subdomains) or URL globs with *
--cache keep images, fonts, styles and scripts on disk (100MB)
--cache-max-size <size> the cache's size, "1MB" to "10GB"; turns the cache on
--sharing session|tabs "tabs": every agent session at once, each in its own locked
tabs (default "session": one at a time); mcp.toml then needs
exclusive = false for the identity's server
--tab-lock-wait <duration> with tabs: how long a call waits for a tab another session
holds, "0" (fail at once) to "10m" (default 10s)
--tab-lock-release <duration> with tabs: a session without calls lets go of its tabs after
this, "0" (free between calls) to "24h" (default 5m)
Blocking without the cache turns Chrome's own HTTP cache off: use them together.
Input:
--humanize <level> off (default), light (the pointer travels a curve to a point
inside the target, keys typed with human delays), full (plus
overshoot, reading pauses, wheel scrolling) or adaptive
(light, full on a site after a challenge page there)
Which engine runs this identity (all off by default):
--engine lightpanda read mode: Lightpanda instead of Chrome, for reading pages;
needs lightpanda on PATH (turno-browser doctor says how)
--engine camoufox Camoufox (a Firefox build) with its own profile; not
recommended for your own accounts; needs Camoufox and
playwright-core (turno-browser doctor says how); no captcha
solving, and no picture in the live view
--attach auto|<dir>|<url> use the Chrome you have open instead of the identity's own:
"auto" is your default Chrome profile, after you turn on
chrome://inspect/#remote-debugging; Chrome asks you to allow
each connection, and the agent then sees all its windows
What turno-browser records for this identity (all off by default; turno-browser record):
--record-flows <bool> keep every session's actions as a flow (auto-<time>, newest 20)
--record-traces <bool> a Playwright trace of each browser session (turno-browser traces)
--record-screenshots <bool> a screenshot after each action
--record-max-size <size> cap of the traces and screenshots, "10MB" to "10GB" (default 200MB)
Vault sign-ins and passwords never reach a flow, a trace or a screenshot.
Off by default, for your own accounts only (they send page content to a third
party you pick, and many sites' terms forbid them; the server lists their tools from its next start):
--act natural language actions (browser_act, browser_extract,
browser_observe) with your client's model (MCP sampling)
--act-provider chat-completions a model API to use when the client has no sampling, with
--act-endpoint <url> its base URL (https, or http on this machine),
--act-model <name> the model name it expects and
--act-key keychain:<item> its key in the secret store (turno-browser secret set <item>)
--act-sampling <bool> false: never ask the client, always use the provider
--act-max-steps <n> most actions per call, 1 to 30 (default 10)
--act-max-tokens <n> most model tokens per call (default 50000)
--act-timeout <duration> longest call, "10s" to "10m" (default 2m)
--captcha-provider task-api solve captcha widgets (browser_solve_captcha) through a solver
--captcha-endpoint <url> service that speaks the createTask protocol, at this URL,
--captcha-key keychain:<item> with its account key in the secret store
--captcha-timeout <duration> longest wait for a solution (default 3m)
--no-act, --no-captcha turn them off
The live view and take-over (off by default; turno-browser live, pause, resume):
--live <bool> serve a view of the agent's tab on 127.0.0.1 and let you pause
the agent to take the controls (from the next server start)
--live-wait <duration> how long a paused call waits for you, "5s" to "30m" (default 2m)
Network and user agent (all off by default; for your own accounts and sites you may automate):
--user-agent coherent the installed Chrome's own user agent and client hints, with
this identity's languages and time zone, checked at every
launch (a headless Chrome stops saying HeadlessChrome); turno
never takes a typed user agent
--proxy-server <url> send this identity's traffic through a proxy: http://,
https://, socks4:// or socks5://host:port; its operator sees
where you go, and sites see its address
--proxy-username <name> the proxy user name, or keychain:<item>
--proxy-password keychain:<item> the password, only from the secret store (turno-browser secret set <item>)
--no-proxy remove the proxy
Examples:
$ turno-browser set school --health-url https://mail.example.com/ --health-text Inbox
$ turno-browser set school --tabs-max 5 --tabs-popups keep --settle 250ms
$ turno-browser set school --block-trackers true --cache --json
$ turno-browser set school --humanize light
$ turno-browser set school --sharing tabs
$ turno-browser set school --live trueturno-browser login
Usage:
turno-browser login <id> [--url <url>]
open the identity's Chrome to sign in by hand once
Examples:
$ turno-browser login school --url https://example.comturno-browser remove
Usage:
turno-browser remove <id> [--dry-run]
delete an identity, its saved logins and its vault
Examples:
$ turno-browser remove school --dry-runturno-browser setup
Usage:
turno-browser setup <claude-code|codex|cursor|copilot|gemini|json>
[--identity <id>] [--json]
print the MCP config that gives an agent an identity (Claude Code, Codex,
Cursor...)
Prints how a coding agent gets one identity's browser: the command to run, or the block to
paste into its config file. It writes nothing; run or paste it yourself.
Agents:
claude-code a claude mcp add command
codex a [mcp_servers] block for ~/.codex/config.toml, and the codex mcp add command
cursor an mcpServers entry for ~/.cursor/mcp.json
copilot an mcpServers entry for ~/.copilot/mcp-config.json, and the copilot mcp add command
gemini an mcpServers entry for ~/.gemini/settings.json, and the gemini mcp add command
json the generic mcpServers entry other MCP clients read
Without --identity it uses the only identity there is. The agent then starts turno-browser-mcp
for the identity when it needs the browser.turno-browser vault
Usage:
turno-browser vault add <identity> <site> --url <sign-in page> [--url
<url>]... [--username <name>] [--totp] [--dry-run]
store a site's username, password and optional TOTP secret (asked hidden, or
on stdin)
turno-browser vault list <identity> [--json]
the sites in an identity's vault (never the values)
turno-browser vault remove <identity> <site> [--dry-run]
delete a site's credentials
turno-browser vault submit <identity> <confirm|auto> [--dry-run]
let browser_login submit the form (auto) or leave the click to the agent
(confirm, default)
The vault keeps a username, a password and optionally a TOTP secret per site for one
browser identity, only in the secret store (the macOS Keychain or the Linux Secret Service).
The browser_login tool fills them into the site's sign-in page without the agent seeing them,
and only on the origins given with --url. In a terminal the password and the TOTP secret are
asked with hidden prompts; from a pipe, the first line of stdin is the password and, with
--totp, the second line is the TOTP secret (base32, or the otpauth:// URI of the QR code).
Examples:
$ turno-browser vault add work github --url https://github.com/login --username alice --totp
$ printf '%s\n' "$PASSWORD" | turno-browser vault add work mail --url https://mail.example.com --username alice@example.com
$ turno-browser vault list work
$ turno-browser vault list work --json
$ turno-browser vault submit work auto
$ turno-browser vault remove work github --dry-runturno-browser vault add
Usage:
turno-browser vault add <identity> <site> --url <sign-in page> [--url
<url>]... [--username <name>] [--totp] [--dry-run]
store a site's username, password and optional TOTP secret (asked hidden, or
on stdin)
Examples:
$ turno-browser vault add work github --url https://github.com/login --username alice --totpturno-browser vault list
Usage:
turno-browser vault list <identity> [--json]
the sites in an identity's vault (never the values)
Examples:
$ turno-browser vault list work
$ turno-browser vault list work --jsonturno-browser vault remove
Usage:
turno-browser vault remove <identity> <site> [--dry-run]
delete a site's credentials
Examples:
$ turno-browser vault remove work github --dry-runturno-browser vault submit
Usage:
turno-browser vault submit <identity> <confirm|auto> [--dry-run]
let browser_login submit the form (auto) or leave the click to the agent
(confirm, default)
Examples:
$ turno-browser vault submit work autoturno-browser secret
Usage:
turno-browser secret set <item> store a value read from a hidden prompt or
stdin
turno-browser secret has <item> exit 0 when the item exists
turno-browser secret list [--json] every keychain: reference in identity.json
and whether it is stored
turno-browser secret remove <item> delete the item
An identity.json names a secret as "keychain:<item>" (proxy.password, act.key, captcha.key), and
so does a replay parameter (--param password=keychain:<item>). The store is the login Keychain on
macOS and the Secret Service (libsecret's secret-tool) on Linux, the same items turno secret uses.
Values are never printed and never passed as an argument. Sign-in credentials live in the vault
(turno-browser vault).
Examples:
$ printf %s "$PROXY_PASSWORD" | turno-browser secret set proxy-password
$ turno-browser secret has proxy-password
$ turno-browser secret list --json
$ turno-browser secret remove proxy-passwordturno-browser secret set
Usage:
turno-browser secret set <item> store a value read from a hidden prompt or
stdinturno-browser secret has
Usage:
turno-browser secret has <item> exit 0 when the item exists
Examples:
$ turno-browser secret has proxy-passwordturno-browser secret list
Usage:
turno-browser secret list [--json] every keychain: reference in identity.json
and whether it is stored
Examples:
$ turno-browser secret list --jsonturno-browser secret remove
Usage:
turno-browser secret remove <item> delete the item
Examples:
$ turno-browser secret remove proxy-passwordturno-browser export
Usage:
turno-browser export <id> --out <file> [--expires 7d] [--force]
write an identity's cookies and site storage to a file encrypted with a
passphrase
Examples:
$ turno-browser export school --out school.session --expires 2dturno-browser import
Usage:
turno-browser import <file> [--as <id>] [--yes] [--dry-run]
replace an identity's session with an export (asks first), or create it
Examples:
$ turno-browser import school.session --as school-laptopturno-browser record
Usage:
turno-browser record <id> [--flows] [--traces] [--screenshots] [--max-size
<size>] [--off] [--dry-run] [--json]
what an identity records (flows, traces, screenshots); turn it on or off
With no flag, shows what the identity records and where. --flows, --traces and --screenshots
turn those on (the next Chrome start uses them), --off turns everything off; turn one off with
turno-browser set <id> --record-traces false. All are off by default.
flows every session's actions saved as a flow (auto-<time>, newest 20 kept)
traces a Playwright trace of each browser session (turno-browser traces)
screenshots a screenshot after each action
Vault sign-ins never reach a flow, a trace or a screenshot: the trace stops before a fill and
starts again after the page navigates, and a password or one-time code is never saved.
Examples:
$ turno-browser record school --flows --tracesturno-browser flows
Usage:
turno-browser flows <id> [<flow>] [--remove] [--dry-run] [--json]
an identity's saved flows; name one to see its steps, --remove to delete it
Examples:
$ turno-browser flows schoolturno-browser replay
Usage:
turno-browser replay <id> <flow> [--param <name=value>]... [--from <step>]
[--headless] [--json]
run a saved flow on the identity's Chrome, without an agent
Runs the flow through turno-browser-mcp, the same way an agent's browser_replay does. A
sensitive parameter is never a value on the command line: pass --param <name>=keychain:<item>
(store it once with turno-browser secret set <item>), or type it at the hidden prompt. When a step fails,
the report says which locators it tried; --from continues at a later step.
Examples:
$ turno-browser replay school submit-timesheet --param password=keychain:school-passwordturno-browser traces
Usage:
turno-browser traces <id> [<recording>] [--open] [--segment <n>] [--json]
an identity's recordings (traces, screenshots); --open shows a trace in the
viewer
--open serves the trace on 127.0.0.1 with the trace viewer patchright-core ships and opens it
in your default browser; Ctrl-C stops it. A recording has one trace per stretch of activity (a
vault sign-in or the idle limit ends one): --segment picks one, the last by default.
Examples:
$ turno-browser traces school --openturno-browser live
Usage:
turno-browser live <id> [--no-open] [--json]
watch the agent in an identity's browser and take the controls (opens the
live view)
Shows what the agent is doing (paused or not, its tabs) and opens the live view in your
default browser: the agent's tab as a picture, Pause and Resume buttons, and while the agent is
paused, your clicks, keys and scrolls go to the page. The view is served on 127.0.0.1 only; the
link it opens works once. Off by default: turn it on with turno-browser set <id> --live true
(it starts with the next turno-browser-mcp for the identity).
Read mode (Lightpanda) has no pixels, attach mode is your own Chrome, which you already see, and
Camoufox (Firefox) has no Chrome screencast: there the view is off, and pause and resume still work. A page that holds a vault or password
value is never shown until it navigates.
Examples:
$ turno-browser live schoolturno-browser pause
Usage:
turno-browser pause <id> [--json] pause the agent in an identity's browser:
its next call waits until you resume
A call that is running finishes; the next one waits up to the identity's live wait (2m by
default), then fails and tells the agent you still have the browser. A batch or replay stops at its
next step. In a headed Chrome the agent's tab comes to the front. Needs the live view on.
Examples:
$ turno-browser pause schoolturno-browser resume
Usage:
turno-browser resume <id> [--json] give the browser back to the agent; each
waiting call is told what changed
The waiting calls go on. Each starts with a note: how long the pause lasted and what changed
(the current tab's URL and title, tabs opened and closed, your input in the view). When something
changed, a call that does more than read does not run, and the agent gets a fresh snapshot instead.
Examples:
$ turno-browser resume schoolturno-browser do
Usage:
turno-browser do <id> <action> [args] [--session <name>] [--json]
Runs one action on the identity's browser through its background server, a turno-browser-mcp
that serves the identity to the shell (turno-browser background shows it). The first action starts
it; it exits after 15 minutes without a request (TURNO_BROWSER_BACKGROUND_IDLE changes that). While
it runs it alone drives the identity's browser: an agent's turno-browser-mcp for the same identity
answers with an error that names it. With turno installed, turno browser do goes through mcpd
instead.
Actions:
open <url> go to a URL in the session's tab
back go back in the tab's history
snapshot [<ref>] [--depth <n>] the page's accessibility tree with
refs (e12) to act on; <ref> limits it
to one element
read [<ref>] [--max-chars <n>] the visible text of the page or one
element (first 20000 characters;
--max-chars 0 for all)
find <text> elements whose text matches, with
their refs
click <ref> [--double] [--right] click an element
type <ref> <text|-> [--submit] [--slowly]
fill a field (- reads the text from
stdin); --submit presses Enter after
press <key> press a key (Enter, Escape, ArrowDown,
Control+a)
select <ref> <value>... choose options of a select element
hover <ref> move the pointer over an element
wait [--text <t>] [--gone <t>] [--seconds <n>]
wait for text to appear or go, or for
some seconds
screenshot [--out <file.png>] [--full] save a PNG of the tab (default: a file
in the temporary folder) and print its
path
tabs [new [<url>] | select <n> | close <n>]
the browser's tabs (others' marked in
use), or open, pick or close one
login <site> sign in with a vault credential
(turno-browser vault); the value never
reaches the shell
call <tool> [--args <json>] [--arg key=value]...
any tool of the identity's server, in
this session (browser_batch,
browser_fill_form...)
close close the session's tabs (the whole
browser when it serves one session)
and end the session
session which session these commands use, who
owns it and how it ends
end end the session now: its tabs stay
open and free, the browser keeps
running
Refs (e12) come from the last snapshot; take a new one after the page changes.
Session: the commands one agent or one terminal shell runs are one session, so they keep their
tab and their place in the tab locks ("sharing": "tabs") or hold the identity's one-session lease
("sharing": "session"). The session belongs to the process that runs the commands: the coding
agent (each of its shell commands passes through a short-lived shell) or your terminal's shell.
It ends when that process exits, with 'end' or 'close', or when the background server exits.
--session <name> (or TURNO_BROWSER_SESSION) keeps several sessions apart under one owner, for
example two subagents each in its own tab.
Output: url: and title: lines, then what the action returned; errors go to stderr with exit 1.
--snapshot after an action prints the snapshot too; --json prints one object.
--timeout <seconds> (default 120) bounds one action; attach mode can wait for Chrome's consent
dialog.
Examples:
$ turno-browser do school open https://example.com
$ turno-browser do school snapshot
$ turno-browser do school click e12
$ turno-browser do school type e5 'alice@example.com' --submit
$ turno-browser do school read
$ turno-browser do school screenshot --out page.png
$ turno-browser do school endturno-browser background
Usage:
turno-browser background status [<id>] [--json]
which identities have a background server
running
turno-browser background start <id> [--idle <duration>] [--headless]
start an identity's background server
ahead of the first do
turno-browser background stop <id> stop an identity's background server and
its Chrome
The background server of an identity is the turno-browser-mcp that `do` starts to reach the
identity's browser from the shell, on a socket in a folder only you can enter. While it runs it
alone drives the identity's browser: an agent's server for the same identity answers with an
error that names it. It exits after 15 minutes without a request (start --idle, or
TURNO_BROWSER_BACKGROUND_IDLE), and stop closes its Chrome first.
Examples:
$ turno-browser background status
$ turno-browser background start school --idle 30m
$ turno-browser background stop schoolturno-browser background status
Usage:
turno-browser background status [<id>] [--json]
which identities have a background server running
Examples:
$ turno-browser background statusturno-browser background start
Usage:
turno-browser background start <id> [--idle <duration>] [--headless]
start an identity's background server ahead of the first do
Examples:
$ turno-browser background start school --idle 30mturno-browser background stop
Usage:
turno-browser background stop <id> stop an identity's background server and
its Chrome
Examples:
$ turno-browser background stop schoolturno-browser doctor
Usage:
turno-browser doctor [--fix] [--no-launch] [--json]
check Chrome, a test launch and every identity (settings, lock, sign-in),
with fixes
Examples:
$ turno-browser doctor --fixturno-browser reputation
Usage:
turno-browser reputation [<id>] [--json]
challenges each identity met per site (captcha, verify it's you, block) and
their trend
Examples:
$ turno-browser reputation school --jsonturno-browser bench
Usage:
turno-browser bench [--engine <name>]... [--url <url>]... [--only-urls]
[--yes] [--json]
check how each browser engine loads reference test pages and your URLs (asks
first)
Examples:
$ turno-browser bench --only-urls --url https://example.com --yesturno-browser-mcp
The MCP server an agent runs for one identity. turno-browser-mcp --help also lists the Playwright MCP flags it passes on, left out here.
turno-browser-mcp: a browser MCP server that drives your installed Chrome, with one
persistent profile per identity (turno-browser add <id>).
--identity <id> use the identity's saved profile (served one session at a time by
mcpd, unless the identity's "sharing" is "tabs")
--allow-http-identity allow --port or --host together with --identity; the server then
binds to 127.0.0.1 only. Any local process can use that browser.
TURNO_BROWSER_IDLE=15m close Chrome after this long without a tool call (headed too); the
next call opens it again with the same profile. "0" keeps it open.
--idle-timeout <ms> and a --config of your own take precedence.
Tabs (these flags win over the identity's identity.json):
--max-tabs <n> most pages open at once, the least recently used closes past it
(default 8; 0: no cap)
--popups <close|keep> close popups that open while no tool call runs (default close)
--park-after <duration> park a page unused this long on about:blank; it loads again on its
next use (default 5m; 0: never)
--close-after <duration> close a page unused this long (default 15m; 0: never)
--background-throttling let Chrome slow down tabs that are not in front (default off); the
agent's tab is brought to the front before each call
--sharing <session|tabs> "tabs": several agent sessions use the browser at once, each in
its own tabs, which it locks (default "session", one at a time;
mcp.toml then needs exclusive = false for this server)
Input (wins over the identity's identity.json):
--humanize <level> off (default), light, full or adaptive: the pointer travels a curve
to a point inside the target, keys are typed with human delays;
full adds overshoot, reading pauses and wheel scrolling; adaptive is
light, and full on a site that showed a challenge page
Engines (these flags win over the identity's identity.json; all off by default):
--engine lightpanda read mode: Lightpanda instead of Chrome, for reading pages
(navigate, snapshot, find, click a link, evaluate); other tools are
refused. Needs lightpanda on PATH or TURNO_LIGHTPANDA_PATH
--engine camoufox Camoufox (a Firefox build) instead of Chrome, with its own profile;
off by default. Needs Camoufox and
playwright-core (turno-browser doctor says how); never downloaded
--engine chrome the default; turns off an identity's read, Camoufox or attach mode
--attach <target> connect to a Chrome you already have open instead of launching
one: "auto" (your default Chrome profile, after you turn on remote
debugging at chrome://inspect/#remote-debugging), a Chrome user
data dir, or a loopback endpoint. The agent sees every window of
that profile; turno closes only the tabs it opened
Live view (wins over the identity's identity.json; off by default):
--live serve a view of the agent's tab on 127.0.0.1 (turno-browser live
<id> opens it) and let you pause the agent to take the controls
--live-wait <duration> how long a call waits while you have the agent paused (default 2m,
"5s" to "30m"); then it fails and tells the agent you still have it
Background server (for shell use without turno; turno-browser do starts it):
--background serve the identity over MCP streamable HTTP on a Unix socket in a
folder only you can enter (<state>/browser/identities/<id>/background),
or on 127.0.0.1 with a per-server token in a file only you can read
where a socket cannot be used. Writes server.json there while it runs.
Needs --identity; --port and --host do not apply
--background-idle <duration>
exit after this long without a request (default 15m; "0" never);
also TURNO_BROWSER_BACKGROUND_IDLE. Chrome closes first
While the background server of an identity runs, it alone drives the identity's browser: a
stdio server of that identity (an agent's, or mcpd's) answers each call that needs the browser
with an error that names the background server, and the background server does not start while
another process has the identity's Chrome open. Stop it with turno-browser background stop <id>
(or kill <pid>); turno-browser background shows which run.
Examples:
turno-browser-mcp --identity work
turno-browser-mcp --identity work --max-tabs 4 --park-after 2m
turno-browser-mcp --identity work --humanize light
turno-browser-mcp --headless --popups keep
turno-browser-mcp --engine lightpanda
turno-browser-mcp --attach auto
turno-browser-mcp --identity work --live
turno-browser-mcp --identity work --background --background-idle 30m