hanzo-desktop

Hanzo Desktop is a cross-platform desktop application for creating and managing AI agents without code.

Hanzo Desktop - Cross-Platform AI Agent Builder

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-node.md, hanzo/hanzo-mcp.md, hanzo/hanzo-ui.md

Overview

Hanzo Desktop is a cross-platform desktop application for creating and managing AI agents without code. Built with Tauri (Rust backend + React frontend) and managed as an NX monorepo, it provides a visual interface for multi-agent orchestration, MCP tool integration, and hybrid local/cloud AI inference.

The application embeds the Hanzo Node binary (from github.com/hanzoai/node) as a sidecar process, which provides the actual AI agent runtime, P2P networking, and inference capabilities.

Fork lineage: Originally based on dcSpark/shinkai-local-ai-agents (some shinkai-* lib names remain in the codebase).

OSS Info

Repo: github.com/hanzoai/desktop. Package: @hanzo/source v1.1.34. Desktop app: hanzo-desktop v1.1.28. Apache License.

When to use

Building AI agents without writing code (drag-and-drop visual interface)
Running local AI inference with privacy (Ollama integration)
Orchestrating multiple agents that collaborate on complex workflows
Connecting AI agents to external tools via MCP
Cross-platform deployment (Windows, macOS, Linux)

Hard requirements

Node.js >= 20 with npm 10.x
Rust toolchain (for Tauri build)
NX (workspace orchestration, included as devDependency)
Side binaries: Hanzo Node v1.1.20 + Ollama v0.12.3 (downloaded via CI script)

Quick reference

| Item | Value | |------|-------| | Repo | github.com/hanzoai/desktop | | Package name | @hanzo/source v1.1.34 | | Desktop app | hanzo-desktop | | Framework | Tauri (Rust + React) | | Build system | NX + Vite | | Frontend | React 19, TypeScript, Tailwind CSS 4 | | State | Zustand (UI) + React Query (server) | | Testing | Vitest + React Testing Library | | Platforms | Windows 10+, macOS 10.15+, Linux (Ubuntu 20.04+) | | Node.js | >= 20 | | License | Apache-2.0 |

Project structure

desktop/
├── package.json # @hanzo/source v1.1.34 (workspace root)
├── nx.json # NX workspace config
├── tsconfig.base.json
├── eslint.config.mjs
├── mise.toml # Runtime version manager
├── apps/
│ └── hanzo-desktop/ # Main Tauri desktop application
│ └── src-tauri/ # Rust backend + Tauri config
├── libs/
│ ├── hanzo-message-ts/ # Message protocols for Hanzo Node communication
│ ├── hanzo-node-state/ # React Query state management for node data
│ ├── hanzo-ui/ # Reusable React component library
│ ├── hanzo-artifacts/ # Styled UI primitives (Radix + Tailwind)
│ ├── hanzo-i18n/ # i18next internationalization (8 languages)
│ └── shinkai-node-state/ # Legacy state lib (upstream naming)
├── ci-scripts/ # Build, binary download, Ollama repo generation
├── scripts/ # Development utilities
├── tools/ # NX plugins and dev tools
├── patches/ # npm patch-package overrides
├── docs/ # Documentation
└── assets/ # App icons and images

Key features (verified from repo)

No-code agent builder: Visual interface for creating specialized AI agents
Multi-agent orchestration: Deploy teams of agents that collaborate and share context
MCP support: Universal protocol compatibility (Claude, Cursor ecosystem)
Hybrid deployment: Local inference (Ollama), cloud models, or both
Cross-platform: Windows, macOS (Apple Silicon), Linux
Crypto-native: Built-in support for decentralized payments and DeFi interactions
Internationalization: 8 languages (EN, ES, ZH, ZH-HK, KO, JA, ID, TR)
Composio integration: Pre-built app templates via generated repository

Technology stack

| Layer | Technology | |-------|-----------| | Desktop shell | Tauri 2.x (Rust + WebView) | | Frontend | React 19, TypeScript, Vite | | Styling | Tailwind CSS 4, Radix UI, Shadcn/ui patterns | | State management | Zustand (UI state), React Query (server state) | | Build orchestration | NX 22.3 | | AI runtime | Hanzo Node (embedded Rust sidecar) | | Local inference | Ollama (embedded sidecar) | | Testing | Vitest, React Testing Library, Playwright | | i18n | i18next with AI-generated translations | | Forms | React Hook Form + Zod | | Charts | Recharts | | Markdown | Streamdown |

Development

Setup

git clone https://github.com/hanzoai/desktop.git
cd desktop
nvm use
npm ci

Download side binaries

The app embeds Hanzo Node and Ollama as sidecar binaries:

# macOS Apple Silicon
ARCH="aarch64-apple-darwin" \
HANZO_NODE_VERSION="v1.1.20" \
OLLAMA_VERSION="v0.12.3" \
npx ts-node ./ci-scripts/download-side-binaries.ts

# Linux
ARCH="x86_64-unknown-linux-gnu" \
HANZO_NODE_VERSION="v1.1.20" \
OLLAMA_VERSION="v0.12.3" \
npx ts-node ./ci-scripts/download-side-binaries.ts

# Windows
$ENV:ARCH="x86_64-pc-windows-msvc"
$ENV:HANZO_NODE_VERSION="v1.1.20"
$ENV:OLLAMA_VERSION="v0.12.3"
npx ts-node ./ci-scripts/download-side-binaries.ts

Run development server

npx nx serve:tauri hanzo-desktop

Build

npx nx build hanzo-desktop

# With increased memory for large builds
NODE_OPTIONS="--max_old_space_size=8192" npx nx build hanzo-desktop

Test

npx nx test [project-name]
npx nx run-many --target=test
npx nx lint [project-name]

Shared libraries

| Library | Purpose | |---------|---------| | hanzo-message-ts | TypeScript message protocols for communicating with Hanzo Node | | hanzo-node-state | React Query hooks for node data (models, agents, jobs) | | hanzo-ui | Reusable React components and design system | | hanzo-artifacts | Styled UI primitives built on Radix and Tailwind CSS | | hanzo-i18n | Internationalization utilities with AI-generated translations |

Tauri plugins used

The desktop app uses these Tauri 2.x plugins (from package.json):

@tauri-apps/plugin-dialog - Native file/folder dialogs
@tauri-apps/plugin-fs - File system access
@tauri-apps/plugin-http - HTTP client
@tauri-apps/plugin-log - Logging
@tauri-apps/plugin-notification - System notifications
@tauri-apps/plugin-opener - Open URLs/files
@tauri-apps/plugin-os - OS information
@tauri-apps/plugin-process - Process management
@tauri-apps/plugin-shell - Shell command execution
@tauri-apps/plugin-updater - Auto-update

Related Skills

hanzo/hanzo-node.md - The Rust AI node that powers the desktop app backend
hanzo/hanzo-mcp.md - MCP protocol integration
hanzo/hanzo-ui.md - Component library (separate from the desktop-internal hanzo-ui lib)
hanzo/python-sdk.md - Python SDK for programmatic access

Last Updated: 2026-03-13 Category: Hanzo Ecosystem Related: desktop, tauri, react, agents, ai, cross-platform Prerequisites: Node.js 20+, Rust toolchain, NX basics