Skip to content
Troy

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
  1. Files Troy writes
  2. settings.json
  3. shortcuts.json
  4. window-state.json
  5. history.json
  6. agent-endpoint.json
  7. troy-errors.log
  8. extensions/
  9. Build configuration

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"
  • rememberHistory does nothing in v0.1.5. On main, true records visits to history.json, and switching it from true to false in the settings panel deletes that file.
  • The new tab page settings panel changes rememberHistory and blockTrackers. It cannot change searchEngine; 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 searchEngine value 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}.exe and portable Troy-windows-portable-${arch}.exe.
  • Linux target: AppImage (not built by any script or release job).
  • afterPack: scripts/after-pack.cjs ad-hoc signs and verifies the macOS bundle.
  • Only package.json, src/browser/** and build/icon.png are packaged in v0.1.5. On main, src/read/** and src/agent/** are added. TypeScript sources and source maps are excluded.