How to run the desktop app

zk.money Desktop runs the zk.money wallet on your own computer. A Chrome window opens showing the wallet, and you sign in with the same passkey you use on zk.money. Your accounts and your funds are the same. The only thing that changes is where the website is served from.

For how the app makes your passkey work without the real website, see How the desktop app works.

What you need

  • The zk.money desktop wallet installed.
  • Google Chrome. The app uses the Chrome you already have installed, and other browsers do not work.
  • Your passkey, reachable from this computer. It does not have to be stored on it.

How to use it

  1. Open zk.money Desktop. A Chrome window appears showing the wallet.
  2. Sign in with your passkey. Use the same one you use on zk.money.
  3. Close the window when you have finished. Nothing keeps running in the background.

Where your wallet data is stored

In the app's own data folder on your computer, separate from your normal browser. Deleting the app or its data does not affect your funds. They live on the network, and signing in with your passkey brings back your accounts, balances and payment history.

What to watch for

  • Only install official releases. The app carries a full copy of the wallet, so a tampered copy could act as the real wallet and take your funds. Never download it from a third-party website, and check the file you got against its published fingerprint before you open it.
  • One window at a time. The wallet locks its local database while it runs. Do not open extra tabs on the wallet, and do not open the app twice.
  • The first launch starts fresh. The app keeps its wallet data separate from your normal browser, so there is nothing there the first time you open it. Signing in with your passkey restores your accounts.
  • Anything involving your Ethereum wallet happens in your regular browser. Some actions need a signature from an Ethereum wallet such as MetaMask, which lives in your normal browser rather than in this app. When one comes up, the app opens a page there showing what you are about to approve. Approve it and close the tab, and the app picks the result up on its own.

Reaching your passkey

Your passkey has to be reachable from this computer, but it does not have to be stored on it. The app's Chrome starts signed out of Google and without extensions. Pick the option that matches where your passkey lives.

  • iCloud Keychain. On a Mac it is offered automatically: allow Chrome to use iCloud Keychain the first time it asks, then confirm with Touch ID. On any other computer, choose the QR code option and scan it with your iPhone. If Touch ID does not open your wallet, see Your Mac's passkey does not open your wallet.
  • Google Password Manager. On a Mac, sign the app's Chrome in to the Google account that holds the passkey, as described under Troubleshooting below. See also Your Google Password Manager passkey does not appear.
  • 1Password. Choose the QR code option and scan it with your phone, where the 1Password app holds your passkey. On a Mac, signing the app's Chrome in to Google can bring your 1Password extension with it; unlock it, and it can offer your passkey. If it gives no secret key, see The 1Password extension gives no secret key.
  • A hardware security key. Plug it in.

The phone and security-key options work everywhere. On Linux, which has no built-in passkey storage, use one of them or Google Password Manager. Passkeys covers the rest.

Verifying your download

Every release publishes a file called SHA256SUMS, a list of fingerprints with one per installer. Checking the fingerprint proves the file on your disk is byte-for-byte the published one, and was not corrupted or tampered with on the way.

Download SHA256SUMS from the official GitHub releases page, separate from the website the installer came from. Put it in the same folder as the installer, usually Downloads, then run the command for your platform.

macOS, in Terminal:

cd ~/Downloads
shasum -a 256 --check --ignore-missing SHA256SUMS

You should see the file you downloaded followed by OK.

Linux, in a terminal:

cd ~/Downloads
sha256sum --check --ignore-missing SHA256SUMS

You should see the file you downloaded followed by OK.

Windows, in PowerShell:

cd ~\Downloads
Get-FileHash "zkmoney-desktop-windows-setup.exe"

Open SHA256SUMS in Notepad and compare the long code PowerShell printed with the one next to your file's name. The whole string must be identical, and upper or lower case does not matter.

If the check says FAILED, or the codes differ, do not open the installer. Delete it and download it again from the official download page.

Pointing the wallet at a different service

The wallet talks to a few services on the internet: an Ethereum RPC, an Aztec node, and an enclave. If one is unavailable, you can name a replacement, such as an Ethereum RPC from another provider.

Change them in the wallet, as on the website: Settings > Advanced > Endpoints, or Endpoints at the top of the page before you sign in. If the wallet cannot start, its error screen offers Change endpoints. Save, and the wallet reloads on the new addresses. Leaving a field empty keeps the built-in address.

The app also has a settings page with the same fields, plus the contract configuration. Open it in one of these ways:

  • Automatically. If the app finds at startup that it cannot load zk.money's configuration, it opens the settings page instead of the wallet, with a message explaining what failed.
  • macOS. While the app is running, right-click the zk.money Desktop icon in the Dock and choose Endpoint Settings.
  • Windows and Linux. While the app is running, click the zk.money icon in the system tray, next to the clock. On Windows it may be hidden behind the ^ arrow.

The menu item is unavailable for a moment while the app starts or relaunches. On the settings page, click Save & relaunch wallet.

If you set addresses in an earlier version of the app, enter them again: they are not carried over.

Only use addresses from a source you trust. Never paste one a stranger sent you. Whoever runs an Aztec node you use sees your IP address and can tell which transactions your wallet sends and receives, but not what is in them.

Troubleshooting the desktop app

If the app does not work, one of these is usually the cause:

  • Nothing opens, or the app cannot find Chrome. Install Google Chrome and open the app again. Edge, Firefox and Safari do not work, because they cannot offer your zk.money passkey the way Chrome does.
  • Chrome opens but does not ask for your passkey. See The browser does not offer your passkey.
  • A passkey saved in Google Password Manager does not appear. The app's Chrome starts signed out of Google, so it cannot see it. On a Mac, sign the app's Chrome in: click the wallet window, choose Chrome > Settings in the menu bar, then You and Google, and sign in to the account that holds the passkey. See Your Google Password Manager passkey does not appear for what Chrome may ask next.
  • Your passkey works, but your accounts do not appear. This copy of the app may target a different network than your wallet does. Check that the release you installed matches your wallet and is up to date. Otherwise, see "No wallet for this passkey" and, on a Mac, Your Mac's passkey does not open your wallet.
  • The page shows an error or never finishes loading. Close the Chrome window, quit the app, and open it again. If it still fails, restart your computer and try once more.