Troy / Guides
Driving Troy from an agent
How an agent attaches to Troy over the Chrome DevTools Protocol, finds the right tab, captures console and network events, and behaves in a shared browser.
On this page
Troy’s agent bridge is the Chrome DevTools Protocol (CDP), unchanged. Anything that speaks it can attach: Playwright, Puppeteer, or a raw WebSocket client. This page uses Playwright, which is what Troy’s own tests and skill use.
The browser an agent attaches to is one a person is using, with their sessions in it. Most of this page follows from that: find the port without asking the person to copy it, work in your own tab, and leave without closing anything.
How the bridge works
When Troy starts with --cdp-port=<port> (or TROY_CDP_PORT), it turns on Chromium’s remote debugging on that port and allows CDP connections from the http://127.0.0.1 origin. It then writes agent-endpoint.json into its profile folder and deletes it again when it quits. On main the file is written to a temporary name and renamed into place, so a reader never sees half a file.
Without the flag no port is opened at all. Troy’s test suite checks both directions: attachable when asked for, refused when not.
| Field | Meaning |
|---|---|
port |
The port you passed |
httpEndpoint |
http://127.0.0.1:<port>, for connectOverCDP |
webSocketDebuggerUrlHint |
http://127.0.0.1:<port>/json/list |
pid |
Troy’s process id |
version |
Troy’s version |
startedAt |
When Troy started |
startedAt uses the International Organization for Standardization (ISO) 8601 date format.
The endpoint file is not a token and grants nothing. It only says where the port is. The WebSocket address for each tab changes as tabs open and close, which is why the file points at the /json/list listing rather than naming one address.
Find the endpoint from code
The file sits in Electron’s user data folder for the app name Troy:
import { readFileSync } from 'node:fs'
import { homedir } from 'node:os'
import path from 'node:path'
const base = {
darwin: path.join(homedir(), 'Library', 'Application Support'),
win32: process.env.APPDATA,
}[process.platform] ?? path.join(homedir(), '.config')
const file = path.join(base, 'Troy', 'agent-endpoint.json')
const { httpEndpoint } = JSON.parse(readFileSync(file, 'utf8'))
If the file is missing, Troy is running without the bridge. Ask the person to restart it with --cdp-port rather than starting a second copy, which would not have their session.
Check that it is live
The file says where Troy was, not that it is still there. It can be stale in two cases:
- Troy crashed or was force quit. The file is removed on a normal quit only, so it can outlive the browser.
- A second Troy started on the same profile. Troy holds no single-instance lock. The second copy overwrites the file, and deletes it when it quits, even if the first copy is still running.
Before attaching, ask the port itself. Chromium answers /json/version on its debugging port:
const res = await fetch(`${httpEndpoint}/json/version`).catch(() => null)
if (!res?.ok) throw new Error('agent-endpoint.json is stale: nothing answers on that port')
Pick the right tab
connectOverCDP returns the tabs already open. Troy’s own pages, such as the chrome (tab strip and toolbar) and the new tab page, are local file:// pages, so filter on the address to find a web page:
import { chromium } from 'playwright'
const browser = await chromium.connectOverCDP(httpEndpoint)
const [context] = browser.contexts()
const page = context.pages().find((p) => p.url().startsWith('http'))
To work without disturbing the person, open a tab of your own and close only that one:
const mine = await context.newPage()
await mine.goto('http://localhost:3000/')
// ... work ...
await mine.close()
Troy’s tests do not cover opening a tab from a CDP client. If newPage() fails, ask the person to open a tab for you (Cmd+T), or start Troy with the address as an argument (open -a Troy --args --cdp-port=9333 http://localhost:3000/), and work only in that tab.
Act on the page
Use normal Playwright calls:
await page.goto('http://localhost:3000/checkout')
await page.getByRole('button', { name: 'Continue' }).click()
console.log(await page.getByRole('alert').textContent())
Capture console and network events
Attach listeners before the navigation you expect to produce them:
page.on('console', (m) => console.log(`[${m.type()}]`, m.text()))
page.on('pageerror', (e) => console.log('[pageerror]', e.message))
page.on('requestfailed', (r) => console.log('[failed]', r.url(), r.failure()?.errorText))
Read the page as a document
To check what is visible, read innerText or use role queries, never textContent or innerHTML, which include text a person cannot see.
On main, the read pipeline returns the whole page as one document: visible text in reading order, a selector on every block that came from the Document Object Model (DOM), and a marker for each region only pixels could explain. Run it with node scripts/read.mjs or call readPage from your own code. See How Troy reads a page.
Detach
await browser.close()
On a CDP connection this detaches. It does not close Troy or its tabs. Never quit Troy to clean up: that closes the window someone is working in.
Rules for working in someone else’s browser
These come from the troy skill that ships with the repository:
- One Troy, the user’s. Do not launch a second instance while one is running.
- Do not close the user’s tabs. Open your own and close only those.
- Do not navigate away from a tab the user is working in without asking.
- If the bridge is not enabled, ask. Do not fall back to a fresh headless browser and report results from a session that was never signed in.
Limits the agent inherits
The refusals Troy enforces apply to an agent as well as to a person:
- Popups become tabs, and device permission requests are denied.
- The address bar refusals apply to the address bar and the new tab search box (and, in v0.1.5, the shortcut tiles).
- A page’s own attempt to navigate its top frame to a scheme other than
http,https,fileorabout:blankis handed to the operating system instead of loaded.
A CDP client does not go through the address bar. page.goto sends Page.navigate straight to Chromium, so the address bar’s resolver (resolveOmnibox) never sees that address. Do not count on the address bar’s refusals to filter what your own script navigates to. On main, the agent tool layer’s page_navigate does run every address through that resolver. See Privacy and permissions and Agent tool layer.
Scripts for verified actions
The repository also carries Node.js scripts that navigate, click and fill with a host allowlist and a check that each action changed the page. They were written for the apply-fill workflow and attach to any CDP endpoint. See Action scripts.