Nexus Client

Overview

nexus-client is a command-line tool that turns any machine with a spare GPU and a local OpenAI-compatible model server (Ollama) into a compute provider node on the Nexus network. You run it, it connects to the gateway, and your GPU starts answering inference jobs for paying clients.

The loop is simple: stake GNN to earn the gateway's trust, serve the inference jobs the gateway dispatches to your node, and earn GNN — paid out per epoch. The client is fully open source, so you can read exactly what runs on your machine: https://github.com/Dev916/nexus-client.

How it works

Your node sits between your hardware and the network. It opens a WebSocket to the Nexus gateway, proves it has staked GNN on Solana, and then relays each dispatched job to your local Ollama server — streaming the result back. The gateway meters the work and the chain settles the payout.

flowchart LR
  U["You · GPU + Ollama"] --> N["nexus-client"]
  N -->|"WS handshake"| G["Nexus Gateway"]
  N -->|"stake GNN"| C[("Solana")]
  G -->|"verify stake"| C
  G -->|"dispatch job"| N
  N -->|"inference"| O["Ollama"]
  G -->|"payout GNN"| C
  classDef client fill:#0d1419,stroke:#00d4ff,color:#c9f4ff;
  classDef gw fill:#150f24,stroke:#b388ff,color:#e9ddff;
  classDef chain fill:#241a08,stroke:#ffbd2e,color:#ffe9b3;
  classDef up fill:#0a1f14,stroke:#27c93f,color:#bdf5cf;
  class U,N client;
  class G gw;
  class C chain;
  class O up;
          

Prerequisites

Before you start, make sure you have:

• A GPU with enough VRAM for the model you plan to serve — see the eligible model classes for what your card can handle.
• Ollama installed and running, with at least one model pulled.
• A Solana wallet holding SOL (for transaction fees) and ≥ 1 GNN (the mainnet stake minimum).

Install

Download the prebuilt binary for your platform from the releases page. There is no installer and no package-manager step — grab the single file and run it.

# macOS (Apple Silicon)
curl -LO https://github.com/Dev916/nexus-client/releases/latest/download/nexus-client-macos-arm64

# macOS (Intel)
curl -LO https://github.com/Dev916/nexus-client/releases/latest/download/nexus-client-macos-x64

# Linux
curl -LO https://github.com/Dev916/nexus-client/releases/latest/download/nexus-client-linux-x64

# Windows (PowerShell)
curl.exe -LO https://github.com/Dev916/nexus-client/releases/latest/download/nexus-client-windows-x64.exe

Verify your download against the published checksums (SHA256SUMS), then make the binary executable:

# Download the checksums and verify
curl -LO https://github.com/Dev916/nexus-client/releases/latest/download/SHA256SUMS
# macOS / Linux
shasum -a 256 -c SHA256SUMS
# make it executable
chmod +x nexus-client-*

Quickstart

Five commands from zero to earning. Replace llama3.2 with whichever eligible model your GPU can serve.

# 1. Pull an eligible model with Ollama
ollama pull llama3.2

# 2. Initialize your node. --model MUST match the Ollama model name exactly.
#    Use --wallet import <path|base58> for a funded wallet, or omit for a fresh one.
nexus-client init --model llama3.2 --wallet import ./wallet.json

# 3. Stake GNN on-chain to the network treasury (mainnet, 1 GNN minimum)
nexus-client stake --amount 1

# 4. Start serving jobs and earning
nexus-client start

# 5. (anytime) Check what you've earned
nexus-client earnings

init

nexus-client init bootstraps your node. It creates the client directory (default ~/.nexus-client, override with --dir) and writes three files: a node_key, a wallet.json, and a config.toml.

nexus-client init [--dir ~/.nexus-client] [--model hermes-3] \
  [--wallet new|import <path|base58>]

# Fresh Solana wallet — you must fund it before you can stake
nexus-client init --model llama3.2 --wallet new

