Install

Right now you install Canonical by building it from source. There is no one-click installer and no app — you compile two small programs and the second step sets them running. Plan on a few minutes for that first build.

Before you start, make sure you have:

A Mac or a Linux machine. On Windows, do everything inside WSL2 — the wallet talks over Unix sockets and has no native Windows build.
Rust 1.92.0 (the version is pinned for you in the repo).
Node.js 24+ (only used by the packaging step).
A terminal you are at home in. Everything happens there.

Build it and turn it on#

terminal

git clone <repository-url>
cd canonical-wallet
cargo build --release -p canonicalwalletd -p canonicalwallet
npm run package:release
./dist/release-core/install-core.sh --data-dir ~/.canonical \
  --service launchd --enable-service      # macOS

On Linux, change only the last line's flag:

terminal

./dist/release-core/install-core.sh --data-dir ~/.canonical \
  --service systemd-user --enable-service  # Linux

The first cargo build compiles everything, so it takes a few minutes; after that it is fast. When the installer finishes, the wallet is already running in the background as a service — there is nothing else to start.

What that installer just did#

It runs as you, needs no sudo, and in plain terms it:

Put the two programs on your PATH (in ~/.local/bin).
Set up a private folder for your wallet's data and created your access tokens — a full-access one (operator.token) and a read-only one for agents (mcp.token).
Registered the wallet as a background service and started it, because you passed --service ... --enable-service.

It will never overwrite tokens you already have, so re-running it later to update the programs is safe. See everything it can do with:

terminal

./dist/release-core/install-core.sh --help

Prefer to watch it run instead?#

While you are learning, it can be nice to see the wallet in a terminal instead of hiding it as a service. Skip the service flags and run it yourself:

terminal

# Terminal 1 — leave this open
canonicalwalletd init --data-dir ~/.canonical            # first time only
canonicalwalletd serve --clients-file ~/.canonical/clients.json

Everything works the same; the wallet just stops when you close that terminal.

Where your wallet lives on disk#

Inside the folder you chose (~/.canonical here):

File	What it is
vault.json	Your keys, encrypted with your password.
state.json	Your accounts, rules, pending transactions, chains.
audit.jsonl	The tamper-proof history of everything that happened.
clients.json, *.token	Who is allowed in, and with what access.

Updating later#

terminal

git pull
cargo build --release -p canonicalwalletd -p canonicalwallet
npm run package:release
./dist/release-core/install-core.sh --data-dir ~/.canonical   # new programs, same data

Restart the service afterward. Your wallet, your pending transactions, their approvals, and the history all carry over untouched — the wallet upgrades its own files automatically.

If you downloaded a release instead of building#

Check it is genuine before running anything:

terminal

shasum -a 256 --check SHA256SUMS     # macOS
sha256sum -c SHA256SUMS              # Linux