dstack Mining Backend

dstack GPU mining backend service, responsible for monitoring GPU status and communicating with the message network.

Prerequisites

IMPORTANT: Before deploying this backend service, you must:

1. Run dstack on the host machine with GPU passthrough enabled
2. Provide GPU resources to the dstack service
3. Ensure the dstack service is accessible at localhost:14520
4. Ensure the dstack VMM port is configured to listen on 0.0.0.0 (it defaults to 127.0.0.1). This is required for Docker container access. You can verify the port binding status using sudo netstat -tulnp | grep 14520

Without a properly configured dstack service with GPU resources on the host machine, you will not be able to earn rewards.

Architecture

┌─────────────────────┐
│   Registry Server   │  ← Verify and manage all worker nodes
│                     │
└─────────────────────┘
          ↑
          │ Manual Registration
          │
┌─────────────────────┐
│  dstack Backend     │  ← Monitor GPU + Generate Keys
│   (This Project)    │
└─────────────────────┘
          ↑                ↑
          │                │
          ↓                │ Read Nostr key
┌─────────────────────┐    │
│   dstack Service    │    │
│  (GPU Scheduler)    │    │
│   Port: 14520       │    │
└─────────────────────┘    │
                           │
                  ┌────────┬────────┐
                  │  Dephy Worker   │  ← Message network communication
                  │   Port: 9001    │
                  └─────────────────┘

Components

1. dstack Backend (This Project)

Role: GPU node backend service

Functions:

• Monitor dstack GPU status
• Generate/load Nostr keypair (stored in data/key)
• Detect Node Type from dstack metadata
• Provide health check API (/health)

2. Dephy Worker (Included in docker-compose)

Role: Worker for message network communication

Functions:

• Read Nostr keys generated by Backend
• Connect to message network
• Handle task distribution

Dependency: Backend must start and keys must be generated first.

3. Registry Server (External Service)

Role: Centralized node registration and authentication service

Functions:

• Receive worker node registrations
• Verify node permissions
• Manage node whitelist

4. dstack Service (External Service)

Role: GPU virtualization and scheduling service

Functions: Provide GPU resource information

You need to provide: dstack service running on local machine at localhost:14520

Quick Start

1. Configure Environment Variables

# Copy configuration file
cp .env.example .env

# Edit .env file and fill in required parameters
nano .env

Required configuration:

# Ethereum owner address (required)
OWNER_ADDRESS=0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb

# Worker image version (optional, use v2.0.0 for production)
DEPHY_WORKER_IMAGE_TAG=v2.1.0

2. Start Backend

docker compose up -d

3. Get Registration Info

View the logs to get the information needed for manual registration:

docker compose logs dstack-backend

Look for the "MANUAL REGISTRATION REQUIRED" section:

INFO MANUAL REGISTRATION REQUIRED
INFO Please provide the following information to the administrator:
INFO Nostr Public Key: <your-pubkey>
INFO Owner Address:    <your-owner-address>
INFO Node Type:        <detected-node-type>

4. Register Manually

Send the information from the previous step to the administrator to register your node.

5. Start Worker

Once registered, start the worker service:

docker compose --profile mining up -d

Environment Variables

Basic Configuration

Variable	Description	Default Value
DSTACK_BACKEND_DSTACK_URL	dstack service address. Supports both HTTP (e.g., http://host.docker.internal:14520) and Unix socket (e.g., unix:///opt/dstack/dstack-v05x/run/teepod.sock)	http://host.docker.internal:14520
LISTEN_ADDR	Backend listening address	0.0.0.0:8080
DATA_DIR	Data directory (key storage)	./data

Registration Configuration (Required)

Variable	Description	Required
OWNER_ADDRESS	Ethereum owner address	✅ Required

Important: Missing OWNER_ADDRESS will prevent the service from starting.

API Endpoints

GET /health

Returns Backend health status and GPU information

Response Example:

{
  "version": "1.0.0",
  "topic": "dstack-gpu-monitor",
  "pubkeys": ["abc123..."],
  "status": "Available",
  "metadata": "{\"gpu_count\":1,\"gpus\":[...]}",
  "ip_address": "192.168.1.100"
}

GET /

Returns basic service information

Registration Workflow

1. Start Backend: The backend service starts, generates a Nostr keypair, and connects to the local dstack service to fetch GPU information.
2. Get Registration Info: The backend logs the generated Public Key, the configured Owner Address, and the detected Node Type.
3. Manual Registration: You must provide this information to the administrator to register your node on the whitelist.
4. Start Worker: Once registered, you start the dephy-worker service (using the mining profile). The worker reads the keys and connects to the message network to start receiving tasks.

Troubleshooting

Startup Failed: Missing Environment Variables

Error: OWNER_ADDRESS environment variable is required for worker registration

Solution: Configure OWNER_ADDRESS in .env file

Node Type Unknown

ERROR Could not determine node type from dstack. Defaulting to 'Unknown'.

Solution:

1. Ensure dstack is running at localhost:14520
2. Check DSTACK_BACKEND_DSTACK_URL configuration
3. Ensure dstack has GPU resources available
4. Check the GPU type is supported, currently we only support H100, H200 and B200

dstack Connection Failed

ERROR Failed to connect to dstack: ...

Solution:

1. Ensure dstack service is running at localhost:14520
2. Check DSTACK_BACKEND_DSTACK_URL configuration
3. If using Unix socket (e.g., unix:///opt/dstack/dstack-v05x/run/teepod.sock):
   • Verify the socket file exists: ls -l /opt/dstack/dstack-v05x/run/teepod.sock
   • Ensure the Docker container has access to the socket (mount it as a volume)
   • Check socket permissions
4. Ensure the dstack service is listened on 0.0.0.0 not just localhost

License

MIT