Free and open sourcev0.1.5 release notes

Your agent joins the browser you are signed into.

Troy is a Chromium browser that an agent can attach to. You browse and sign in as usual; the agent connects over the Chrome DevTools Protocol (CDP) and works in the tabs you already have, logins included.

For Apple silicon. Also for Intel Macs and Windows. MIT licence.

Illustration: a Troy window signed in to a checkout page on localhost, with the agent port open and an agent in a terminal attached to it, clicking the Continue button.

Most browser automation starts a fresh, empty browser. The pages worth automating sit 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.

Capabilities

A real browser, with its rules in code.

Pages render as Chromium renders them. What a page or an agent may do is decided by the browser, because a rule in the browser holds for every caller.

An agent port that is off by default

Start Troy with --cdp-port and Chromium's debugging port opens on 127.0.0.1, for that launch only. Troy writes agent-endpoint.json into its profile so the agent finds the port without anything copied between terminals, and deletes it when Troy quits.

agent-endpoint.json
{
  "port": 9333,
  "httpEndpoint": "http://127.0.0.1:9333",
  "version": "0.1.5",
  ...
}

Your tabs, your logins

Any CDP client, such as Playwright's connectOverCDP, gets the tabs already open, including the one you signed into. browser.close() only detaches; Troy and your tabs stay open.

Refusals live in code

javascript:, data:, blob:, filesystem: and browser-internal addresses are refused by one resolver. window.open becomes a tab, and camera, microphone, location and notification requests are denied.

Actions that check themselves

The action scripts work inside a host allowlist, refuse submit buttons, password fields and ambiguous matches, and read the page back after acting. A click that changed nothing reports NOT VERIFIED.

An agent panel in the window

Press Cmd+Shift+A (Ctrl on Windows) to read the live tab. In v0.1.5 it shows the page's title and visible text, read from the Document Object Model (DOM).

Keeps nothing you did not ask for

No history by default and nothing sent while you type. Third-party trackers are cancelled and tracking parameters such as utm_*, gclid and fbclid are stripped before the request is made.

Stays open, stays fast

An uncaught error is written to troy-errors.log instead of closing every signed-in tab. A stress run with twelve busy tabs fails if the chrome drops below 60 frames per second.

Skills for agents

Two skills ship in the repository. troy teaches an agent to attach, capture console and network events, and leave your tabs alone. apply-fill fills long forms one approved answer at a time and never submits.

How it works

From install to attached in four steps.

  1. Install

    Use the Homebrew cask on macOS, or download the disk image or Windows installer from the latest release.

  2. Open the agent port

    Start Troy with --cdp-port=9333, or set TROY_CDP_PORT. Then browse and sign in as you normally would.

  3. Attach the agent

    The agent reads agent-endpoint.json and connects with any CDP client. It gets the tabs you already have, not a new, empty profile.

  4. Detach when done

    browser.close() on a CDP connection detaches the agent and leaves Troy and every tab open.

Terminal
$ open -a Troy --args --cdp-port=9333
attach.mjsNode.js with Playwright
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; Troy and its tabs stay open

Works with Dexter

Dexter already works in Troy.

Dexter, Velofy's coding agent, works with Troy today through its troy tool. A deeper, native Dexter integration is coming.

Any other agent can attach with a CDP client of its own, such as Playwright.

Meet Dexter

Install

Get Troy.

macOS 12 or later on Apple silicon and Intel, and Windows 10 or later. Linux runs from source.

Homebrew

Recommended on macOS
$ brew tap velofy/tap
$ brew trust velofy/tap
$ brew install --cask troy

The brew trust line is needed once. The cask picks the Apple silicon or Intel build and clears the quarantine flag, so Troy opens on first launch with no extra step. Update with brew upgrade --cask troy.

From source

$ git clone https://github.com/velofy/troy.git
$ cd troy && npm install
$ npm run browser

The main branch includes changes made since the last release, such as the read pipeline. Pass flags after --, for example npm run browser -- --cdp-port=9333.

Latest release v0.1.5Release notesAll releasesInstallation guide

Where it stands

Honest about what is built.

Troy is named for a read pipeline that fuses structure from the DOM with optical character recognition (OCR) of the regions the DOM cannot explain. Part of it is on the main branch; the rest is planned.

Released in v0.1.5

  • The browser for macOS and Windows
  • The agent port and agent-endpoint.json
  • The agent panel, reading text from the DOM
  • Action scripts and the two skills

On main, not yet released

  • The read pipeline: it settles the page, reads structure from the DOM and drops text a person could not see
  • Regions only pixels can explain, such as a canvas, are marked as unread
  • History, recorded only when you turn it on

Planned

  • OCR engines: Apple Vision on macOS, Tesseract elsewhere
  • A troy command, starting with troy read
  • Find in page, context menus, tab reordering and auto-update

Read the roadmap

FAQ

Questions.

More in the documentation.

Does the agent get a new browser?

No. It attaches to the Troy window you are using and sees the tabs already open, with your logins. Troy's troy skill tells an agent to open its own tab, close only that tab, and not steer a tab you are working in without asking.

Is the debugging port open all the time?

No. It opens only when you start Troy with --cdp-port or set TROY_CDP_PORT, for that launch, and it listens on 127.0.0.1. An open port is full control of every tab you are signed into, so it stays off by default.

Which agents can use Troy?

Any client that speaks the Chrome DevTools Protocol, such as Playwright with connectOverCDP. Dexter, Velofy's coding agent, works with Troy today through its troy tool, and a deeper native integration is coming.

Can Troy read text inside a canvas or an image?

Not yet. In v0.1.5 the agent panel reads a page's text from the DOM alone. On the main branch, the read pipeline finds the regions only pixels can explain, such as a canvas, but no OCR engine is connected yet, so those regions are reported as unread rather than transcribed.

Why does macOS ask before the first launch?

Troy is ad-hoc signed but not notarised. For a downloaded disk image, Control-click the app and choose Open once. The Homebrew cask clears the quarantine flag, so it opens with no extra step. On Windows, choose More info, then Run anyway.

Is there a Linux build?

No release build yet. Troy runs on Linux from source with npm run browser, and its continuous integration runs the tests on Linux as well as macOS and Windows.

Can it replace my everyday browser?

That is not the aim. There are no bookmarks, find in page, context menus, address bar suggestions or auto-update yet.

What does Troy cost?

Nothing. Troy is free and open source under the MIT licence, and there is no paid plan.

Let your agent work where you are signed in.

Free and open source. macOS and Windows.