# 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](https://rustup.rs) |
| FreeBSD | `pkg install rust` |

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

## Step 1: Install the Wallet

**macOS / Linux / FreeBSD:**

```bash
curl --proto '=https' --tlsv1.2 -sSf https://harmoniis.com/wallet/install | sh
```

**Windows (PowerShell):**

```powershell
irm https://harmoniis.com/wallet/install.ps1 | iex
```

**From source (requires Rust 1.86+):**

```bash
cargo install harmoniis-wallet
```

This compiles and installs the `hrmw` binary. Pre-built binaries include GPU mining support (DX12/Vulkan/Metal) out of the box.

Verify the installation:

```bash
hrmw --version
```

## Step 2: Run the Setup Wizard

```bash
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

Configure OS credential store integration during or after setup:

```bash
# Default — require credential store
hrmw setup --password-manager required

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

# File-only, no credential store
hrmw setup --password-manager off
```

The `required` mode is the default. Supported credential stores:

| Platform | Backend |
|----------|---------|
| macOS | Keychain (with optional iCloud sync) |
| Linux | Secret Service (`secret-tool`) |
| Windows | Credential Manager (`cmdkey`) |

### Changing Password Manager After Setup

`hrmw setup` is idempotent — it is safe to re-run on an existing wallet. It will never destroy key material, contracts, or identities. Only the password manager setting is updated.

```bash
# Remove credentials from OS store
hrmw setup --password-manager off

# Re-store credentials in OS store
hrmw setup --password-manager required
```

After disabling the password manager, back up your master key immediately:

```bash
hrmw key export --format mnemonic
```

## 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:

```bash
hrmw key export --format mnemonic
```

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

```bash
hrmw key export --format hex
```

For a full filesystem backup of all wallet state:

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

## Step 4: Verify Your Installation

```bash
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:

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

List your identity keys to confirm:

```bash
hrmw identity pgp-list
```

Register your identity on the marketplace with a nickname:

```bash
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

```bash
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:

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

### Option C: Fund with Bitcoin

Generate your Bitcoin receive address:

```bash
hrmw bitcoin address
```

Send Bitcoin to that address, then sync:

```bash
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`:

```bash
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:

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

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

### GPU mining support

Pre-built release binaries include GPU support via wgpu (DX12/Vulkan/Metal). Mining backend auto-detection order: CUDA (Linux, source builds only), then wgpu (DX12 on Windows, Vulkan on Linux, Metal on macOS), then CPU.

- **DX12** (Windows): Works with AMD and NVIDIA GPUs. Auto-selected by default.
- **Vulkan** (Linux/Windows): Requires Vulkan-capable GPU and drivers.
- **CUDA** (Linux only): Available in source builds (`cargo install harmoniis-wallet`). Preferred when available.
- **Metal** (macOS): Auto-selected on Apple Silicon and Intel Macs.
- **CPU**: Always available as fallback (uses SIMD with runtime feature detection).

Run `hrmw webminer bench` to verify GPU detection. If you see `GPU: feature-disabled`, upgrade to the latest release: `hrmw upgrade`.

## Next Steps

- [CLI Reference](/docs/wallet/cli-reference) — complete command reference
- [Wallet Overview](/docs/wallet/overview) — architecture and key derivation
- [Quickstart](/docs/quickstart) — end-to-end marketplace walkthrough