# turno-browser (/docs/reference/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](/docs/reference/cli/browser)); `setup`, `secret` and `background` are turno-browser's alone, and its `do` goes through the identity's background server instead of mcpd.

```text title="turno-browser --help"
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 [#turno-browser-list]

```text
Usage:
  turno-browser list [--json]  list browser identities and whether they are in
                               use
```

## turno-browser add [#turno-browser-add]

```text
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,en
```

## turno-browser show [#turno-browser-show]

```text
Usage:
  turno-browser show <id> [--json]  an identity's settings, session health and
                                    who holds it

Examples:
  $ turno-browser show school
```

## turno-browser set [#turno-browser-set]

```text
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 true
```

## turno-browser login [#turno-browser-login]

```text
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.com
```

## turno-browser remove [#turno-browser-remove]

```text
Usage:
  turno-browser remove <id> [--dry-run]
    delete an identity, its saved logins and its vault

Examples:
  $ turno-browser remove school --dry-run
```

## turno-browser setup [#turno-browser-setup]

```text
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 [#turno-browser-vault]

```text
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-run
```

### turno-browser vault add [#turno-browser-vault-add]

```text
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 --totp
```

### turno-browser vault list [#turno-browser-vault-list]

```text
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 --json
```

### turno-browser vault remove [#turno-browser-vault-remove]

```text
Usage:
  turno-browser vault remove <identity> <site> [--dry-run]
    delete a site's credentials

Examples:
  $ turno-browser vault remove work github --dry-run
```

### turno-browser vault submit [#turno-browser-vault-submit]

```text
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 auto
```

## turno-browser secret [#turno-browser-secret]

```text
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-password
```

### turno-browser secret set [#turno-browser-secret-set]

```text
Usage:
  turno-browser secret set <item>  store a value read from a hidden prompt or
                                   stdin
```

### turno-browser secret has [#turno-browser-secret-has]

```text
Usage:
  turno-browser secret has <item>  exit 0 when the item exists

Examples:
  $ turno-browser secret has proxy-password
```

### turno-browser secret list [#turno-browser-secret-list]

```text
Usage:
  turno-browser secret list [--json]  every keychain: reference in identity.json
                                      and whether it is stored

Examples:
  $ turno-browser secret list --json
```

### turno-browser secret remove [#turno-browser-secret-remove]

```text
Usage:
  turno-browser secret remove <item>  delete the item

Examples:
  $ turno-browser secret remove proxy-password
```

## turno-browser export [#turno-browser-export]

```text
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 2d
```

## turno-browser import [#turno-browser-import]

```text
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-laptop
```

## turno-browser record [#turno-browser-record]

```text
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 --traces
```

## turno-browser flows [#turno-browser-flows]

```text
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 school
```

## turno-browser replay [#turno-browser-replay]

```text
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-password
```

## turno-browser traces [#turno-browser-traces]

```text
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 --open
```

## turno-browser live [#turno-browser-live]

```text
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 school
```

## turno-browser pause [#turno-browser-pause]

```text
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 school
```

## turno-browser resume [#turno-browser-resume]

```text
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 school
```

## turno-browser do [#turno-browser-do]

```text
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 end
```

## turno-browser background [#turno-browser-background]

```text
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 school
```

### turno-browser background status [#turno-browser-background-status]

```text
Usage:
  turno-browser background status [<id>] [--json]
    which identities have a background server running

Examples:
  $ turno-browser background status
```

### turno-browser background start [#turno-browser-background-start]

```text
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 30m
```

### turno-browser background stop [#turno-browser-background-stop]

```text
Usage:
  turno-browser background stop <id>  stop an identity's background server and
                                      its Chrome

Examples:
  $ turno-browser background stop school
```

## turno-browser doctor [#turno-browser-doctor]

```text
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 --fix
```

## turno-browser reputation [#turno-browser-reputation]

```text
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 --json
```

## turno-browser bench [#turno-browser-bench]

```text
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 --yes
```

## turno-browser-mcp [#turno-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.

```text title="turno-browser-mcp --help"
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
```