raindeer-cli

The official command-line interface for the Raindeer decentralized peer-to-peer AI inference marketplace.

The Raindeer CLI (raindeer-cli) is a comprehensive tool designed to orchestrate, configure, and monitor decentralized AI services. With it, you can become an AI resource provider (Seller) by hosting local models, run an autonomous gateway client (Buyer) with cryptographic micro-payment channels, spin up a central discovery registry, or control onchain smart contract operations (DIEM locking and ANTS incentives) directly from your terminal.

🛠️ Installation

Ensure you have Node.js (v18 or higher) installed on your system.

Install globally via NPM:

npm install -g raindeer-cli

Or run directly using npx:

npx raindeer-cli [command]

🚀 Quick Start (Run All Nodes)

To boot up a local test environment, including a Hardhat EVM Node, Registry Directory, Buyer Proxy, and 50-node P2P seller network simulator simultaneously, run:

raindeer start

📋 Command Directory

🟢 raindeer seller (Become an AI Provider)

Monetize your computing power or upstream API keys by exposing Raindeer endpoints.

• Setup Configuration Wizard:

  raindeer seller setup

  An interactive CLI wizard that helps you specify your onchain merchant address, configure your models/services list, set pricing parameters (USDC rates per million tokens), and hook up LLM backend providers (Ollama, vLLM, OpenRouter, Together). Creates ~/.raindeer/config.json.

• Start Node:

  raindeer seller start

  Loads your local configuration, establishes optional secure public tunnels (via localtunnel), registers your node endpoint with the discovery registry, and starts serving incoming buyer inferences.

• View Earnings & Statistics:

  raindeer seller status

  Displays real-time uptime, aggregated latency percentiles, input/output token volume served, and total USDC earned & ready to settle.

• Check Metrics:

  raindeer seller metrics

  Outputs live, raw Prometheus text format metrics for integration with monitoring stacks (e.g. Grafana).

🔵 raindeer buyer (API Client Gateway)

Route inference requests to the best available sellers and sign off-chain micro-payments dynamically.

• Start Local Buyer Proxy:

  raindeer buyer start

  Launches a local gateway on Port 8377. You can redirect your existing OpenAI or Anthropic API tools here (e.g., export OPENAI_BASE_URL=http://localhost:8377/v1) to automatically access the decentralized network.

• Manage Pin Connections: Choose to route all requests to a specific peer rather than relying on automated reputation scores.

  raindeer buyer connection set --peer <peerId>
  raindeer buyer connection clear

• Check Proxy Status & Escrow Budgets:

  raindeer buyer status

  Displays your proxy stats, reputation metrics, connected signer wallets, and active channel details (escrow allocations, cumulative spends).

• Review Peer Reputation Scores:

  raindeer buyer reputation

  Lists all peers that you have transacted with, along with their success rate, P95 latency response, and derived reliability scores.

🟣 raindeer registry (Peer Directory)

Manage the discovery network directories.

• Start Registry Server:

  raindeer registry start

  Spawns the liveness lookup hub on Port 9000 mapping Peer IDs to URLs and offerings.

• Registry Metrics:

  raindeer registry metrics

  Check the total count of registered nodes, active heartbeats, and pruning counts.

💎 raindeer diem (Onchain Escrow Capacity)

Participate in the DIEM Provider Capacity Program by locking tokens to secure your node slot and claiming incentives.

• Check Onchain ESCROW status:

  raindeer diem status

  Displays your DIEM token address, total locked capacity, and queued withdrawals.

• Lock Capacity Tokens: Lock your DIEM tokens to increase your provider reputation and capacity score:

  raindeer diem lock <amount>

• Claim Network Incentives: Claim accumulated $ANTS native network rewards for your active hosting capacity:

  raindeer diem claim

🔍 raindeer network (Discovery & Exploration)

• Browse Registered Offerings:

  raindeer network browse [--model <model_name>]

  Lists all active seller nodes registered in the network, sorted by recency and filtered by specific model capabilities.

• Examine Peer Metadata:

  raindeer network peer <peerId>

  Fetches raw registration metadata, endpoint routes, supported models, and merchant wallet addresses for any individual Peer ID.

🔒 Security & Payments

The Raindeer CLI relies on standard Ethereum signatures (EIP-712 typed structured data). All payment requests utilize EIP-402 micro-payment headers (x-402-payment-auth and x-402-channel-id). The CLI signs payment envelopes completely local on your machine, ensuring your private keys never leave your terminal environment.

📄 License

Raindeer CLI is distributed under the ISC License.