zk0 Node Operators Guide

Welcome to the zk0 Node Operators Guide! This document provides everything you need to know to participate in the zk0 federated learning network as a node operator.

What is zk0?

Installation Guide Architecture Overview Running Simulations

zk0 is a federated learning platform for robotics AI, enabling privacy-preserving training of SmolVLA models across distributed clients using real-world SO-100/SO-101 datasets. Node operators contribute their private robotics datasets while maintaining full data privacy.

Getting Started

1. Apply to Become a Node Operator

To join the zk0 network:

  1. Review Requirements: Ensure you have:
    • A private robotics dataset (SO-100/SO-101 compatible)
    • GPU-enabled machine (recommended for training)
    • Stable internet connection
    • Basic familiarity with Docker

  2. Submit Application: Create a new issue using our Node Operator Application Template

  3. Wait for Approval: Our team will review your application and contact you.

2. Install zk0bot CLI

Once approved, install the zk0bot CLI tool:

# One-line installer
curl -fsSL https://zk0.bot/get-zk0bot.sh | bash

This will:

3. Configure Your Environment

Set up required environment variables:

# For Hugging Face datasets (if using HF-hosted private datasets)
export HF_TOKEN="your_huggingface_token"

Note: WandB logging is handled server-side only. Client training does not require WandB credentials.

4. Start Your Client

Launch your zk0 client with your private dataset:

# For Hugging Face datasets
zk0bot client start hf:yourusername/your-private-dataset

# For local datasets
zk0bot client start local:/path/to/your/dataset

Your client will:

Server Operations (For Server Operators)

If you’re running a zk0 server:

# Start the server
zk0bot server start

# Check status
zk0bot status

# View logs
zk0bot server log

# Stop the server
zk0bot server stop

Monitoring and Troubleshooting

Check Status

zk0bot status

View Logs

# Server logs
zk0bot server log

# Client logs
zk0bot client log

Common Issues

Docker not found: Install Docker Desktop or Docker Engine Permission denied: Ensure Docker daemon is running and you have permissions Dataset not found: Verify dataset path/URL and credentials Connection failed: Check internet connection and server availability Installer fails: If curl -fsSL https://get.zk0.bot | bash fails, check GitHub status (api.github.com), ensure curl/wget available, or download manually from https://github.com/ivelin/zk0/releases/latest

Dataset Requirements

Supported Formats

Quality Guidelines

Privacy Considerations

Dynamic Client Joining

Server Behavior

Client Lifecycle

Flower Deployment Engine

Community and Support

Discord

Join our Discord community for support and updates: zk0 Discord

GitHub

Contact

Technical Details

System Requirements

Security

Performance

Advanced Configuration

Custom Docker Compose

The zk0bot CLI uses Flower’s Deployment Engine components. For advanced setups, you can modify the provided Docker Compose files:

Example custom client configuration:

# docker-compose.client.yml (custom)
version: '3.8'
services:
  supernode:
    image: flwr/supernode:1.23.0
    command: ["--insecure", "--isolation", "process", "--superlink", "superlink:9092", "--node-config", "partition-id=${PARTITION_ID} num-partitions=4", "--clientappio-api-address", "0.0.0.0:${NODE_PORT}"]
    ports: ["${NODE_PORT}:${NODE_PORT}"]
    networks: [flwr-network]
  superexec-client:
    build: {context: ., dockerfile: superexec.Dockerfile}
    image: zk0-superexec:0.6.0
    command: ["--insecure", "--plugin-type", "clientapp", "--appio-api-address", "supernode:${NODE_PORT}"]
    environment:
      - DATASET_URI=${DATASET_URI}
      - HF_TOKEN=${HF_TOKEN}
    depends_on: [supernode]
    networks: [flwr-network]
networks:
  flwr-network:
    external: true

Environment Variables

Contributing

We welcome contributions to improve the zk0 platform:

  1. Fork the repository
  2. Create a feature branch
  3. Submit a pull request
  4. Join our Discord for discussion

License

zk0 is open-source software licensed under the Apache 2.0 License.

Last updated: 2025-11-10