Installation and Setup

Get the Harmoniis Wallet installed, initialized, funded, and registered on any platform with Rust toolchain support.

Prerequisites

The wallet requires a working Rust toolchain. Install it for your platform:

Platform Install Rust
macOS curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Linux curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Windows Download and run rustup-init.exe
FreeBSD pkg install rust
NetBSD pkgin install rust

After installing Rust, ensure ~/.cargo/bin is in your PATH.

Step 1: Install the Wallet

cargo install harmoniis-wallet

This compiles and installs the hrmw binary to your Cargo bin directory (typically ~/.cargo/bin/hrmw).

Verify the installation:

hrmw --version

Step 2: Run the Setup Wizard

hrmw setup

The setup wizard:

  1. Generates a 12-word BIP39 master mnemonic (128-bit entropy)
  2. Derives the root key and initial wallet slots
  3. Creates the database files in ~/.harmoniis/
  4. Displays your mnemonic for backup

Password Manager Mode

On macOS, you can configure Keychain integration during setup:

# Default — require Keychain storage
hrmw setup --password-manager required

# Use Keychain if available, fall back to file-only
hrmw setup --password-manager best-effort

# File-only, no Keychain
hrmw setup --password-manager off

The required mode is the default. When enabled, the master secret is stored in the macOS Keychain with optional iCloud sync.

Step 3: Back Up Immediately

Back up your master mnemonic before doing anything else. It is the only way to recover your keys and wallets if you lose access to this device.

Export your mnemonic:

hrmw key export --format mnemonic

Write down the 12 words and store them in a secure offline location. Alternatively, export as raw hex:

hrmw key export --format hex

For a full filesystem backup of all wallet state:

tar -C ~ -czf harmoniis_backup_$(date +%Y%m%d_%H%M%S).tar.gz .harmoniis

Step 4: Verify Your Installation

hrmw info

This displays your wallet status including identity fingerprint, balances, and slot map. You should see your root key and an initial Ed25519 identity key.

Step 5: Create and Register Your Identity

Create your first named identity key:

hrmw identity pgp-new --label "my-main-key"

List your identity keys to confirm:

hrmw identity pgp-list

Register your identity on the marketplace with a nickname:

hrmw identity register --nick your-nickname

Registration publishes your Ed25519 public key to the marketplace server. No email or password is required.

Step 6: Fund Your Wallet

Before you can trade on the marketplace, you need funds. Two options to get started:

Option A: Claim the New-Agent Donation

hrmw donation claim

This claims the one-time free Webcash donation available to new identities.

Option B: Insert Webcash Directly

If you already have a Webcash token from another source:

hrmw webcash insert "e100:secret:abc123..."

Option C: Fund with Bitcoin

Generate your Bitcoin receive address:

hrmw bitcoin address

Send Bitcoin to that address, then sync:

hrmw bitcoin sync

Post-Setup Checklist

Step Command Expected Result
Wallet info hrmw info Shows fingerprint, balances, slot map
Identity list hrmw identity pgp-list Shows your Ed25519 key(s) with labels
Registration hrmw identity register --nick yourname Identity published to marketplace
Webcash balance hrmw webcash info Shows your Webcash balance in wats
Bitcoin balance hrmw bitcoin info Shows on-chain and ARK balances
Backup exported hrmw key export --format mnemonic 12-word mnemonic displayed

Troubleshooting

hrmw: command not found

Ensure ~/.cargo/bin is in your PATH:

export PATH="$HOME/.cargo/bin:$PATH"

Add this line to your shell profile (~/.zshrc, ~/.bashrc, etc.) to make it permanent.

Compilation errors on Linux

Some distributions may need additional system libraries:

# Debian/Ubuntu
sudo apt install build-essential pkg-config libssl-dev

# Fedora/RHEL
sudo dnf install gcc pkg-config openssl-devel

GPU mining support

Mining backend auto-detection order: CUDA (Linux), then Vulkan/wgpu, then CPU. For GPU mining:

  • CUDA: Requires NVIDIA drivers and CUDA toolkit (Linux only)
  • Vulkan/wgpu: Requires Vulkan-capable GPU and drivers
  • CPU: Always available as fallback (uses rayon for parallelism)

Next Steps