Suite Desktop Architecture

Trezor Suite Desktop is an Electron-based application that provides a full-featured, offline-capable interface for managing Trezor hardware wallets. It combines the power of Node.js with a modern React frontend.

Overview

Suite Desktop is built using:

Electron 40.1.0

Cross-platform desktop framework

React 19.1.0

UI rendering and component architecture

Redux Toolkit

State management and data flow

Node.js 24

Backend runtime for native features

Architecture Layers

┌────────────────────────────────────────┐
│         Renderer Process (UI)            │
│  ┌──────────────────────────────────┐  │
│  │  React Components (@trezor/suite)  │  │
│  │  Redux Store & Middleware          │  │
│  │  @trezor/ipc-proxy                 │  │
│  └──────────────────────────────────┘  │
└──────────────────┬─────────────────────┘
                 │ IPC Communication
┌──────────────────┴─────────────────────┐
│        Main Process (Node.js)           │
│  ┌──────────────────────────────────┐  │
│  │  @trezor/suite-desktop-core        │  │
│  │  - Window Management               │  │
│  │  - Auto Updates                    │  │
│  │  - File System Access              │  │
│  │  - Native Modules                  │  │
│  │  @trezor/connect (Node)            │  │
│  └──────────────────────────────────┘  │
└──────────────────┬─────────────────────┘
                 │
┌──────────────────┴─────────────────────┐
│         Native Layer                    │
│  - Trezor Bridge (USB/HID)             │
│  - Tor (Privacy)                       │
│  - File System                         │
│  - OS Integration                      │
└────────────────────────────────────────┘

Key Components

1. Renderer Process

The renderer process runs the React-based UI in a Chromium browser context.

UI Layer
IPC Proxy
Security

@trezor/suite PackageThe main Suite UI package provides:

React components for all screens
Redux store for state management
Routing and navigation
Business logic

// Renderer entry point
import { App } from '@trezor/suite';
import { render } from 'react-dom';

render(<App />, document.getElementById('root'));

@trezor/ipc-proxyProxies Connect API calls from renderer to main process:

// In renderer process
import TrezorConnect from '@trezor/connect';

// This actually calls main process via IPC
const result = await TrezorConnect.getAddress({
  path: "m/49'/0'/0'/0/0",
  coin: 'btc',
});

All @trezor/connect methods are transparently replaced by IPC proxy calls.

Context IsolationThe renderer runs with:

Context isolation enabled
Node integration disabled
Sandboxing enabled

// Electron configuration
const window = new BrowserWindow({
  webPreferences: {
    contextIsolation: true,
    nodeIntegration: false,
    sandbox: true,
    preload: path.join(__dirname, 'preload.js'),
  },
});

2. Main Process

The main process handles all Node.js operations and system integrations.

@trezor/suite-desktop-core

Core functionality for the Electron main process:Window Management

Create and manage application windows
Handle window state (minimize, maximize, close)
Multi-window support

Auto-Updates

Check for application updates
Download and install updates
Notify user of available updates

File System

Read/write application data
Manage logs
Export/import wallet data

IPC Handlers

Process messages from renderer
Invoke native APIs
Return results to renderer

Trezor Connect in Main Process

Connect runs in Node.js context in main process:

// Main process
import TrezorConnect from '@trezor/connect';

TrezorConnect.init({
  manifest: {
    email: '[email protected]',
    appUrl: 'https://suite.trezor.io',
  },
});

// Handle IPC requests from renderer
ipcMain.handle('trezor-connect', async (event, method, params) => {
  return await TrezorConnect[method](params);
});

Benefits:

Direct USB/HID access
No WebUSB limitations
Better performance
Offline capabilities

Native Modules

Integration with native system features:Trezor Bridge

USB/HID device communication
Device detection and monitoring
Low-level protocol handling

Tor

Bundled Tor binary
SOCKS5 proxy configuration
Privacy-enhanced connections

Coinjoin Backend

Bitcoin privacy features
Coordinator communication
Transaction mixing

Key Differences: Desktop vs Web

Trezor Connect
Firmware Binaries
Device Communication
Privacy Features

Desktop

Connect runs in Node.js (main process)
Imported as regular node_module
No Connect files on renderer
IPC proxy in renderer

// Renderer: @trezor/ipc-proxy
TrezorConnect.getAddress(...) → IPC → Main Process

Web

Connect is part of JavaScript bundle
Uses @trezor/connect-web
Runs in browser context
WebUSB for device communication

// Browser: @trezor/connect-web
TrezorConnect.getAddress(...) → WebUSB

See webpack config for web replacement logic.

Desktop

Firmware bundled as application resources
Located in bin/ directory (same level as app.asar)
Read using fs.readFile API
Works offline

