Provider onboarding

Earn $OGPU by running OpenReef fine-tuning jobs on the OpenGPU Network.

How it works

1. You register a provider wallet against the OpenReef fine-tune source.

2. OpenGPU provider-suite pulls the OpenReef worker image for your GPU environment.

3. SmartRoute assigns eligible jobs (VRAM, env, reputation, runtime readiness).

4. Your node trains with the qualified engine for its hardware and uploads the adapter.

5. OpenReef validates the artifact and settles on-chain payment.

Hardware

Component	Minimum	Recommended
GPU	8 GB VRAM	16–24 GB+
System RAM	16 GB	32 GB
Disk	50 GB free SSD	100 GB+ NVMe
Network	Stable broadband	100+ Mbps upload
OS	Linux (Ubuntu 22.04+)	Same

NVIDIA (CUDA)

Consumer: RTX 30/40-series with enough VRAM for the jobs you want
Datacenter: A10, A100, H100, etc.
Driver with CUDA 12.6-class user stack (Torch cu126 images)
QLoRA supported

AMD (ROCm)

Examples: RX 7900 / 7800 class; newer RDNA with supported ROCm
The published AMD worker carries a pinned ROCm 7.2 PyTorch stack; the host

must provide a compatible ROCm container runtime

QLoRA not used — worker uses LoRA (stable on ROCm)
Desktop GPUs sharing the display compositor should leave VRAM headroom (host-side OpenReef local mode does this automatically; bare provider nodes are usually headless)

Prerequisites

# Docker
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker
docker run --rm hello-world

GPU runtimes:

NVIDIA: nvidia-container-toolkit
AMD: ROCm + Docker access to devices per OpenGPU provider docs

Wallets

You need:

Wallet	Role
Master	Receives earnings
Provider	Signs provider-suite / on-chain ops

1. Open management.opengpu.network

2. Connect or create the master wallet

3. Create/link a provider wallet

4. Complete master ↔ provider pairing as shown in the dApp

Keys and job claims (D2): OpenReef never bakes private keys into GHCR images.

The source compose runs two services:

1. openreef-signer (CPU) — receives PROVIDER_PRIVATE_KEY from provider-app

(${PROVIDER_PRIVATE_KEY:-}) and performs signed D2 claims against the OpenReef API.

2. finetune (GPU) — no private key; calls http://openreef-signer:8787/v1/claim

over the compose network after an on-chain attempt.

Do not commit keys to git or paste them into chat. Optional: set OPENREEF_SIGNER_TOKEN

on both services for Bearer auth between finetune and signer.

Use the live_data bridge pattern if you publish runtime JSON without embedding secrets

in the source image.

Register on the OpenReef source

1. In the OGPU management UI, find the OpenReef Fine-Tune source.

2. Register with your provider wallet.

3. Choose environment:

- NVIDIA (CUDA)

- AMD (ROCm)

4. Confirm the transaction on-chain.

Images (default tags — always pull):

ghcr.io/asphyksia/finetune-worker:cuda-latest
ghcr.io/asphyksia/finetune-worker:rocm-latest
ghcr.io/asphyksia/openreef-signer:latest

NVIDIA multi-GPU is an explicit, not-yet-promoted path. After a matching image

has passed a real multi-GPU smoke, a provider can reuse the NVIDIA environment:

export FINETUNE_IMAGE=ghcr.io/asphyksia/finetune-worker@sha256:<cuda-multigpu-digest>
export OPENREEF_GPU_COUNT=all
export OPENREEF_TRAIN_ENGINE=axolotl

The defaults remain one NVIDIA GPU with Unsloth. Do not use

cuda-multigpu-latest before its release gate is complete.

The public provider source is public-source/; the product repository keeps a

local mirror under sources/finetune/. Compose uses pull_policy: always where

configured.

Optional: pin image digests (recommended after a green job)

Mutable tags can move. After a successful claim+train smoke, resolve digests and pin:

# From OpenReef monorepo (needs docker + GHCR access)
./scripts/record-image-digests.sh

Then set env for the provider compose stack (provider-app env or shell):

