Skip to content
Troy

Troy / Get started

Installation

Install Troy with the Homebrew cask, download a macOS or Windows build from GitHub Releases, or build and run it from source.

On this page
  1. Homebrew (macOS)
  2. Direct downloads
  3. First launch on macOS
  4. First launch on Windows
  5. Build from source
  6. Packaging an installer
  7. Where Troy keeps its data
  8. Updating

Troy ships as a desktop app for macOS (Apple silicon and Intel) and Windows. On Linux you can run it from source.

The installers are v0.1.5, the current release. Features that are only on the main branch, such as the read pipeline, need a build from source.

Homebrew (macOS)

brew tap velofy/tap
brew trust velofy/tap
brew install --cask troy

The brew trust line is needed once. The tap’s own README explains that Homebrew 7.0 will not load a cask from a third-party tap until you trust it, and without it the install fails with Refusing to load cask velofy/tap/troy from untrusted tap velofy/tap. To trust only this cask rather than the whole tap, run brew trust --cask velofy/tap/troy instead.

The cask lives in velofy/homebrew-tap. It installs Troy.app into your Applications folder, picks the Apple silicon or Intel build for your machine, and requires macOS 12 (Monterey) or later, the minimum the app itself declares.

Troy is ad-hoc signed but not notarised. The cask clears the quarantine flag after installing, so the app opens on first launch with no extra step. Installing through the tap is the explicit act of trust that replaces the Gatekeeper prompt.

To remove it:

brew uninstall --cask troy

brew uninstall --zap --cask troy also removes the profile at ~/Library/Application Support/Troy, which holds your signed-in sessions, settings and extensions, along with Troy’s caches, preferences file and saved window state.

Direct downloads

Each release on GitHub Releases carries four files: two macOS disk images (DMG) and two Windows executables (EXE). The file names carry no version, so these links always point at the latest release:

The version lives in the release title and in the app itself.

First launch on macOS

Open the DMG and drag Troy into Applications. Because Troy is not notarised, the first launch of a hand-downloaded copy needs one gesture: Control-click the app, then choose Open. After that it opens normally. If your version of macOS does not offer Open there, open System Settings, then Privacy and Security, and choose Open Anyway, or run xattr -dr com.apple.quarantine /Applications/Troy.app once.

Ad-hoc signing matters here. Without it, Apple silicon refuses to launch the app at all and reports it as damaged, and Control-click then Open does not help. The build signs every macOS bundle for that reason (see Architecture).

First launch on Windows

The installer is not one-click: it lets you choose the install directory, installs for the current user, and creates a desktop shortcut named Troy. The portable build runs without installing.

SmartScreen will warn about an unrecognised app. Choose More info, then Run anyway.

Build from source

Requirements:

  • Node.js and npm. Continuous integration (CI) uses Node.js 22.
  • Git.
  • For packaging on macOS, the Xcode command line tools (codesign is used to ad-hoc sign the bundle).

Clone and install:

git clone https://github.com/velofy/troy.git
cd troy
npm install

A fresh clone is the main branch, which includes changes made since the last release. A build from main still reports version 0.1.5, because package.json has not been bumped since. To build exactly what v0.1.5 shipped, run git checkout v0.1.5 after cloning.

npm install may not download Electron’s binary or Playwright’s Chromium on its own. If npm run browser or the tests complain about a missing binary, fetch both the way CI does:

node node_modules/electron/install.js
npx playwright install chromium

Run the browser straight from the source tree:

npm run browser

Pass flags after --, for example to open the agent port:

npm run browser -- --cdp-port=9333

Packaging an installer

npm run dist:mac    # a DMG for this machine's architecture
npm run dist:win    # the Windows installer and portable EXE
npm run pack        # an unpacked app directory, no installer

Output goes to release/. Each of these scripts deletes release/ first. Treat that folder as a build directory, not an install: running the app from there runs whatever was last built.

npm run smoke starts the packaged build and checks that it opens a window, loads its new tab page and navigates.

On macOS the architecture comes from the machine you build on. The release workflow passes --mac --arm64 or --mac --x64 explicitly (see Development and releases).

electron-builder.yml also defines a Linux AppImage target, but there is no npm script for it and releases do not include a Linux build.

Where Troy keeps its data

Troy stores everything in Electron’s user data folder for the app name Troy. On macOS that is:

~/Library/Application Support/Troy

On Windows it is %APPDATA%\Troy, and on Linux ~/.config/Troy. The files in it are listed in Configuration and files.

Updating

There is no auto-update. Update with brew upgrade --cask troy, or download the new release by hand.