Skip to main content

Connecting GPU to Cluster

How do I connect my GPU to the ZkAGI cluster?​

You can connect a CPU or GPU to the ZkAGI cluster using Docker on Windows or Ubuntu. Pull the appropriate Docker image, run the container with your wallet address, and click Connect in the ZkAGI interface.

Prerequisites

  • Docker installed and running.
  • For GPU on Linux: NVIDIA drivers + NVIDIA Container Toolkit.
  • For GPU on Windows: recent NVIDIA drivers and Docker Desktop (WSL2 backend).

How do I set up CPU connection to ZkAGI?​

CPU connection requires Docker Desktop (Windows) or Docker Engine (Ubuntu), pulling the CPU image, and running a container with your wallet address. The container initializes in about 20 seconds before you can connect.

1) Download Docker​

Install Docker Desktop (Windows) or Docker Engine (Ubuntu) from the official Docker website.

2) Open a terminal​

  • Windows: Command Prompt (CMD)
  • Ubuntu: Terminal

3) Pull the CPU image​

docker pull zkagi/connect2cluster:latest

4) Run the container (CPU)​

Replace YOUR_WALLET_ADDRESS with your actual address.

docker run -dit \
  -e "walletAddress=YOUR_WALLET_ADDRESS" \
  --privileged \
  --network host \
  zkagi/connect2cluster:latest

Note (Windows): --network host behaves differently on Docker Desktop for Windows. If host networking isn't supported, omit --network host and ensure required ports are exposed via -p <host:container> as needed.

5) Connect​

  • Wait ~20 seconds for the container to initialize.
  • Open the ZkAGI interface and click Connect.

How do I set up GPU connection to ZkAGI?​

GPU connection requires Docker, verified NVIDIA drivers (check with nvidia-smi), and the GPU-specific Docker image. Run the container with the --gpus all flag and your wallet address to enable GPU passthrough.

1) Download Docker​

Install Docker Desktop (Windows) or Docker Engine (Ubuntu).

2) Check GPU and drivers​

Open CMD/Terminal and verify your GPU:

nvidia-smi

If your driver version is > 552, consider installing a compatible version as required by your environment.

3) Pull the GPU image​

docker pull zkagi/connect2cluster:gpu-latest

4) Run the container (GPU)​

Replace YOUR_WALLET_ADDRESS with your actual address.

docker run -dit \
  -e "walletAddress=YOUR_WALLET_ADDRESS" \
  --privileged \
  --network host \
  --gpus all \
  zkagi/connect2cluster:gpu-latest

Linux (NVIDIA Toolkit): If --gpus all fails, install/configure nvidia-container-toolkit.

Windows: Ensure WSL2, NVIDIA drivers with WSL support, and Docker Desktop GPU integration are enabled.

5) Connect​

  • Wait ~20 seconds for startup.
  • Open the ZkAGI interface and click Connect.

How do I disconnect or restart my ZkAGI cluster connection?​

To disconnect, stop any running container created from the zkagi/connect2cluster images using Docker commands. To restart, use docker restart on previously stopped containers.

Disconnecting​

Stop any running container created from the zkagi/connect2cluster images.

Windows (CMD):

FOR /F "tokens=*" %i IN ('docker ps -q --filter "ancestor=zkagi/connect2cluster"') DO docker stop %i

Ubuntu (bash):

docker ps -q --filter "ancestor=zkagi/connect2cluster" | xargs docker stop

Restarting​

Restart a previously stopped container created from the zkagi/connect2cluster images.

Windows (CMD):

FOR /F "tokens=*" %i IN ('docker ps -a -q --filter "ancestor=zkagi/connect2cluster"') DO docker restart %i

Ubuntu (bash):

docker ps -a -q --filter "ancestor=zkagi/connect2cluster" | xargs -I {} docker restart {}

How do I troubleshoot ZkAGI cluster connection issues?​

Common issues include host networking incompatibility on Windows, GPU passthrough failures, and wallet address errors. Each problem has a specific fix involving Docker flags, NVIDIA toolkit installation, or verifying container GPU access.

  • Cannot use --network host on Windows: Remove that flag and publish required ports with -p.
  • --gpus all fails: Install NVIDIA drivers and nvidia-container-toolkit (Linux) or enable GPU support in Docker Desktop (Windows).
  • No GPU detected in container: Run the following to verify Docker can see the GPU: 
    docker run --rm --gpus all nvidia/cuda:12.2.0-base-ubuntu22.04 nvidia-smi
  • Wallet not recognized: Ensure walletAddress is passed exactly and the value is correct.