export FINETUNE_IMAGE=ghcr.io/asphyksia/finetune-worker@sha256:<digest>
export OPENREEF_SIGNER_IMAGE=ghcr.io/asphyksia/openreef-signer@sha256:<digest>

Compose accepts these variables; if unset, tags above remain the default.

See operations.md for digest and release evidence.

Optional: qualified image updates while idle

The public worker repo ships a systemd installer for Linux provider nodes:

sudo ./scripts/install-provider-updater.sh \
  --compose-file /opt/openreef-provider/docker-compose-nvidia.yml \
  --project-directory /opt/openreef-provider

Use the AMD compose path on AMD nodes. The updater drains new claims, defers

while training.active exists, validates signer/worker HTTP readiness and

restores the previous local images on failure. It never changes a digest pin;

rolling tags receive only manually qualified releases.

Runtime readiness

On start, the worker writes a report (e.g. /workspace/openreef_runtime.json, schema openreef.runtime.v1) including:

Detected backend (CUDA / ROCm / CPU)
GPU model & VRAM
Torch / HIP / CUDA versions
Selected engine dependency checks (Unsloth or Axolotl)
Explicit issues list

When published via live_data (openreef.provider_live.v1), SmartRoute can exclude unready or mismatched machines before charging end users.

See tools/openreef_live_data_bridge/ for a provider-owned publisher that keeps keys outside the train container.

What jobs look like

Item	Detail
Workload	Supervised fine-tune (instruction data)
Method	LoRA (all); QLoRA (NVIDIA)
Models	Open catalog sizes routed by your VRAM
Timeout	Scales with model size & preset
Failure	OpenReef may requeue; repeated failure → user refund

Stay online, keep disks free for HF cache + checkpoints, and avoid killing the container mid-job.

Pause OpenReef safely

Create the persistent pause marker from the provider source compose project.

For the normal soft pause, leave the source services running:

sudo install -d -m 755 /data/openreef-control
printf '%s\n' 'operator maintenance' | sudo tee /data/openreef-control/paused >/dev/null

The marker survives container recreation. Updated OpenReef signer and worker

images refuse new work while it exists. The worker remains HTTP-healthy and

returns 503 before enqueueing a finetune, which prevents external provider-app

from repeatedly recreating a deliberately paused source. Check the local state

with:

test -f /data/openreef-control/paused && echo paused || echo active
test ! -f /data/openreef-control/training.active && echo idle || echo training
curl -fsS http://127.0.0.1:${PORT}/docs >/dev/null

Resume only when the operator intends to accept work again:

sudo unlink /data/openreef-control/paused
docker compose up -d openreef-signer finetune

This is an OpenReef-owned fail-closed guard. The external OGPU provider-app must

still persist and honor its own user_stopped state so WSS Restart events do

not recreate unrelated source services. Until that upstream behavior is present,

use the marker as the durable OpenReef pause control. Stop source containers

only as a separate hard-stop action when provider-app is also stopped or its

user_stopped state is known to be durable.

Reliability tips

1. VRAM: only register env that matches real hardware.

2. Disk: large model weights need headroom.

3. Updates: allow image pulls so you receive worker fixes.

4. Monitoring: watch openreef_runtime.json / live_data status.

5. Reputation: high fail rates reduce routing preference.

Security expectations

Do not log user datasets or adapters publicly.
Treat job payloads and weights as confidential to the job owner.
Never paste master/provider private keys into chat or git.
Prefer bridge processes for live_data over embedding keys in train images.

Support

Product & community: Telegram OpenReef
Network docs: opengpu.network
Product documentation: documentation index

Checklist

[ ] Docker + GPU runtime working
[ ] Master + provider wallets linked
[ ] Registered on OpenReef source (correct env)
[ ] Image pulls successfully
[ ] Runtime report healthy
[ ] live_data publishing (recommended)
[ ] Enough free disk for models
[ ] Persistent pause control understood and tested

Ready to train on the reef?

Upload a dataset, pick a model and launch your first job — the Dataset Lab validates everything before you spend a credit.

Enter AI Lab