Troy / Guides
Privacy and permissions
What Troy refuses, which permissions pages get, how tracker blocking works, what the profile keeps, and the limits of each protection.
On this page
Troy is meant to be driven by an agent on a profile that is signed into real accounts. Its defaults follow from that:
- Refuse in code. A rule enforced by instructions to an agent is a suggestion; a rule in the browser holds for every caller.
- Keep nothing you did not ask for. A list of everywhere you went, on a profile holding real accounts, is a liability, so none exists by default.
- Say plainly where a protection stops. Overstating privacy is a bug.
Sessions live in one profile
Everything you sign into in Troy is kept in its profile folder (~/Library/Application Support/Troy on macOS). An agent that attaches over the Chrome DevTools Protocol (CDP) works inside that same profile, which is the point: the page behind the login is the page worth testing.
There is one profile per install. Troy writes agent-endpoint.json beside the profile so that an agent cannot be pointed at the wrong window by a second profile.
Address bar refusals
Every string typed into the address bar or the new tab search box goes through one resolver. In v0.1.5 the new tab shortcut tiles used it too; on main the tiles are gone, and the agent tool layer’s page_navigate uses it instead. It returns one of five results: load a web address, run a search, hand the address to another app, refuse it, or do nothing for empty input.
These schemes are refused, with the reason shown as a notice in the chrome:
| Scheme | Reason Troy gives |
|---|---|
javascript: |
Runs script in the page already open |
data: |
Can carry a whole page from the address bar |
blob: |
Only meaningful inside the page that made it |
filesystem: |
Reaches the page sandbox directly |
chrome:, devtools: |
Browser internals, not a web page |
chrome-extension: |
Extension pages are not addressable here |
about:blank is allowed; other about: pages are refused. Refused schemes are checked before the generic scheme:// rule, so javascript://x/%0aalert(document.cookie) is refused even though it looks like a web address.
mailto:, tel:, sms:, facetime:, msteams: and zoommtg: are handed to the operating system, as is any other unknown scheme written with ://.
Page behaviour
- Popups become tabs. A page calling
window.openfor anhttporhttpsaddress gets a new tab. Other targets go to the operating system. No uncontrolled window is ever opened. - Page navigations. If a page tries to move its top frame to a scheme other than
http,https,fileorabout, Troy cancels it and hands the address to the operating system. - Permissions. Every permission request is denied except fullscreen and sanitized clipboard writes. Camera, microphone, geolocation and notifications are refused.
- Isolation. Each tab is a separate view with context isolation and the sandbox on, and no Node.js integration. A page cannot script Troy’s own chrome.
- The new tab bridge. The new tab page has a small bridge for tiles and settings. The main process checks the calling frame’s address on every call and refuses anything that is not Troy’s own new tab page.
Tracker blocking
On by default, and switchable from the new tab page settings (the gear button). It does two separate things:
- Strips tracking parameters from an address before the request is made, including
utm_*,gclid,fbclid,msclkid,mc_eid,igshid,_hsencand others. A search URL keeps itsq. - Cancels third-party requests to a fixed list of analytics and ad hosts, such as
google-analytics.com,doubleclick.net,connect.facebook.net,hotjar.comandsegment.io. Hosts match exactly or as a subdomain, never as a substring. On main, a tracker request started by something other than a web page (an initiator that is nothttporhttps) is treated as third party and cancelled.
Two limits are deliberate. A top-level navigation you typed or clicked is never cancelled, and a request to the same site as the page (compared on the last two labels of the host name) is never cancelled.
It does nothing about first-party tracking. Search goes to Google, and a Google search is seen by Google. The settings panel says so.
Search and suggestions
Nothing is sent while you type. The search URL is built once, when you press Enter, and no suggestion service is ever asked. Google is the default engine. duckduckgo is the other supported value, set by editing settings.json (see Configuration and files).
History
Nothing is recorded by default.
- In v0.1.5 the Remember history switch in the new tab settings is stored and toggles, but no code reads it, so turning it on records nothing. The project’s product requirements document (PRD) lists this as a known gap. The new tab shortcuts are added by hand, not collected by watching where you go.
- On main the switch works. While it is on, each
httporhttpspage a tab navigates to is added tohistory.jsonin the profile, newest first, with its title and the time. A repeat visit moves to the top instead of being duplicated, and the list keeps at most 500 entries. Turning the switch off deletes the file. Failed loads and Troy’s own pages are never recorded. Nothing reads the list yet: there are no suggestions and no history page.
Extensions
Unpacked Chrome extensions load from <profile>/extensions/ at startup. There is no store, nothing is fetched remotely, and there is no auto-update, so an extension is only ever code you put there. Each extension is loaded with file access off.
- View > Extensions Folder creates and opens the folder.
- View > Reload Extensions loads it again and reports the result as a notice.
A subfolder counts as an extension only if it contains manifest.json. One broken extension does not stop the others from loading. Electron implements a subset of the Chrome extension application programming interfaces (APIs), so an extension that needs an unimplemented API will report that itself. There is no toolbar surface for extensions yet.
What a read can see
The agent panel, and anything attached over CDP, can read any page in the profile. Two rules in the read pipeline on main limit what a read returns:
- Password values are never extracted. A password field appears as
[password field]. The agent tool layer’spage_readlists password inputs but leaves their value empty. - Hidden text is dropped. Text a person could not see, such as
display: none, zero-sized, transparent or white-on-white text, never reaches the output. Hidden text is the most common way scraped output gets poisoned.
These rules apply to Troy’s own read. A CDP client can still evaluate any script it likes in the page.
Error log
When something goes wrong inside Troy’s main process, the browser stays open, shows a notice, and appends one entry to troy-errors.log in the profile. The log records the error and stack, not the pages you had open, and is trimmed once it passes 512 kilobytes (KB).
What Troy does not defend against
From the project’s design document: a user who deliberately installs a malicious extension, a compromised machine, and first-party tracking by a site you chose to visit.
An open agent port is also full control of every signed-in tab to any process on the machine. There is no token on the port. That is why it is off unless you ask for it, on each launch.