hanzo-live 0.1.0a1

Real-time AI video generation and streaming tool with WebRTC support

Hanzo Live

Hanzo Live is a tool for running and customizing real-time, interactive generative AI pipelines and models.

🚧 Here be dragons! This project is currently in alpha. 🚧

Features

• Autoregressive video diffusion models
  • StreamDiffusionV2
  • LongLive
• WebRTC real-time streaming
• Low latency async video processing pipelines
• Interactive UI with text prompting, model parameter controls and video/camera/text input modes

...and more to come!

System Requirements

Hanzo Live currently supports the following operating systems:

• Linux
• Windows
• macOS (Apple Silicon with MLX support)

GPU Requirements

NVIDIA GPUs (Linux/Windows):

• Requires a Nvidia GPU with >= 24GB VRAM
• We recommend a driver that supports CUDA >= 12.8
• RTX 3090/4090/5090 recommended (newer generations will support higher FPS throughput and lower latency)
• If you do not have access to a GPU with these specs, we recommend installing on Runpod

Apple Silicon (macOS):

• Supported on M1/M2/M3/M4 Macs with unified memory
• Automatically uses MLX (Apple's machine learning framework) with Metal backend
• No special flags needed - Apple Silicon acceleration is auto-detected

Install

Manual Installation

Install uv which is needed to run the server and Node.js which is needed to build the frontend.

Clone

git clone [e-mail]:hanzoai/live.git
cd live

Build

This will build the frontend files which will be served by the Hanzo Live server.

uv run build

Run

[!IMPORTANT] If you are running the server in a cloud environment, make sure to read the Firewalls section.

This will start the server and on the first run will also download required model weights. The default directory where model weights are stored is ~/.hanzo-live/models.

uv run hanzo-live

The application will automatically detect your hardware:

• NVIDIA GPU (Linux/Windows) → Uses CUDA acceleration
• Apple Silicon (macOS) → Uses MLX/Metal acceleration
• CPU fallback → Use --cpu flag for testing without GPU

After the server starts up, the frontend will be available at http://localhost:8000.

Runpod

Use our RunPod template to quickly set up Hanzo Live in the cloud. This is the easiest way to get started if you don't have a compatible local GPU.

[!IMPORTANT] Follow the instructions in Firewalls to get a HuggingFace access token.

Deployment Steps:

1. Click the Runpod template link: Template

2. Select your GPU: Choose a GPU that meets the system requirements.

3. Configure environment variables:

   • Click "Edit Template"
   • Add an environment variable:
     • Set name to HF_TOKEN
     • Set value to your HuggingFace access token
   • Click "Set Overrides"

4. Deploy: Click "Deploy On-Demand"

5. Access the app: Wait for deployment to complete, then open the app at port 8000

The template will automatically download model weights and configure everything needed.

Firewalls

If you run Hanzo Live in a cloud environment with restrictive firewall settings (eg. Runpod), Hanzo Live supports using TURN servers to establish a connection between your browser and the streaming server.

The easiest way to enable this feature is to create a HuggingFace account and a read access token. You can then set an environment variable before starting Hanzo Live:

# You should set this to your HuggingFace access token
export HF_TOKEN=your_token_here

When you start Hanzo Live, it will automatically use Cloudflare's TURN servers and you'll have 10GB of free streaming per month:

uv run hanzo-live

Contributing

Read the contribution guide.

License

The alpha version of this project is licensed under CC BY-NC-SA 4.0.

You may use, modify, and share the code for non-commercial purposes only, provided that proper attribution is given.

We will consider re-licensing future versions under a more permissive license if/when non-commercial dependencies are refactored or replaced.

---

Copyright © 2025 Hanzo AI Inc. All rights reserved.