Troy / Reference
Configuration and files
Every file Troy keeps in its profile folder, including settings.json keys and defaults, shortcuts, the agent endpoint, extensions and the error log.
On this page
Troy has no configuration file of its own outside the profile. Everything it remembers lives in one folder, Electron’s user data folder for the app name Troy. Keeping these together is deliberate. The signed-in sessions an agent works in, the settings that govern them and the file that tells an agent where to attach sit side by side, so an agent cannot be pointed at a window that uses a different profile.
The folder is:
- macOS:
~/Library/Application Support/Troy - Windows:
%APPDATA%\Troy - Linux:
~/.config/Troy
Chromium’s own profile data (cookies, local storage, and so on) is kept in the same folder. That is where your signed-in sessions live.
Files Troy writes
| File | Holds |
|---|---|
settings.json |
Settings, see below |
window-state.json |
Window size and position |
agent-endpoint.json |
Agent port, only while it is open |
troy-errors.log |
Main-process errors |
extensions/ |
Unpacked Chrome extensions |
shortcuts.json |
New tab tiles (v0.1.5 only) |
history.json |
Visited pages (main only, when on) |
settings.json
{
"rememberHistory": false,
"blockTrackers": true,
"searchEngine": "google"
}
| Key | Default | Meaning |
|---|---|---|
rememberHistory |
false |
Keep a history list |
blockTrackers |
true |
Tracker blocking and parameter stripping |
searchEngine |
"google" |
"google" or "duckduckgo" |
rememberHistorydoes nothing in v0.1.5. On main,truerecords visits tohistory.json, and switching it fromtruetofalsein the settings panel deletes that file.- The new tab page settings panel changes
rememberHistoryandblockTrackers. It cannot changesearchEngine; edit the file for that. - Troy caches settings in memory after the first read, so edit the file while Troy is not running.
- A missing or corrupt file falls back to the defaults. A key with the wrong type falls back to its default.
- An unknown
searchEnginevalue falls back to Google. - Keys Troy does not know are kept when it writes the file.
Search addresses:
google:https://www.google.com/search?q=duckduckgo:https://duckduckgo.com/?q=
shortcuts.json
Used by v0.1.5 only. On main the new tab page has no tiles and Troy neither reads nor writes this file.
A JavaScript Object Notation (JSON) array of tiles, at most 12:
[
{ "url": "https://github.com/", "title": "github.com" }
]
Only http and https addresses are kept. An address without a scheme gets https://. A missing title becomes the host name without www.. Adding an address that is already present updates its title.
window-state.json
The window’s last normal bounds (x, y, width, height), written on resize, move and close, but not while minimised. Width and height are raised to the 520 by 400 minimum. If the file is missing or invalid, Troy opens at 1280 by 860.
history.json
Main only. Written while rememberHistory is on: a JSON array, newest first, of at most 500 entries.
[
{
"url": "https://example.com/",
"title": "Example Domain",
"visitedAt": "2026-10-23T10:00:00.000Z"
}
]
A repeat visit moves the address to the top rather than adding a second entry. Only http and https pages are recorded, never failed loads or Troy’s own pages. Nothing in Troy reads the list yet.
agent-endpoint.json
Written at startup when --cdp-port or TROY_CDP_PORT is set, and deleted when Troy quits. Fields: port, httpEndpoint, webSocketDebuggerUrlHint, pid, version, startedAt. See Driving Troy from an agent.
A crash or force quit skips the delete, so the file can describe a Troy that is no longer running. Check the port before trusting it (how).
troy-errors.log
One entry per uncaught exception or unhandled promise rejection in the main process:
[2026-09-30T10:00:00.000Z] uncaughtException: TypeError: <message>
<stack>
The file is deleted and started again once it passes 512 kilobytes (KB).
extensions/
Created at startup if missing. Each subfolder with a manifest.json is loaded as an unpacked extension with file access off, so an extension cannot read file:// addresses. Open it with View > Extensions Folder and reload with View > Reload Extensions. See Privacy and permissions.
Build configuration
electron-builder.yml in the repository controls packaging. Values worth knowing:
- App id:
com.anishfyi.troy. Product name:Troy. - Output directory:
release/. - macOS target: disk image (DMG), named
Troy-mac-${arch}.dmg, category developer tools. - Windows targets: Nullsoft Scriptable Install System (NSIS) installer
Troy-windows-setup-${arch}.exeand portableTroy-windows-portable-${arch}.exe. - Linux target: AppImage (not built by any script or release job).
afterPack: scripts/after-pack.cjsad-hoc signs and verifies the macOS bundle.- Only
package.json,src/browser/**andbuild/icon.pngare packaged in v0.1.5. On main,src/read/**andsrc/agent/**are added. TypeScript sources and source maps are excluded.