Installation

Get hwLedger running on your system.

Requirements

• Rust: 1.70+ (MSRV)
• OS: macOS 12+, Windows 10+, Linux (Ubuntu 20.04+)
• RAM: 8 GB minimum (16 GB recommended)
• GPU (optional): NVIDIA, AMD, or Apple Silicon for inference

Build from Source

Clone, build, and verify installation

Keyframes (0 — VLM-friendly)

Loading manifest…

Download MP4Download GIF Keyframes (repo)

1. Clone the repository

git clone https://github.com/KooshaPari/hwLedger.git
cd hwLedger

2. Install Rust (if not already installed)

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

3. Build the CLI

cargo build --release

The binary will be at target/release/hwledger-cli.

4. (Optional) Build native GUI

macOS (SwiftUI)

cd apps/macos
xcodebuild -scheme HwLedger -configuration Release

Windows (WinUI 3)

cd apps/windows
dotnet publish -c Release

Linux (Qt 6)

cd apps/linux-qt
cargo build --release

Quick Test

Run the planner to verify installation:

./target/release/hwledger-cli plan --model llama-2-70b

Expected output (example):

hwLedger Capacity Planner

Model: llama-2-70b
├─ Attention: MHA
├─ Num layers: 80
├─ Hidden size: 4096
└─ Num heads: 64

KV Cache (batch_size=1, seq_length=4096, dtype=float16):
├─ Per layer: 67 MB
├─ Total: 5.3 GB

Model Weights (dtype=float16):
├─ Parameters: 70 B
├─ Size: 140 GB

Total VRAM needed: ~146 GB

Installation via Homebrew (coming soon)

Once released, install via Homebrew:

brew install hwledger

Docker (coming soon)

Run in Docker:

docker run -it --gpus all ghcr.io/kooshapari/hwledger:latest

Next Steps

• Plan a model — understand VRAM and throughput
• View architecture — system design overview
• Fleet setup — configure heterogeneous hardware
• Build from source — contribute to hwLedger

Troubleshooting

Rust compilation fails

Ensure you have the latest Rust:

rustup update

macOS: Xcode not found

Install Xcode command-line tools:

xcode-select --install

Windows: .NET 9 not found

Install .NET 9 SDK.

Linux: Qt 6 not found

# Ubuntu/Debian
sudo apt-get install qt6-base-dev qt6-qml-dev

# Fedora
sudo dnf install qt6-qtbase-devel qt6-qtdeclarative-devel

Support

• GitHub Issues
• Documentation
• Research