Files
skills/public/hanzo-node.md

7.6 KiB

Hanzo Node - Rust AI Agent Infrastructure

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-desktop.md, hanzo/hanzo-mcp.md, hanzo/python-sdk.md

Overview

Hanzo Node is a Rust-based AI agent infrastructure node that lets you create AI agents without writing code. It provides local AI inference, peer-to-peer networking, MCP tool support, and an HTTP API for agent orchestration. It is the backend engine that powers the Hanzo Desktop application.

Workspace version 1.1.20, Rust edition 2021, requires Rust >= 1.85.

OSS Info

Repo: github.com/hanzoai/node. Companion desktop frontend: github.com/hanzoai/desktop.

When to use

  • Running a local AI agent node for inference and tool execution
  • Building codeless AI agents with task scheduling and automation
  • Embedding AI capabilities into applications via the HTTP API
  • Participating in the Hanzo peer-to-peer compute network
  • Developing against the Hanzo agent protocol (MCP, libp2p, DID)

Hard requirements

  1. Rust >= 1.85 (required for std::fs::exists)
  2. Platform: Linux, macOS, or Windows
  3. SQLite (bundled via rusqlite)

Quick reference

Item Value
Language Rust
Edition 2021
Version 1.1.20
Repo github.com/hanzoai/node
Binary hanzo-bin/hanzo-node
CLI hanzo-bin/hanzoai
Makefile binary hanzoai (renamed from hanzod on 2026-03-28)
Build cargo build
Test IS_TESTING=1 cargo test -- --test-threads=1
API port 3690
P2P port 3691
Config hanzo.toml
License Apache-2.0

Project structure

node/
├── Cargo.toml # Workspace root
├── Cargo.lock
├── Makefile
├── hanzo.toml # Node configuration
├── hanzo-bin/
│ ├── hanzo-node/ # Main node binary
│ ├── hanzoai/ # CLI binary
│ └── hanzo-migrate/ # Database migration tool
├── hanzo-libs/ # Library crates (~40 crates)
│ ├── hanzo-api/ # HTTP API layer
│ ├── hanzo-config/ # Configuration management
│ ├── hanzo-database/ # Database abstraction
│ ├── hanzo-db-sqlite/ # SQLite backend
│ ├── hanzo-did/ # Decentralized identity
│ ├── hanzo-embed/ # Embedding generation
│ ├── hanzo-fs/ # File system operations
│ ├── hanzo-http-api/ # HTTP API endpoints
│ ├── hanzo-identity/ # Identity management
│ ├── hanzo-jobs/ # Job execution
│ ├── hanzo-job-queue-manager/ # Job queue
│ ├── hanzo-libp2p/ # P2P networking (libp2p 0.55)
│ ├── hanzo-libp2p-relayer/ # P2P relay node
│ ├── hanzo-llm/ # LLM provider integrations
│ ├── hanzo-mcp/ # Model Context Protocol
│ ├── hanzo-messages/ # Message protocol definitions
│ ├── hanzo-mining/ # Compute mining
│ ├── hanzo-models/ # Model management
│ ├── hanzo-model-discovery/ # Model discovery
│ ├── hanzo-pqc/ # Post-quantum cryptography
│ ├── hanzo-vm/ # Virtual machine
│ ├── hanzo-compute/ # Compute orchestration
│ ├── hanzo-ai-format/ # AI data formats
│ ├── hanzo-runner/ # Task runner
│ ├── hanzo-runtime/ # Runtime environment
│ ├── hanzo-tools/ # Tool definitions
│ ├── hanzo-tools-runner/ # Tool execution engine
│ ├── hanzo-wasm/ # WebAssembly support
│ └── hanzo-wasm-runtime/ # WASM runtime
├── hanzo-test-framework/ # Testing framework
├── hanzo-test-macro/ # Test macros
├── cloud-node/ # Cloud node variant
├── contracts/ # Associated smart contracts
├── docker/ # Docker configurations
├── docker-build/ # Docker build scripts
├── docs/ # Documentation
├── examples/ # Usage examples
├── knowledge/ # Knowledge base files
├── scripts/ # Build and run scripts
└── HIPs/ # Hanzo Improvement Proposals

Workspace crates