Trezor Suite.app/
├── Contents/
│   ├── Resources/
│   │   ├── app.asar
│   │   └── bin/
│   │       └── firmware/

Web

Firmware hosted on CDN
URL: [suite-url]/build/static/connect/data/firmware
Downloaded using fetch API
Requires internet connection

Application Structure

Package Organization

packages/
├── suite-desktop/              # Build target & bundler
│   ├── build-electron/         # Output directory
│   ├── dist/                   # Compiled main process
│   └── package.json            # Electron app dependencies
├── suite-desktop-core/         # Main process logic
│   ├── src/
│   │   ├── main.ts             # Entry point
│   │   ├── modules/
│   │   │   ├── auto-updater.ts
│   │   │   ├── window-manager.ts
│   │   │   ├── tor.ts
│   │   │   └── trezor-connect.ts
│   │   └── ipc-handlers.ts
│   └── scripts/build.ts
├── suite-desktop-ui/           # Renderer-specific UI
├── suite-desktop-api/          # IPC API definitions
└── suite-desktop-native/       # Native module bindings

Important: @trezor/suite-desktop is a container for bundled code. Do not add custom code or dependencies here. Use @trezor/suite-desktop-core instead.

Build Process

Compile TypeScript

# Compile main process
yarn workspace @trezor/suite-desktop-core build

Bundle Renderer

# Build renderer (Suite UI)
yarn workspace @trezor/suite build

Package with Electron Builder

# Build for specific platform
yarn workspace @trezor/suite-desktop build:mac
yarn workspace @trezor/suite-desktop build:win
yarn workspace @trezor/suite-desktop build:linux

Output

Packaged apps in packages/suite-desktop/build-electron/:

macOS: .dmg and .app
Windows: .exe installer
Linux: .AppImage

Environment Configurations

Suite Desktop runs in different modes with separate data directories:

Environment	App ID	Name	Data Dir	Use Case
Production	`com.trezor.suite`	Trezor Suite	`@trezor/suite-desktop`	Released builds
Development	`com.trezor.suite.dev`	Trezor Suite Dev	`@trezor/suite-desktop-dev`	Built dev versions
Local Dev	`com.github.Electron`	Trezor Suite Local	`@trezor/suite-desktop-local`	`yarn suite:dev:desktop`

Data Directory Locations by OS

macOS

~/Library/Application Support/@trezor/suite-desktop/
├── IndexedDB/          # Database
├── Cache/              # Cached resources
├── logs/               # Application logs
└── User Data/          # Settings

Windows

C:\Users\[user]\AppData\Roaming\@trezor\suite-desktop\

Linux

/home/[user]/.config/@trezor/suite-desktop/

You can access your data directory from Suite: Settings → Debug → Wipe app data (link in description).

Development

Running Dev Server

yarn suite:dev:desktop

This command:

Starts Webpack dev server for renderer
Compiles main process with watch mode
Launches Electron with hot reload

React DevTools are available. To use them, reload the renderer process (Ctrl+R / Cmd+R) while DevTools are open.

Keyboard Shortcuts

Action	Shortcut (macOS)	Shortcut (Windows/Linux)
Reload	Cmd+R / F5	Ctrl+R / F5
Hard Reload	Shift+Cmd+R	Shift+Ctrl+R
Restart	Option+F5	Alt+F5
DevTools	Cmd+Shift+I	Ctrl+Shift+I / F12

Debugging

Renderer Process
Main Process
Logging

Chrome DevToolsPress F12 or Cmd+Shift+I to open DevTools.Features:

React component inspection
Network monitoring
Console logs
Redux DevTools (if enabled)

// Enable Redux DevTools
// .env.local
TANSTACK_REACT_QUERY_DEV_TOOLS=true

VSCode Debugging

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Main Process",
      "type": "node",
      "request": "launch",
      "cwd": "${workspaceFolder}",
      "runtimeExecutable": "yarn",
      "args": ["suite:dev:desktop"],
      "outputCapture": "std"
    }
  ]
}

Set breakpoints in main process code
Press F5 to start debugging

See debugging docs for details.

Enable LoggingRun Suite with log level flag:

# macOS/Linux
./Trezor\ Suite.app --log-level=debug

# Windows
"Trezor Suite.exe" --log-level=debug

Log levels: error, warn, info, debugLog Location:

macOS: ~/Library/Logs/Trezor Suite/
Windows: %USERPROFILE%\AppData\Roaming\Trezor Suite\logs\
Linux: ~/.config/Trezor Suite/logs/

See runtime flags for more options.

Build & Distribution

Building for Release

macOS
Windows
Linux

yarn workspace @trezor/suite-desktop build:mac

Output: packages/suite-desktop/build-electron/

Trezor Suite-[version]-arm64.dmg (Apple Silicon)
Trezor Suite-[version]-x64.dmg (Intel)
mac-arm64/Trezor Suite.app
mac-x64/Trezor Suite.app

