Skip to Content

turno-browserReach

Engines

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

View source

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:

EngineSet itWhat it is for
Chrome (default)nothing, or --engine chromeeverything: the identity's own profile, headed
Read mode--engine lightpandareading pages fast and with little memory, on Lightpanda
Attach--attach autoworking in the Chrome you already have open and signed in
Camoufox--engine camoufoxa Firefox build, on its own profile
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 and 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)

Lightpanda 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:

RunsRefused, and why
browser_navigate, browser_navigate_back, browser_snapshot (without what is inside an iframe), browser_findbrowser_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_formbrowser_handle_dialog: Lightpanda closes dialogs by itself
browser_evaluate, browser_wait_for, browser_tabs, browser_close, browser_batchbrowser_file_upload, browser_run_code_unsafe
browser_network_requests, browser_network_request, browser_console_messagesbrowser_login: read mode keeps no vault sign-ins
browser_act, browser_extract, browser_observe (when turned on)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 MB64 MB
Peak memory958 MB93 MB
First call, browser start included1,329 ms307 ms
Article: open and snapshot206 ms106 ms
2,000 links: open and snapshot707 ms420 ms
500 script-built rows: open and snapshot311 ms311 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 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 and browser_login work, and so does turno-browser do, which calls the same server.
  • 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 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 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.

On this page