Docs / Documentation
Troy
A Chromium browser an agent can attach to inside the session you are signed into
brew tap velofy/tap && brew trust velofy/tap && brew install --cask troy- v0.1.5
- MIT
- JavaScript
Sponsors
The most efficient proxy provider for web scraping and automation, with the highest quality IPs on the market.
Codes for Troy users
TROY3535% off mobile and residential proxiesTROY4040% off ISP (static) proxies
On this page
Troy is a real Chromium browser with its own chrome, built so that an agent can attach to the window you are already signed into and work the page with you.
Most browser automation starts a fresh, empty browser. The pages worth automating are usually behind a login, so the fresh browser is the wrong browser. Troy inverts that: you browse in it, and an agent joins the session you already have over the Chrome DevTools Protocol (CDP). How it works builds the rest of the design from that one idea.
Troy is built with Electron and released under the MIT license. The source is at github.com/velofy/troy.
Status
- Current release: v0.1.5 (30 September 2026). Homebrew and the download links install this version. It is tested on macOS, Windows and Linux. Its agent panel reads a page’s text from the Document Object Model (DOM) only.
- On the main branch, not yet released (as of 23 October 2026): the read pipeline the project is named for. It reads structure from the DOM, drops text a person could not see, and marks the regions only pixels can explain, such as a canvas. The optical character recognition (OCR) stage exists, but no OCR engine is connected yet, so those regions are reported as unread rather than transcribed. Main also records history when you turn it on. To use these now, run Troy from source.
Pages in these docs say “on main” wherever behaviour differs from v0.1.5. The Changelog lists every difference.
Who it is for
- A person pairing with a coding agent. You are signed into a staging site, an admin panel or a dashboard, and you want the agent to look at the page you are looking at and act on it, without a second browser and a second login.
- The agent itself. It attaches with any CDP client, such as Playwright, and gets the tabs that are already open instead of a new, empty profile.
Troy is not trying to replace a general-purpose browser for daily use.
A minimal example
Start Troy with the debugging port open. It is closed unless you ask for it, because an open port is full control of every tab you are signed into.
open -a Troy --args --cdp-port=9333
Attach from Node.js with Playwright. This gives you the tabs already open, not a new browser:
import { chromium } from 'playwright'
const browser = await chromium.connectOverCDP('http://127.0.0.1:9333')
const [context] = browser.contexts()
const page = context.pages().find((p) => p.url().startsWith('http'))
await page.goto('http://localhost:3000/checkout')
await page.getByRole('button', { name: 'Continue' }).click()
await browser.close() // detaches; it does not close the user's browser
The Quickstart walks through this end to end.
What it does today
- An agent bridge that is off by default.
--cdp-portopens a CDP port on this machine only, and Troy writesagent-endpoint.jsoninto its profile so an agent can find it. See Driving Troy from an agent. - Refusals in code.
javascript:,data:,blob:,filesystem:and the browser-internal schemes are refused by the address bar and the new tab search box, from one copy of the rules. - No uncontrolled popups.
window.openbecomes a tab. - Device permissions denied. Camera, microphone, geolocation and notification requests are refused. Only fullscreen and sanitized clipboard writes are allowed.
- Failure pages that keep your address. A failed load shows a page with the address you asked for, and reload retries that address.
- It stays open. Uncaught errors in the main process are written to
troy-errors.loginstead of closing every tab. - No history by default, no suggestion requests while you type, and third-party trackers blocked. See Privacy and permissions.
- Unpacked Chrome extensions load from the profile folder. No store and nothing fetched remotely.
- A 60 frames per second (fps) gate.
npm run stressfails the run if the chrome drops below 60fps while a set of busy tabs (12 by default) loads and animates. - A Claude Code plugin with two skills:
troyfor driving the browser andapply-fillfor filling long forms one approved answer at a time. See Claude Code plugin and skills. - On main: the read pipeline in the agent panel and in
scripts/read.mjs, with Markdown or JavaScript Object Notation (JSON) output. See How Troy reads a page.
What it does not do
- It does not transcribe pixels yet. On main the pipeline finds the regions that need OCR, but no engine is connected, so they come back as “untranscribed” markers. In v0.1.5 there is no OCR path at all.
- It has no
troycommand. On main,node scripts/read.mjsfrom a source checkout is the closest thing. - It has no bookmarks, find in page, context menus, tab reordering or address bar suggestions.
- It runs Chromium only.
- It is ad-hoc signed but not notarised, so a manual download needs one extra step on first launch. See Installation.
- In v0.1.5 the Remember history switch is stored but records nothing. On main it works.
- There is no auto-update.
Where to go next
- Installation: Homebrew, direct downloads, or build from source.
- Quickstart: open the port and attach an agent.
- How it works: the problem, the constraints and the design that follows.
- Worked examples: common tasks from start to finish.
- Using the browser: tabs, the address bar, the new tab page and the agent panel.
- Command line and environment: every flag, script and variable.
- Architecture: the process model and the security model.