Signing: Requires Apple Developer certificateNotarization: Automatic if credentials configured

yarn workspace @trezor/suite-desktop build:win

Output: packages/suite-desktop/build-electron/

Trezor Suite Setup [version].exe (installer)
Trezor Suite [version].exe (portable)

Signing: Requires code signing certificateSee signing docs

yarn workspace @trezor/suite-desktop build:linux

Output: packages/suite-desktop/build-electron/

Trezor Suite-[version].AppImage
Trezor Suite-[version].deb (optional)

Running:

chmod +x Trezor-Suite-*.AppImage
./Trezor-Suite-*.AppImage

NixOS:

appimage-run ./Trezor-Suite-*.AppImage

Auto-Updates

Suite Desktop includes built-in auto-update functionality:

Check for Updates

App checks for updates on startup and periodically.

Download in Background

Updates download automatically in the background.

Notify User

User is notified when update is ready to install.

Install on Restart

Update installs when user restarts the application.

Auto-updates use electron-updater with delta updates for efficiency.

Advanced Features

Tor Integration

How It Works

Bundled Tor binary included with app
Automatically started when Tor mode enabled
SOCKS5 proxy on localhost:9050
All network traffic routed through Tor

// Enable Tor in settings
dispatch(toggleTor(true));

Configuration

Tor settings in Suite:

Settings → Application → Tor
Enable/disable Tor
Snowflake bridges for censored networks
Custom bridges

Technical Details

Location: @trezor/suite-desktop-core/src/modules/tor.tsFeatures:

Automatic Tor binary management
Bootstrap progress tracking
Circuit building
Bridge configuration

Anonymous Mode

Run Suite with fresh data on every start (like incognito mode): See anon-mode docs

Extracting Application

For debugging or inspection, you can extract the packaged app:

macOS
Linux
Windows

npx @electron/asar extract \
  ./Trezor\ Suite.app/Contents/Resources/app.asar \
  ./decompiled

# First, run the AppImage to get mount ID
./Trezor-Suite.AppImage
# Note the mount-id from output

# Extract
npx @electron/asar extract \
  ~/.cache/appimage-run/[mount-id]/resources/app.asar \
  ./decompiled

npx @electron/asar extract ^
  "C:\Program Files\Trezor Suite\resources\app.asar" ^
  .\decompiled

Performance Optimization

Code Splitting

Lazy load routes and heavy components

IPC Batching

Batch multiple IPC calls when possible

Asset Optimization

Compress images and bundle only needed resources

Memory Management

Proper cleanup of listeners and subscriptions

Troubleshooting

Build fails

# Clean build
yarn workspace @trezor/suite-desktop-core clean
yarn workspace @trezor/suite clean
yarn build:essential

App won't start

Check logs:

macOS: ~/Library/Logs/Trezor Suite/
Windows: %APPDATA%\Trezor Suite\logs\
Linux: ~/.config/Trezor Suite/logs/

Device not detected

Install/restart Trezor Bridge
Try different USB cable
Check USB permissions (Linux)
Restart Suite

Next Steps

Suite Web Architecture

Compare with web version architecture

Debugging Guide

Advanced debugging techniques

Runtime Flags

Command-line options

Desktop Updates

Update mechanism details

Get Started

Architecture

​Suite Desktop Architecture

​Overview

Electron 40.1.0

React 19.1.0

Redux Toolkit

Node.js 24

​Architecture Layers

​Key Components

​1. Renderer Process

​2. Main Process

​Key Differences: Desktop vs Web

​Desktop

​Web

​Desktop

​Web

​Desktop

​Web

​Desktop

​Web

​Application Structure

​Package Organization

​Build Process

​Environment Configurations

​Development

​Running Dev Server

​Keyboard Shortcuts

​Debugging

​Build & Distribution

​Building for Release

​Auto-Updates

​Advanced Features

​Tor Integration

​Anonymous Mode

​Extracting Application

​Performance Optimization

Code Splitting

IPC Batching

Asset Optimization

Memory Management

​Troubleshooting

​Next Steps

Suite Web Architecture

Debugging Guide

Runtime Flags

Desktop Updates

Build docs developers (and LLMs) love

Suite Desktop Architecture

Overview

Architecture Layers

Key Components

1. Renderer Process

2. Main Process

Key Differences: Desktop vs Web

Desktop

Web

Desktop

Web

Desktop

Web

Desktop

Web

Application Structure

Package Organization

Build Process

Environment Configurations

Development

Running Dev Server

Keyboard Shortcuts

Debugging

Build & Distribution

Building for Release

Auto-Updates

Advanced Features

Tor Integration

Anonymous Mode

Extracting Application

Performance Optimization

Troubleshooting

Next Steps