The workspace contains approximately 40 crates in hanzo-libs/. Key groupings:

Core infrastructure: hanzo-api, hanzo-config, hanzo-database, hanzo-db-sqlite, hanzo-http-api, hanzo-fs, hanzo-messages, hanzo-runtime

AI / ML: hanzo-llm, hanzo-embed, hanzo-models, hanzo-model-discovery, hanzo-ai-format, hanzo-mcp

Networking: hanzo-libp2p, hanzo-libp2p-relayer, hanzo-compute, hanzo-mining

Identity / Security: hanzo-did, hanzo-identity, hanzo-pqc

Execution: hanzo-vm, hanzo-wasm, hanzo-wasm-runtime, hanzo-runner, hanzo-tools, hanzo-tools-runner, hanzo-jobs, hanzo-job-queue-manager

Excluded from build (noted in Cargo.toml comments): hanzo-db, hanzo-hmm, hanzo-kbs, hanzo-l2, hanzo-consensus, hanzo-sheet, hanzo-simulation, hanzo-tests -- these have external path dependencies or incomplete implementations.

Configuration (hanzo.toml)

The node is configured via hanzo.toml at the repo root:

[node]
ip = "0.0.0.0"
port = 3691 # P2P port
api_ip = "0.0.0.0"
api_port = 3690 # HTTP API port

[embeddings]
use_native_embeddings = true
use_gpu = true
default_embedding_model = "qwen3-embedding-8b"

[database]
path = "./storage/db.sqlite"

[security]
pqc_enabled = false
privacy_tier = 0 # 0-4: Open to TEE-I/O

[tools]
mcp_enabled = true
javascript_runtime = "deno"
python_runtime = "uv"

[llm_providers]
ollama_base_url = "http://localhost:11434"
lm_studio_base_url = "http://localhost:1234"

See the full hanzo.toml in the repo for all options including logging, performance tuning, wallet configuration, and development settings.

Important: Deno binary (2026-03-27)

  • The 112MB deno binary has been removed from git and LFS tracking
  • hanzo-bin/hanzo-node/shinkai-tools-runner-resources/deno is in .gitignore
  • Deno must be installed separately on the host or in the container at build time
  • Do NOT commit the deno binary back into the repo

Building and running

git clone https://github.com/hanzoai/node.git
cd node
cargo build

# Quick start with localhost script
sh scripts/run_node_localhost.sh

# To reset, delete the storage/ folder and rebuild

Testing

# Run all tests (must be from repo root)
IS_TESTING=1 cargo test -- --test-threads=1

# Run a specific test
IS_TESTING=1 cargo test tcp_node_test -- --nocapture --test-threads=1

# Dockerized tests
docker build -t testing_image -f .github/Dockerfile .
docker run --entrypoint /entrypoints/run-main-cargo-tests.sh testing_image

API

The node exposes an HTTP API on port 3690 with OpenAPI documentation:

# Swagger UI (requires --features hanzo_node/swagger-ui)
http://{NODE_IP}:3690/v2/swagger-ui/

# Generate OpenAPI schemas
cargo run --example generate_openapi_docs
# Output goes to docs/openapi/

Key dependencies

Dependency Version Purpose
tokio 1.36 Async runtime
libp2p 0.55.0 P2P networking (noise, yamux, tcp, quic, relay)
rmcp 0.8 Model Context Protocol
warp 0.3.7 HTTP server
rusqlite 0.32.1 SQLite (bundled)
ed25519-dalek 2.1.1 Cryptographic signatures
serde / serde_json 1.0 Serialization
reqwest 0.11.27 HTTP client

Docker

Docker build files are in docker/ and docker-build/. The node is designed to run as a single binary with minimal dependencies.

  • hanzo/hanzo-desktop.md - Desktop frontend (Tauri + React) that wraps this node
  • hanzo/hanzo-mcp.md - MCP protocol and tools
  • hanzo/python-sdk.md - Python client SDK
  • hanzo/hanzo-evm.md - EVM execution engine (separate Rust project)

Last Updated: 2026-03-27 Category: Hanzo Ecosystem Related: rust, ai, infrastructure, libp2p, mcp, agents Prerequisites: Rust >= 1.85, basic understanding of AI agent systems