Skip to content
Troy

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

Primary sponsor

The most efficient proxy provider for web scraping and automation, with the highest quality IPs on the market.

Codes for Troy users

  • TROY35 35% off mobile and residential proxies
  • TROY40 40% off ISP (static) proxies

Visit NodeMaven

On this page
  1. Status
  2. Who it is for
  3. A minimal example
  4. What it does today
  5. What it does not do
  6. Where to go next

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-port opens a CDP port on this machine only, and Troy writes agent-endpoint.json into 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.open becomes 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.log instead 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 stress fails 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: troy for driving the browser and apply-fill for 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 troy command. On main, node scripts/read.mjs from 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