Holochain Deployment — Kangaroo-Electron

Reference for packaging and distributing Holochain hApps as standalone desktop applications using Kangaroo-Electron.

What is Kangaroo-Electron

Kangaroo-Electron (holochain/kangaroo-electron) is Holochain’s official framework for bundling a complete hApp into a standalone cross-platform desktop application. It packages together:

• The Holochain conductor
• lair-keystore (key management)
• Your hApp (.webhapp bundle with DNA + UI)
• An Electron shell

Users receive a single installer (.exe / .dmg / .AppImage) with no Holochain tooling required.

Official repo: https://github.com/holochain/kangaroo-electron

Multi-branch strategy: One branch per supported Holochain version. Always work from the branch matching your hApp’s Holochain version.

Platforms: Windows, macOS, Linux

Branch Selection

Default choice: main-0.6 unless you have a specific reason to use another.

Prerequisites

All platforms

• Rust toolchain (stable)
• Node.js + npm

Linux

• webkit2gtk (for Electron WebView)
• libssl-dev

# Ubuntu/Debian
sudo apt install libwebkit2gtk-4.1-dev libssl-dev

macOS

• Xcode Command Line Tools

xcode-select --install

Windows

• Visual Studio 2019+ with “Desktop development with C++” workload

Repository Setup

# Clone and checkout the right branch
git clone https://github.com/holochain/kangaroo-electron
cd kangaroo-electron
git checkout main-0.6

# Install dependencies (auto-fetches conductor binaries with SHA256 validation)
npm install

No manual compilation needed. Binaries (conductor, lair-keystore) are automatically fetched and verified via SHA256 checksums during npm install.

Artifact Structure

Production: .webhapp bundle in pouch/

A .webhapp is a single archive containing:

1. Your .happ (conductor + DNA + zomes)
2. Your UI assets (HTML/JS/CSS)

Key distinction: .webhapp ≠ .happ. The .happ is backend only. The .webhapp bundles both backend and frontend.

Your hApp build pipeline produces the .webhapp outside Kangaroo. Place the built file here:

pouch/
  your-app.webhapp     ← place your built bundle here

UI icon requirement: Include icon.png (≥ 256×256 px) at the UI root. Missing icon will cause build warnings or failures on some platforms.

Development mode

For dev mode you don’t need a .webhapp. Instead, kangaroo.config.ts accepts:

• happPath — path to your .happ file
• uiPort — port where your UI dev server is running

Configuration

package.json

{
  "name": "your-app-name",
  "version": "0.1.0"
}

electron/config.ts

export const HOLOCHAIN_VERSION = "holochain-0.6.1"; // match your branch
export const APP_ID = "com.yourorg.yourapp";             // reverse-domain identifier
export const PRODUCT_NAME = "Your App Name";              // alphanumeric + hyphens on Windows
export const HAPP_PATH = "pouch/your-app.webhapp";

Windows MSI warning: PRODUCT_NAME must use only alphanumeric characters and hyphens. Spaces and special characters cause MSI packaging failures.

Critical Versioning Semantics

Kangaroo uses a versioning convention that controls user data isolation:

Rule of thumb: Only use patch bumps for backward-compatible updates. Reserve minor/major bumps for intentional breaking changes where data migration is not required (or is handled in-app).

Network Transport (0.6+)

Holochain 0.6 replaced tx5 with iroh as the default network transport.

If your app targets 0.6+, your conductor config must include a relayUrl:

// In your Kangaroo conductor config
relayUrl: "wss://relay.holochain.org"  // official relay, or run your own

Apps migrated from 0.5.x without this update will fail to establish peer connections.

CLI Commands

npm install           # install dependencies + auto-fetch conductor binaries
npm run start         # launch in development mode (hot reload, DevTools available)
npm run kangaroo      # production build for all configured platforms

CI/CD via GitHub Actions

Kangaroo-Electron includes GitHub Actions workflows. Control builds via branch naming:

Required secrets for code-signed builds:

• macOS: APPLE_CERTIFICATE, APPLE_CERTIFICATE_PASSWORD, APPLE_ID, etc.
• Windows: WINDOWS_CERTIFICATE, WINDOWS_CERTIFICATE_PASSWORD

Auto-Update

Kangaroo uses @matthme/electron-updater — a semver-aware fork of electron-updater.

• Checks GitHub releases on app startup
• Respects versioning semantics: patch updates install silently; minor/major present a breaking-change notice
• Requires your GitHub repo to have releases with attached installers (produced by CI)

Other Deployment Options

What NOT to Use

Troubleshooting

Reference: developer.holochain.org/get-started/4-packaging-and-distribution/