Installing the provider agent
Requirements, installation, the mzgrid-provider CLI, running the agent as a systemd service, and how jobs are isolated on your machine.
The mzgrid-provider agent connects your NVIDIA GPUs to the MZGrid network. It detects your hardware, benchmarks it, registers you on-chain, accepts jobs, runs them in isolated containers and reports usage so you get paid in MZG. Before you start, read the economics on the Become a provider page and the rules in Lock & exit and Slashing.
Requirements
| Requirement | Details |
|---|---|
| Operating system | 64-bit Linux. Ubuntu 22.04/24.04 LTS and Debian 12 are the most tested. |
| GPU | One or more supported NVIDIA GPUs — see the GPU catalogue. |
| NVIDIA driver | A recent datacenter or Game Ready driver with nvidia-smi working. See the NVIDIA driver documentation. |
| Docker | Docker Engine with the NVIDIA Container Toolkit so that docker run --gpus works. See the Docker Engine install guide. |
| Node.js | Node.js 24 to run the agent. |
| Network | Open outbound HTTPS to the MZGrid API and a Base RPC endpoint. Inbound reachability on the ports you publish for job endpoints. Stable bandwidth; your measured bandwidth is shown on your offers. |
| Wallet | A Base wallet the agent controls, holding a little ETH on Base for gas (register, acceptJob, requestExit, withdrawLocked). You do not need MZG to start. |
| Disk | Enough free space for container images and model weights. 200 GB of fast SSD per GPU is a sensible minimum for LLM templates. |
Verify the GPU runtime before installing the agent:
nvidia-smi
docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smiBoth commands should list your GPUs.
Install
npm install -g @mzgrid/provider-agent
mzgrid-provider --versionSet up and register
1. init — create or import a key, choose region and pricing
mzgrid-provider initinit creates a new key or imports an existing one into an encrypted keystore at ~/.mzgrid/keystore.json, asks for your region (for example eu-central) and your price per GPU-hour for each detected SKU, pre-filled with the catalogue reference price. Fund the printed address with a small amount of ETH on Base for gas.
init also asks whether you accept the MZGrid Terms of Service, Privacy Policy and Risk Disclosure (current version 2026-11-05), defaulting to No. Your answer and the time are saved in ~/.mzgrid/config.json. For unattended installs, pass --accept-terms to accept without the prompt:
mzgrid-provider init --accept-termsImportant
The keystore holds the key that receives your earnings and controls your locked MZG. Back it up and its passphrase separately. Anyone with both can request your exit and withdraw your lock after 10 days.
2. detect — map GPUs to SKUs
mzgrid-provider detectRuns nvidia-smi --query-gpu=... and maps each GPU to a catalogue SKU, printing its UUID, VRAM and driver version. GPUs that do not match a supported SKU are ignored.
3. benchmark — measure FP16 throughput
mzgrid-provider benchmarkRuns an FP16 matrix-multiply benchmark on each GPU, using PyTorch when available and a bundled CUDA sample otherwise. Results must be within 70–115% of the SKU's reference to be verified. See Benchmark & verification.
4. register — go live
mzgrid-provider registerCalls register(metadataURI) on the ProviderRegistry, registers your machines and pricing with the coordinator (POST /v1/providers/register), and submits your benchmark results. Once your machines are verified, your offers appear in the marketplace.
Registration requires accepting the current Terms of Service. If you did not accept them during init (or the terms have been updated since), register stops with an error before doing anything. Run mzgrid-provider register --accept-terms to accept and register in one step.
5. start — run the job loop
mzgrid-provider start --runtime dockerThe agent sends a heartbeat every 30 seconds, long-polls for jobs, calls acceptJob on-chain, pulls and runs the container, streams logs, reports usage every 60 seconds and reports the result when the job finishes.
Command reference
| Command | Description |
|---|---|
mzgrid-provider init | Create or import a key (encrypted keystore at ~/.mzgrid/keystore.json), choose region and per-SKU pricing, and accept the Terms of Service (prompt, or --accept-terms). |
mzgrid-provider detect | Detect GPUs via nvidia-smi and map them to SKUs. |
mzgrid-provider benchmark | Run the FP16 benchmark. --simulate produces catalogue reference ±5% for testing against a local or testnet coordinator. |
mzgrid-provider register | On-chain register, coordinator registration and benchmark submission. Requires accepted Terms; --accept-terms accepts them now. |
mzgrid-provider start | Run the job loop. --runtime docker (default) or --runtime simulate for testing. |
mzgrid-provider status | Show locked MZG, liquid earnings, reliability and running jobs. |
mzgrid-provider exit | Call requestExit(); starts the 10-day exit delay. |
mzgrid-provider withdraw | Call withdrawLocked() once the delay has passed and no jobs are active. |
Run as a systemd service
Keep the agent running across reboots with a systemd unit. Create a dedicated user that belongs to the docker group, then save this as /etc/systemd/system/mzgrid-provider.service:
[Unit]
Description=MZGrid provider agent
After=network-online.target docker.service
Wants=network-online.target
Requires=docker.service
[Service]
Type=simple
User=mzgrid
Group=mzgrid
SupplementaryGroups=docker
EnvironmentFile=/etc/mzgrid/provider.env
ExecStart=/usr/bin/mzgrid-provider start --runtime docker
Restart=always
RestartSec=5
LimitNOFILE=65536
[Install]
WantedBy=multi-user.target/etc/mzgrid/provider.env holds the keystore passphrase and must be readable only by the service user:
sudo install -d -m 0750 -o mzgrid -g mzgrid /etc/mzgrid
echo 'MZG_KEYSTORE_PASSWORD=...' | sudo tee /etc/mzgrid/provider.env > /dev/null
sudo chmod 0600 /etc/mzgrid/provider.env && sudo chown mzgrid:mzgrid /etc/mzgrid/provider.env
sudo systemctl daemon-reload
sudo systemctl enable --now mzgrid-provider
journalctl -u mzgrid-provider -fIsolation model
Every job runs in its own Docker container pinned to the assigned GPU with docker run --gpus device=<uuid> --rm. The agent applies these restrictions:
- No host network. Containers use an isolated network; only the template's declared ports are published.
- Read-only root filesystem where the image allows it, with a per-job tmpfs for scratch data.
- Resource limits on CPU, memory and process count derived from the offer's specification.
- No privileged mode and no extra capabilities.
- Secrets via environment only. Customer environment variables are passed only to that job's container and are not written to the agent's logs.
- Containers are removed when the job ends (
--rm).
This protects your host from customer workloads and customers from each other. It is not a confidential-computing boundary: as the machine operator you have physical and root access. Customers are told this explicitly in the Security model. You must never inspect, copy or tamper with customer workloads; doing so is fraud and is subject to slashing.