Troy / Get started
Quickstart
Start Troy with its agent port open, find the port from the endpoint file, attach with Playwright, read a tab and detach cleanly.
On this page
This is the shortest path from an installed Troy to an agent script acting on a tab you are signed into. It assumes Troy is installed (Installation) and that you have Node.js.
The agent talks to Troy over the Chrome DevTools Protocol (CDP), the same protocol Chrome’s own developer tools use. Troy keeps that port closed until you ask for it, so step 1 is always to ask.
1. Start Troy with the agent port
The debugging port is closed unless you ask for it, because an open one is unrestricted control of every tab you are signed into. If Troy is already running without it, quit Troy first.
On macOS, for an installed build:
open -a Troy --args --cdp-port=9333
From a source checkout:
npm run browser -- --cdp-port=9333
You can also set the port through the environment instead of a flag:
TROY_CDP_PORT=9333 npm run browser
The flag wins when both are given. Any integer from 1 to 65535 works. Write the flag with =: --cdp-port 9333, with a space, is ignored.
2. Find the endpoint
When the port is open, Troy writes where it is into its profile folder, so nothing has to be copied between terminals:
cat "$HOME/Library/Application Support/Troy/agent-endpoint.json"
{
"port": 9333,
"httpEndpoint": "http://127.0.0.1:9333",
"webSocketDebuggerUrlHint": "http://127.0.0.1:9333/json/list",
"pid": 12345,
"version": "0.1.5",
"startedAt": "2026-09-30T10:00:00.000Z"
}
The file is deleted when Troy quits. If it is missing, Troy is running without the bridge.
3. Sign in and open a page
Use Troy as a browser. Sign in to the site you want the agent to work on and leave the tab open. The agent will see that session.
4. Attach with Playwright
In a scratch folder:
npm install playwright
Save this as attach.mjs:
import { chromium } from 'playwright'
const browser = await chromium.connectOverCDP('http://127.0.0.1:9333')
const [context] = browser.contexts()
// The tabs already open in Troy, including the one you signed into.
for (const page of context.pages()) console.log(page.url())
const page = context.pages().find((p) => p.url().startsWith('http'))
console.log(await page.title())
// What a person can see on the page, as text.
const text = await page.evaluate(() => document.body.innerText)
console.log(text.slice(0, 500))
await browser.close() // detaches only; Troy and its tabs stay open
Run it:
node attach.mjs
browser.close() on a CDP connection detaches. It does not quit Troy, and Troy’s tests check that the tab stays usable afterwards.
5. Read a page from inside Troy
Press Cmd+Shift+A (Ctrl+Shift+A on Windows and Linux) to open the agent panel, then choose read this page. The panel reads the live tab over the same CDP connection.
- In v0.1.5 it shows the page’s title and visible text, read from the Document Object Model (DOM).
- On main it runs the read pipeline and shows the page as Markdown, with a count of DOM blocks and of regions only pixels could explain.
6. Read a page from a script (main only)
From a source checkout of the main branch, with Troy running and the port open. The pipeline runs inside the script over CDP, so the installed v0.1.5 app works as the browser:
node scripts/read.mjs --url "https://example.com/"
--url must equal the tab’s address exactly. Add --json for the full document with a selector on every DOM block. On Linux, set TROY_ENDPOINT_FILE="$HOME/.config/Troy/agent-endpoint.json" first, because the script’s default path is the macOS one.
Next steps
- Driving Troy from an agent: console and network capture, and the rules for working in someone else’s browser.
- Worked examples: checking a deploy, capturing errors, reading a dashboard, filling a form.
- Claude Code plugin and skills: the
troyskill teaches Claude Code the same steps. - Troubleshooting: when the attach fails.