SV2 UI

A unified setup wizard and monitoring dashboard for Stratum V2 mining.

Quick Start (Docker)

docker run --rm \
  --name sv2-ui \
  -p 8080:8080 \
  -e HOST_HOME=$HOME \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v sv2-config:/app/data/config \
  stratumv2/sv2-ui:main

Then open http://localhost:8080. On first run, you'll be guided through the setup wizard.

Flags explained:

• --rm removes the container on exit so you can re-run without conflicts
• -e HOST_HOME=$HOME is required for JD mode to locate your Bitcoin Core socket
• -v /var/run/docker.sock:... lets sv2-ui manage Translator and JDC containers
• -v sv2-config:/app/data/config persists your configuration across restarts

Stopping with Ctrl+C will also stop the Translator and JDC containers automatically.

To fully remove sv2-ui, delete the container together with its config volume:

docker rm -f sv2-ui && docker volume rm sv2-config

Authentication

sv2-ui requires an admin password before it exposes any control over the mining stack. This protects your payout address and pool credentials from anyone who can reach the device's web interface.

• On first launch, sv2-ui asks you to create an admin password. It also generates a one-time recovery key — save it somewhere safe.
• Sessions are kept in memory and last 12 hours; they are cleared on server restart, at which point you simply log in again. This means sv2-ui updates or Umbrel reboots will log everyone out — if the dashboard is left open on a screen, it will show the login form on the next request.
• Forgot the password? On the unlock screen, choose Forgot password? and enter your recovery key. This resets the password while keeping your mining configuration. You then choose a new password and get a fresh recovery key. You can also (re)generate a recovery key any time from Settings > Security when signed in.
• Lost your recovery key? Delete the credential file and reload the app. You'll be prompted to create a new password; your mining configuration is kept. The file location depends on your setup:
  • Docker: docker exec sv2-ui rm -f /app/data/config/credential.json
  • Umbrel: Settings > Advanced > Terminal > select the Stratum V2 UI app > rm -f /app/data/config/credential.json
  • Dev: delete data/config/credential.json from the project root

macOS (Docker Desktop)

docker run --rm --name sv2-ui -p 8080:8080 \
  -e HOST_HOME=$HOME \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v sv2-config:/app/data/config \
  stratumv2/sv2-ui:main

macOS (Colima / OrbStack)

Mount the appropriate Docker socket for your setup:

# Colima
docker run --rm --name sv2-ui -p 8080:8080 \
  -e HOST_HOME=$HOME \
  -v $HOME/.colima/default/docker.sock:/var/run/docker.sock \
  -v sv2-config:/app/data/config \
  stratumv2/sv2-ui:main

# OrbStack
docker run --rm --name sv2-ui -p 8080:8080 \
  -e HOST_HOME=$HOME \
  -v $HOME/.orbstack/run/docker.sock:/var/run/docker.sock \
  -v sv2-config:/app/data/config \
  stratumv2/sv2-ui:main

Development

# Install dependencies (includes server workspace)
npm install

# Make sure Docker Desktop / Docker Engine is running

# Start frontend + backend
npm run dev

Then open http://localhost:5173. On first run, you'll be guided through the setup wizard.

The backend auto-detects common local Docker sockets, including /var/run/docker.sock and ~/.docker/run/docker.sock. To override detection, set DOCKER_SOCKET_PATH or DOCKER_HOST before starting the server.

What It Does

1. Setup Wizard - Guides you through configuration

   • Choose Solo or Pool mining
   • Choose whether templates come from your own node or from a pool
   • Select a pool when using pool-provided templates
   • Set the expected hashrate for initial difficulty tuning
   • Configure your username/Bitcoin address
   • For JD mode: select OS, Bitcoin network, and auto-compute the IPC socket path
   • Bitcoin Core IPC is currently supported on Linux and macOS only; Windows is not supported yet

2. Docker Orchestration - Starts and manages containers

   • Translator Proxy (SV1 to SV2 translation)
   • JD Client (for custom block templates, optional)
   • Graceful shutdown: Ctrl+C stops all containers

3. Monitoring Dashboard - Real-time stats

   • Pool connection status (e.g. "Connected to Braiins")
   • Total hashrate from connected miners
   • Active workers
   • Shares to pool
   • Hashrate history chart

Deployment Modes

Pool Mining (No-JD)

Pool ← Translator ← SV1 Miners

Pool Mining with Job Declaration

Pool ← JDC ← Translator ← SV1 Miners
        ↑
   Bitcoin Core (your node creates block templates)

Solo Mining

Solo Pool ← Translator ← SV1 Miners

Sovereign Solo Mining

Bitcoin Core ← JDC ← Translator ← SV1 Miners

Supported Pools

Pool	Mode	Status
Braiins Pool	Pool (No-JD)	Available
SRI Solo Pool	Pool (JD) / Solo	Testing
Blitzpool	Solo	Available
Sovereign Solo Mining	Solo (JD)	Available

Building the Docker Image

docker build -t sv2-ui:test .

docker run --rm --name sv2-ui -p 8080:8080 \
  -e HOST_HOME=$HOME \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v sv2-config:/app/data/config \
  sv2-ui:test

Project Structure

sv2-ui/
├── src/                    # React frontend
│   ├── components/
│   │   ├── setup/          # Setup wizard steps
│   │   ├── settings/       # Settings page components
│   │   ├── data/           # Dashboard components
│   │   └── ui/             # Base UI primitives
│   ├── hooks/              # React hooks
│   └── pages/              # Page components
├── server/                 # Node.js backend
│   └── src/
│       ├── index.ts        # Express API + graceful shutdown
│       ├── docker.ts       # Docker orchestration
│       └── config-generator.ts  # TOML config generation
├── Dockerfile              # Multi-stage build (with tini for signal handling)
└── public/                 # Static assets

Docker Images Used

sv2-ui uses stratumv2/translator_sv2:main for no-JD stacks on development branches. JD stacks use stratumv2/jd_client_sv2:main and stratumv2/translator_sv2:main.

Release branches should pin all sv2-apps image tags in shared/src/images.ts before publishing.

Bitcoin Core IPC Support

JD mode supports Bitcoin Core 30.x and 31.x over IPC. During setup, sv2-ui stores 30 for Bitcoin Core 30.x or 31 for Bitcoin Core 31.x and writes that value to the generated JDC config.

Monitoring API Notes

• Monitoring API contract - How sv2-ui should handle JDC and Translator Proxy monitoring API changes.

Ports

Port	Service	Description
8080	sv2-ui (Docker)	Web UI
5173	sv2-ui (dev)	Vite dev server
3001	sv2-ui (dev)	Backend API
34255	Translator	SV1 miners connect here
9092	Translator	Monitoring API
34265	JDC	Translator connects here (JD mode)
9091	JDC	Monitoring API (JD mode)

Tech Stack

• React 18 + TypeScript - Frontend
• Vite - Build tool
• Tailwind CSS - Styling
• React Query - Data fetching
• Express - Backend API
• Dockerode - Docker orchestration

Related Projects

• stratum-mining/sv2-apps - Translator, JDC, Pool, JDS
• stratum-mining/stratum - SV2 protocol implementation

License

MIT OR Apache-2.0