A unified setup wizard and monitoring dashboard for Stratum V2 mining.
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:mainThen open http://localhost:8080. On first run, you'll be guided through the setup wizard.
Flags explained:
--rmremoves the container on exit so you can re-run without conflicts-e HOST_HOME=$HOMEis 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/configpersists 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-configsv2-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.jsonfrom the project root
- 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:mainMount 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# Install dependencies (includes server workspace)
npm install
# Make sure Docker Desktop / Docker Engine is running
# Start frontend + backend
npm run devThen 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.
-
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
-
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
-
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
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
| 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 |
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:testsv2-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
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.
JD mode supports Bitcoin Core 30.x, 31.x and 32.x over IPC. sv2-ui reads the node's major version over RPC before every start, stores it, and writes it to the generated JDC config, so a node that changes version is picked up on its next start.
Mining does not start if the version cannot be read, because a JDC configured for the wrong version can lose the blocks it finds. The version is read through the data directory that holds the IPC socket, which ties the answer to the node JDC will use. So the socket has to stay in that directory, the RPC server has to be on, Bitcoin Core has to use its default RPC port or set rpcport or rpcbind in that directory's bitcoin.conf, and sv2-ui has to be able to read its cookie file, or rpcuser and rpcpassword in that bitcoin.conf. Settings passed on the command line, or kept in a file named by -conf or includeconf, are not picked up, and neither is a cookie moved with -rpccookiefile.
- Monitoring API contract - How
sv2-uishould handle JDC and Translator Proxy monitoring API changes.
| 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) |
- React 18 + TypeScript - Frontend
- Vite - Build tool
- Tailwind CSS - Styling
- React Query - Data fetching
- Express - Backend API
- Dockerode - Docker orchestration
- stratum-mining/sv2-apps - Translator, JDC, Pool, JDS
- stratum-mining/stratum - SV2 protocol implementation
MIT OR Apache-2.0