# Import a funded wallet (a solana-keygen 64-byte JSON path, or a base58 secret)
nexus-client init --model llama3.2 --wallet import ./wallet.json

--wallet new generates a brand-new Solana wallet — remember to send it SOL and at least 1 GNN before staking. --wallet import accepts either a solana-keygen 64-byte JSON keypair file path or a base58-encoded 64-byte secret, so you can reuse a wallet you already fund.

flowchart TD
  I["nexus-client init"] --> K["node_key (Ed25519 seed)"]
  I --> W["wallet.json (Solana keypair)"]
  I --> CF["config.toml (model · upstream · gateway)"]
  classDef client fill:#0d1419,stroke:#00d4ff,color:#c9f4ff;
  class I,K,W,CF client;
          

Keys & wallet

Your node holds two distinct keys with two different jobs. Keeping them straight saves a lot of confusion.

Node key

node_key is an Ed25519 32-byte seed. It identifies your node to the gateway during the WebSocket handshake. It is not a wallet and holds no funds — it is purely your node's identity on the network.

Wallet

wallet.json is a standard Solana 64-byte keypair. It is used to (a) send the on-chain stake transaction and (b) prove ownership when you read earnings — the gateway issues a wallet-scoped JWT via Sign-In-With-Solana (SIWS) so only the owner can see a node's payouts.

stake

nexus-client stake --amount <GNN> registers your node on-chain so the gateway will trust it. First it fetches GET /api/compute/config for the GNN mint, the treasury address, the minimum, and the active network. It then sends an on-chain GNN transfer_checked to the treasury's associated token account, and finally records the stake via POST /api/compute/stake (including the tx_signature).

nexus-client stake --amount <GNN> [--rpc <url>] [--dir]

# Mainnet minimum is 1 GNN
nexus-client stake --amount 1

# Use a reliable RPC if sendTransaction is rate-limited
nexus-client stake --amount 1 --rpc https://your-rpc.example/v1

The minimum is 1 GNN on mainnet. A given transaction signature can be recorded only once — staking is replay-protected by a unique index on the signature. Public RPCs frequently rate-limit sendTransaction; pass --rpc with a reliable endpoint if a stake times out.

sequenceDiagram
  participant CLI as nexus-client
  participant G as Gateway
  participant C as Solana
  CLI->>G: GET /api/compute/config
  G-->>CLI: mint, treasury, min, network
  CLI->>C: transfer_checked GNN → treasury ATA
  C-->>CLI: tx signature (finalized)
  CLI->>G: POST /api/compute/stake (tx_signature)
  G->>C: verify transfer on-chain
  G-->>CLI: staked: meets minimum
          

start

nexus-client start brings your node online. It opens the gateway WebSocket, signs the handshake with your node_key, obtains a wallet JWT via Sign-In-With-Solana, and authenticates. If the node's recorded stake meets the minimum it is admitted and enters the serving loop; otherwise the gateway rejects it with not staked.

nexus-client start [--dir]

sequenceDiagram
  participant N as Node
  participant G as Gateway
  N->>G: WS connect + node-key signature
  N->>G: SIWS → wallet JWT
  G->>G: check stake ≥ minimum
  G-->>N: authenticated (or rejected: not staked)
  Note over N,G: node now receives jobs for its model
          

Serving loop

Once authenticated, your node serves one dispatched job at a time. For each job it first sanitizes the request body: it pins the served model to your config.model, clamps max_tokens, and drops any unexpected keys. It then POSTs the cleaned request to your Ollama upstream (/v1/chat/completions, streaming) and forwards the SSE stream back to the gateway as the completion — or returns a job_error if the upstream call fails. The gateway meters the tokens and writes the ledger.

sequenceDiagram
  participant G as Gateway
  participant N as Node
  participant O as Ollama
  G->>N: job (model, messages)
  N->>N: sanitize (pin model, clamp tokens)
  N->>O: POST /v1/chat/completions (stream)
  O-->>N: SSE tokens
  N-->>G: stream completion (or job_error)
  Note over G: meter tokens · ledger (70/30)
          

