Skip to main content
The desktop app is an Electron app that wraps the Linger web app and runs the Computer Daemon as its child process. This page is for contributors who change the app or produce its release packages. To install a released package, see Install the desktop app. The app lives in apps/desktop of the repository. Its AGENTS.md is the source for this page, and it covers the release steps in more detail.

​
Check what you need

You build from a source checkout, so you need the repository’s toolchain.
  • Git, Node.js 26.5 or later (below 27) with pnpm, and Go 1.26.
  • A Linger server the app can reach, such as the one pnpm dev starts. See Contribute.
  • Docker on a Linux host, only to package for macOS or Windows.

​
Build and run the app from source

You build the app from the root of the checkout. The build also compiles the Computer Daemon for this machine.
1

Clone the repository and install dependencies

2

Download Electron

pnpm does not run Electron’s download script, so run it yourself:
If the default download host is unreachable, set ELECTRON_MIRROR first.
3

Build and start the app

The command builds the app and the Daemon, then opens the window.
4

Enter your server address

On the setup screen, enter your Linger server address, such as http://localhost:3000. The app connects this computer and opens Linger.
To build without opening the window, run pnpm --filter @linger/desktop build. To build the Daemon for other platforms, list them in LINGER_DESKTOP_DAEMON_TARGETS:

​
Include Quick Install in a build

Quick Install sets up a local Linger server from the setup screen. A build offers it only when the build includes a Linger source package. Give the build one of these before you run it:
  • LINGER_SOURCE_ARCHIVE_FILE, a source package to bundle in the app.
  • LINGER_SOURCE_ARCHIVE_URL and LINGER_SOURCE_ARCHIVE_SHA256, an HTTPS download and its SHA-256 digest.
A native install also needs the platform’s pinned tools and PostgreSQL. The build reads the tracked apps/desktop/distribution/<target>.json for its target. LINGER_DESKTOP_DISTRIBUTION names a different file. Without a distribution file for the computer, Quick Install turns native off and installs with Docker. The darwin-arm64, win32-x64, and linux-x64 builds bundle PostgreSQL in the app. Put the pinned archives in LINGER_NATIVE_POSTGRES_DIR before the build, which defaults to ~/.cache/linger-desktop. The build fails without them. For development, LINGER_CHECKOUT points local installs at an existing Linger checkout instead of the source package.

​
Build an installer package

Build the app bundle for the target platform, then package it. The macOS and Windows scripts run on a Linux host and call Docker images that you build first. For macOS on Apple silicon:
For Windows:
For Linux:
Each script writes its package to apps/desktop/out/.

​
Sign the packages

Unsigned packages make each user confirm the first launch, so sign release builds when you can.
  • macOS. The script gives the app an ad-hoc signature by default. Pass --developer-id <p12> and --developer-id-password <file> to sign with your Developer ID. Add --notary-key <json> to notarize the app and the .dmg. --notary-key works only with --developer-id.
  • Windows. The setup program and the .zip are not Authenticode-signed, so SmartScreen asks each user to confirm.
  • Linux. The archive is not signed.
When signing changes, update the first-launch steps in Install the desktop app. A notarized macOS package needs none of them.

​
Check a package before you release it

Check each package on a clean computer of its target, not on the build host.
  1. Install the package the way Install the desktop app describes, including the first-launch confirmation.
  2. Run Quick Install with the default choices. It must end on Linger is ready.
  3. Open Linger. It must show the local server, signed in, with this computer connected.
The Computer Daemon inside the app does not update itself, unlike a Computer you connect with linger-computer. A newer app build brings a newer Daemon.

​
Keep learning

Install the desktop app

See the install steps your users follow.

Contribute

Run Linger from source and prepare a pull request.

Architecture overview

See how the desktop app fits with the other services.

Environment variables

Look up each setting in .env.