hanzo-node

Hanzo Node is a Rust-based AI agent infrastructure node that lets you create AI agents without writing code.

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

Rust >= 1.85 (required for std::fs::exists)
Platform: Linux, macOS, or Windows
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.

Related Skills

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