status

nexus-client status prints your node's current configuration without connecting to anything: the configured model, the upstream server, the gateway, and your node's public key. It is the quickest way to confirm init wrote what you expected.

$ nexus-client status [--dir]
model:    llama3.2
upstream: http://localhost:11434/v1
gateway:  wss://nexus.ghostnn.ai/api/compute/node
node:     7xQ9…PuB6   (node pubkey)

earnings

nexus-client earnings calls GET /api/compute/nodes/{pubkey}/earnings with your wallet JWT. The endpoint is owner-gated — only the wallet that owns the node can read it — and returns your lifetime and unpaid GNN plus your last payout.

$ nexus-client earnings [--dir]
lifetime:    128.5 GNN
unpaid:        4.2 GNN
last payout:  12.0 GNN  (epoch 41)

Config reference

init writes config.toml in the client directory. Three fields control where the node runs and where it sends inference, each with a sensible default:

The client directory itself defaults to ~/.nexus-client; every subcommand takes --dir to point at a different one (useful if you run more than one node on a machine).

Network internals

Lending a GPU to strangers only works if the network can tell honest work from cheating. Three mechanisms keep providers accountable and the rewards fair.

Reputation & canaries

The gateway tracks a per-node reputation score that rises with consistent, correct work. To probe honesty it periodically dispatches canary jobs — requests with a known-good expected answer — pinned to a specific node. A node that fudges or skips real inference fails its canaries, and its reputation falls.

Output verification

Beyond canaries, a sample of real jobs — weighted by reputation, so newer and lower-trust nodes are checked more often — is inspected out of band by an LLM judge (Claude Haiku). The judge grades whether the served output is a genuine, on-model response. Repeated failures earn strikes, and enough strikes can freeze and slash a node. Doing honest work with a capable-enough model passes — there is nothing to game.

Payouts & metering

Every completed job is metered by tokens (prompt + completion). Rewards for that work are split 70% to the provider that ran the job and 30% to the network treasury, accumulating as unpaid GNN. The gateway settles those balances on-chain per epoch, which is what earnings reports as your last payout.

Troubleshooting

Each entry below is a symptom, its likely cause, and the fix.

Gateway rejected this node: not staked

Cause: your stake was never recorded, or it sits below the minimum.

Fix: run nexus-client stake --amount 1 and confirm the gateway replies that the stake meets the minimum before starting again.

earnings returns 401 Unauthorized

Cause: the wallet JWT doesn't match the node's owner — the earnings endpoint is owner-gated.

Fix: run the command from the client directory that holds the node's wallet.json (use --dir to point at it).

Inference fails with model not found

Cause: config.model doesn't exactly match the model name pulled in Ollama, and the node pins that name into every upstream request.

Fix: set --model to the exact pulled name (re-run init or edit config.toml), then confirm with nexus-client status.

Windows: the console opens and immediately vanishes

Cause: older builds depended on the VC++ runtime, which may be missing.

Fix: re-download the latest release — the current build is statically linked (+crt-static) and needs no runtime install.

Stake fails or times out on sendTransaction

Cause: a public RPC is rate-limiting your transaction.

Fix: pass --rpc <reliable endpoint> to nexus-client stake and retry.

Security & FAQ

Is it safe to run?

The client is open source and auditable — you can read exactly what it does at https://github.com/Dev916/nexus-client. Nothing runs on your machine except the binary you downloaded and your own Ollama server; the node never executes code the gateway sends it, it only relays inference requests to your local upstream.

How do I keep my keys safe?

Treat wallet.json and node_key as secrets. Back them up somewhere safe, and never commit or share them — anyone with wallet.json controls your funds, and anyone with node_key can impersonate your node.

Can I unstake?

Not yet. Unstaking is out of scope at launch — staked GNN stays staked. Only stake what you're comfortable committing to keep your node trusted.

Which models are accepted?

Any model in the network's eligible classes that your GPU can serve. See the eligible model classes on the overview page for the current list.