AetherForge/README.md

AetherForge

Private Monero fleet command deck for machines you own.

One Windows control PC. One dashboard. Forge a worker installer per machine — or fuse it inside your own prep tool — and watch your entire LAN 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 · alerts · limits   │
  │           │                                                 │
  │           ▼                                                 │
  │  FORGE (Builder)          per-worker .exe baked at compile  │
  │           │                                                 │
  │           ├──► Fusion? embed worker inside your prep.exe    │
  │           │                                                 │
  │           ▼                                                 │
  │  WORKER PC                RandomX on CPU · WebSocket home   │
  │           │                                                 │
  │           ▼                                                 │
  │  COMMAND DECK             live stats · remote ops · shares  │
  └─────────────────────────────────────────────────────────────┘

---

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, WebSocket hub, SQLite fleet DB, Stratum proxy to your pool
Command deck	React dashboard — fleet overview, agent roster, forge builder, calibrate settings, field guide
Worker agent	Windows binary compiled on demand — mines RandomX, phones home, accepts remote commands
Fusion	Optional bundler — hides the worker inside your uploaded prep.exe, same icon, single deliverable
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 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)

• Live fleet hashrate, CPU/RAM gauges, share feed
• Per-agent cards with pause / resume / stop / uninstall
• Fleet alerts (offline, hashrate drop, rejection spikes)
• Pool connection status, earnings estimate, AI activity panel

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)

Forge (Miner Builder)

• 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
• Fusion mode — upload prep, pick run order (parallel / prep_first / worker_first), output lands in project root with prep's icon when icon extraction succeeds
• Baked settings: thread mode, idle/scheduled mining, install path, stealth, self-healing watchdog, firewall exclusion

Calibrate (Settings)

• Server port, public URL, data retention, max agents
• Default pool + wallet for new forge forms
• 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

---

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, and starts the server.

2. Browser opens http://localhost:8989

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

4. Forge → worker name + server URL (http://YOUR-LAN-IP:8989 or your tunnel URL) → Forge Installer

5. Run the forged .exe once on each worker PC

6. Watch them appear on Command Deck and Fleet Roster

Output locations

Artifact	Where
Fused / forged exe (primary)	Project root — e.g. G:\crypto miner\prep.exe or install-worker.exe
Archive copy	data\builds\{build-id}\
Uninstall script	Same build folder + download API
Server config	data\config.json
Fleet database	data\miner.db

---

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.

---

Project Layout

crypto miner/
├── run.bat              ← one-click build + launch
├── bin/
│   └── miner-server.exe
├── data/                ← config, DB, builds, preps, logs
├── server/              ← Go control server
│   └── web/             ← React command deck (Vite)
├── agent/               ← Windows worker source (compiled by Forge)
├── fusion/              ← prep + worker bundler
├── PROBLEMS.md          ← known issues audit (severity-ranked)
└── README.md            ← you are here

---

API Surface (summary)

Method	Path	Purpose
GET	/api/v1/health	Health check
GET/PUT	/api/v1/config	Calibrate settings
POST	/api/v1/builder/build	Forge worker (multipart if Fusion)
GET	/api/v1/builds/{id}/download	Download forged exe
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 ..\..
cd server
go build -o ..\bin\miner-server.exe .

bin\miner-server.exe -port 8989 -data .\data

---

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, 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

• The dashboard and API ship without authentication by default. Do not expose port 8989 to the public internet without adding your own access controls (VPN, firewall allowlist, 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.
• 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}