Skip to Content

turno-browserReach

Natural language actions and captcha solving

Two opt-in sets of tools that send page content to a model or a service you choose, and the acceptable use of turno-browser.

View source

Both are off until you turn them on for an identity, and both send something to a third party you choose. Read Acceptable use before you do.

Natural language actions

Off until you turn it on per identity. browser_act carries out a short instruction on the current tab ("accept the cookie banner, then open the second result") with a model choosing one browser action at a time; browser_extract reads data off the page as JSON from an instruction; browser_observe proposes the calls that would do it, without running them.

turno-browser set school --act                     # your client's model, through MCP sampling
turno-browser set school --act-provider chat-completions \
  --act-endpoint https://models.example.com/v1 --act-model <model> --act-key keychain:act-model
turno-browser secret set act-model                                  # the key, asked with a hidden prompt
turno-browser set school --no-act                  # off again

The model is yours to pick. With MCP sampling (--act), the agent's own client answers with a model it chooses, and turno holds no key; mcpd passes the request to the session that made the call. When the client does not offer sampling, or with --act-sampling false, turno calls the provider you name: any HTTP API in the chat completions shape, which hosted services and local model servers both speak (http:// is accepted only on 127.0.0.1, localhost or [::1]). Its key is a keychain:<item> reference read from the secret store at each call, never a value in identity.json or in a tool argument, and it is hidden from every result like a vault value.

Each call is bounded: at most act.maxSteps actions (10 by default, at most 30; a call can ask for fewer), act.maxTokens model tokens, prompts and replies together (50,000), and act.timeout (2 minutes). The tools are listed once the server starts with act set; turning it off takes effect at the next call.

What the model gets and can do is fixed by turno, not by the model:

  • The instruction and an accessibility snapshot of the current tab. Vault values are hidden from it, and so are the values of password, one-time code and card fields on the page. An instruction that holds a hidden value is refused: sign-ins go through browser_login.
  • It answers with one call at a time from a short list: browser_click, browser_type, browser_fill_form, browser_select_option, browser_press_key, browser_hover, browser_drag, browser_wait_for, browser_navigate_back. It cannot navigate to a URL, open or close tabs, run script, upload files or call turno's tools, so text on a page that tries to steer it can at worst click and type on that page. A call that would type into a password or one-time code field is refused.
  • The result lists every step, what the model said it was for, how it ended and the budget used.

What it costs: every call sends the instruction and the page's content (what the snapshot shows, including the text of your signed-in pages) to the model's provider, and a model can misread a page and click the wrong thing. Use it on your own accounts, for steps you would check.

With the other settings:

  • "sharing": "tabs": it runs in the calling session's own tabs, under its tab locks.
  • Attach mode: it works in the agent's own tab of your Chrome, never in your tabs.
  • Read mode ("engine": "lightpanda"): browser_extract and browser_observe work; browser_act can only use the tools read mode runs (no drag).
  • Camoufox: it works, through the same stock tools.
  • A proxy: the proxy's user name and password are hidden from the prompt like vault values.
  • humanize: each action is the stock tool call, so it moves and types like the agent's own calls.
  • Recordings: a flow records the stock steps the model chose, never the instruction, the prompt or the page it read, and a trace or screenshot covers those steps like any other.

Captcha solving

Off until you turn it on per identity. browser_solve_captcha finds a captcha widget on the current tab (reCAPTCHA v2, hCaptcha or Turnstile), sends its kind, its public site key and the page address to a solver service you configure, and puts the token it returns into the page's response field (and calls the widget's callback when it names one). The agent then submits the form itself, before the token expires.

turno-browser secret set captcha-solver                             # the service's account key, hidden prompt
turno-browser set shop --captcha-provider task-api \
  --captcha-endpoint https://solver.example.com --captcha-key keychain:captcha-solver
turno-browser set shop --no-captcha                # off again

task-api is the createTask and getTaskResult protocol that many solver services share; the endpoint is the service's API address. The key is read from the secret store at each use and hidden from every result. A solve waits at most captcha.timeout (3 minutes).

Say plainly what it means before you turn it on:

  • A third party sees the challenge and the page: the solver gets the page address and the widget, and usually loads the page on its own machines (or has people answer it) to produce the token.
  • Solving a site's captchas by machine may break its terms of service, and a site that notices may suspend the account. It is meant for your own accounts, on sites where you accept that.
  • It only answers widgets that hand back a token. A full-page "checking your browser" page, a "verify it's you" prompt or a block page is left to you in the window.

Every attempt, solved or not, is a line in the identity's reputation log with the host name, the widget kind and the provider (never the token or the key), and turno-browser reputation shows a solved column once a solver answered.

With the other settings: it works with "sharing": "tabs" (in the calling session's tab) and in attach mode (in the agent's own tab); read mode refuses it, since Lightpanda runs no widget, and turno-browser set refuses the combination. Camoufox refuses it too: the token is set from Patchright's isolated script world and the widget's callback runs in the page's own, and Camoufox runs on stock Playwright. It is not recorded in a flow: a replay that meets the captcha again stops at the next step, where the agent can call browser_solve_captcha and go on with from.

Acceptable use

Use it with your own accounts, on sites whose terms allow automated access by you, and at a human pace. The same goes for the network and user agent settings and Camoufox: they are for your own accounts and sites you may automate. Do not use it to get around access controls, paywalls or rate limits, to scrape at scale, or to access accounts that are not yours. Captcha solving is off unless you turn it on, and then it is for your own accounts only, with the costs above. How you use the browser on third-party sites is between you and each site's terms.

On this page