# Engines (/docs/browser/engines)

The Chrome turno-browser launches by default, and the three other engines an identity can run on: read mode, attach and Camoufox.

An identity runs on the Chrome turno launches on its own profile. Three other engines are there
when you ask for one, per identity in `identity.json` (format 6, format 11 for Camoufox) or per
server with a flag, which wins over the file:

| Engine | Set it | What it is for |
|---|---|---|
| Chrome (default) | nothing, or `--engine chrome` | everything: the identity's own profile, headed |
| Read mode | `--engine lightpanda` | reading pages fast and with little memory, on Lightpanda |
| Attach | `--attach auto` | working in the Chrome you already have open and signed in |
| Camoufox | `--engine camoufox` | a Firefox build, on its own profile |

```sh
turno-browser set school --engine lightpanda     # read mode for this identity
turno-browser set school --attach auto           # attach to your own Chrome
turno-browser set school --engine "" --attach "" # back to the default
turno-browser-mcp --engine lightpanda            # read mode for one server, no identity
```

With [several agents in one browser](/docs/browser/sharing) and
[human-like input](/docs/browser/actions#human-like-input): read mode works with `"sharing": "tabs"`, and attach mode
with `humanize`. The other two pairs are refused with the reason, in `identity.json` and from
server flags: attach mode with `"sharing": "tabs"` (in your own Chrome turno keeps one agent's
tabs apart from yours, not several sessions apart from each other), and read mode with
`humanize` (Lightpanda lays out no page, so there is no pointer path or scroll to play).
Camoufox works with both, and with recordings.

## Read mode (Lightpanda) [#read-mode-lightpanda]

[Lightpanda](https://github.com/lightpanda-io/browser) is a headless browser built for
automation: it runs scripts and builds the page, but does not lay it out or draw it. turno never
downloads it. Install it yourself (`brew install lightpanda-io/browser/lightpanda` on macOS, the
nightly binary on Linux), and turno runs the `lightpanda` on your PATH, or the one at
`TURNO_LIGHTPANDA_PATH`. `turno-browser doctor` shows the one it found and how to install it.

turno starts `lightpanda serve` on a private Unix socket (no TCP port) with Lightpanda's
telemetry off, and stops it when the session closes or after the idle limit. A Lightpanda left
running by a server that was killed (SIGKILL gives it no chance to clean up) is stopped when the
next read mode server for the same identity starts, as a Chrome left behind on a profile is. For an identity,
Lightpanda keeps its own cookies in `lightpanda-cookies.json` in the identity's state folder: it
never reads or writes the Chrome profile, so a site you signed into in Chrome is not signed in
here, and read mode runs no health check, reputation log, blocking or cache.

These tools run in read mode; the others are refused with the reason before they reach the
browser:

| Runs | Refused, and why |
|---|---|
| `browser_navigate`, `browser_navigate_back`, `browser_snapshot` (without what is inside an iframe), `browser_find` | `browser_take_screenshot`: no layout, so a screenshot shows only the text |
| `browser_click` (a link with `target="_blank"` opens nothing) | `browser_resize`, `browser_emulate_media`, `browser_drag`, `browser_drop`: no layout |
| `browser_hover`, `browser_type`, `browser_press_key`, `browser_select_option`, `browser_fill_form` | `browser_handle_dialog`: Lightpanda closes dialogs by itself |
| `browser_evaluate`, `browser_wait_for`, `browser_tabs`, `browser_close`, `browser_batch` | `browser_file_upload`, `browser_run_code_unsafe` |
| `browser_network_requests`, `browser_network_request`, `browser_console_messages` | `browser_login`: read mode keeps no vault sign-ins |
| `browser_act`, `browser_extract`, `browser_observe` (when [turned on](/docs/browser/natural-language-and-captchas#natural-language-actions)) | `browser_solve_captcha`: no captcha widget runs |

Checked with Lightpanda 1.1.0 (nightly) through Patchright. Lightpanda's CDP answers a few calls
differently from Chrome's, so turno passes its traffic through a small relay that turns those
answers into ones Patchright handles.

Measured on one machine (an Apple M3 with 16 GB, macOS 26.5, Chrome 157, Lightpanda 1.1.0
nightly; median of five runs): three local pages from a fixture server (an article, a list of
2,000 links, a page that builds 500 rows with a script), each opened and snapshotted five times
through the MCP server, headless Chrome against Lightpanda:

| | Chrome (headless) | Lightpanda |
|---|---|---|
| Memory after the three pages (browser processes, RSS) | 913 MB | 64 MB |
| Peak memory | 958 MB | 93 MB |
| First call, browser start included | 1,329 ms | 307 ms |
| Article: open and snapshot | 206 ms | 106 ms |
| 2,000 links: open and snapshot | 707 ms | 420 ms |
| 500 script-built rows: open and snapshot | 311 ms | 311 ms |

The memory numbers held steady from run to run. The times did not: the machine was busy during
the runs and single runs varied by a factor of two or more, so read them as a rough ratio, not a
promise. Your numbers will differ.

Use read mode for public pages you only need to read. It is not a way to visit sites that block
automation: Lightpanda sends `Lightpanda/1.0` as its user agent, and `browser_login` is
refused there.

## Camoufox [#camoufox]

[Camoufox](https://camoufox.com) is a Firefox build that sets what the browser reports (screen,
fonts, WebGL and the like) inside the browser itself. turno can run an identity on it, off by
default. Two things to weigh before you turn it on: a Firefox whose reported values differ from
the computer's is something sites look for, and Camoufox is a third party's build of Firefox
that you install and keep up to date yourself.

turno never downloads it. Two things must be installed, and `turno-browser doctor` checks both
and prints how to install them:

- Camoufox: `pip install -U camoufox && camoufox fetch`. turno runs the newest build in the
  installer's cache folder, or the executable at `TURNO_CAMOUFOX_PATH`.
- Stock Playwright of the same minor version as the Patchright turno-browser uses
  (`npm install -g playwright-core@<version>`, or its folder at `TURNO_PLAYWRIGHT_CORE`):
  Patchright drives Chromium only, and Firefox speaks Playwright's own protocol.

For an identity, Camoufox keeps its own Firefox profile in the identity's state folder
(`camoufox-profile`): the Chrome profile and its sign-ins do not carry over, and
`turno-browser login` (which opens the Chrome profile) is refused; sign in from an agent session,
with `browser_login` and the vault. The identity's runtime lock holds while it runs. turno passes
it no generated values: it presents what its build reports for this computer, with the identity's
languages and time zone, and its `proxy` when set. `userAgent` and `"keychain": "system"` are
refused with it, and so is attach mode.

Every stock tool runs except `browser_run_code_unsafe`, which runs code written for Patchright's
API; it is refused with the reason. With the opt-in features:

- [Natural language actions](/docs/browser/natural-language-and-captchas#natural-language-actions) and `browser_login` work, and so does
  [`turno-browser do`](/docs/browser/actions#from-the-shell), which calls the same server.
- [Captcha solving](/docs/browser/natural-language-and-captchas#captcha-solving) is refused, in `identity.json` and, with `--engine camoufox`,
  when `browser_solve_captcha` is called: it relies on Patchright's script worlds.
- The [live view](/docs/browser/live-view) shows no picture, since it is a Chrome screencast;
  pause and resume work.

That was checked with Playwright's own Firefox build in Camoufox's place (an official Camoufox
build was not available to test), along with a proxy, humanize, tab sharing, recordings,
natural language actions, `browser_login` and the live view's pause. The health check, reputation log, blocking and cache run the
same code as with Chrome and were not checked on Firefox separately.

## Attach to your Chrome [#attach-to-your-chrome]

Attach mode connects to the Chrome you already have open instead of launching one, so the agent
works in your real, signed-in browser. It is off until you set it, and it is a big grant: the
agent can see and act on every window and every signed-in site of that Chrome profile.

Since Chrome 136, `--remote-debugging-port` is ignored on Chrome's default profile, so the way in
is Chrome's own switch: open `chrome://inspect/#remote-debugging` (Chrome 144 or newer) and turn
remote debugging on. Chrome then asks you to allow each new connection, and turno waits up to 60
seconds for your answer. That dialog is the consent step; turno cannot answer it for you.

`--attach` takes `auto` (your default Chrome profile), the absolute path of a Chrome user data
folder (Chrome Beta or Canary, or a Chrome you started with `--remote-debugging-port` and its own
`--user-data-dir`), or a loopback endpoint (`http://127.0.0.1:9222`). It never connects to
another machine.

turno never closes your browser or a tab it did not open:

- it opens a tab of its own when it connects and works there, so its first navigation never
  replaces one of your pages; the agent can still list and select your tabs;
- a tab that opens during one of its tool calls is the agent's; tabs that were open before, or
  that you open between calls, are yours;
- `browser_close`, the end of the session and the idle limit close the agent's tabs and
  disconnect; Chrome keeps running (after the idle limit, the next call connects again, and Chrome
  may ask again);
- the tab governor counts, parks and closes only the agent's tabs, and closes no popup;
- there is no runtime lock and no orphan sweep for that Chrome: those act on the identity's own
  profile, which attach mode does not use; the identity's health check, reputation log, blocking
  and cache do not apply either;
- `browser_run_code_unsafe` is refused: it would run arbitrary code against your whole browser.