AetherForge/README.md

# Private Miner Command Deck

Private Monero (XMR) fleet control server for your own network. Run the control server on one Windows machine, configure pool/wallet/defaults in the web dashboard, build per-machine worker `.exe` files, and deploy them across your LAN.

## Quick Start

1. Install [Go 1.21+](https://go.dev/dl/) and [Node.js 20+](https://nodejs.org/) (or let `run.bat` install them).
2. Double-click **`run.bat`** on your control PC.
3. Open **http://YOUR-LOCAL-IP:8989** (shown when the server starts).
4. Go to **Settings** and set your wallet + pool.
5. Go to **Miner Builder**, enter a worker name, click **Build Installer .exe**.
6. Copy `install-{worker}.exe` to each Windows machine on your LAN and **run it once**.

Each installer:

- Copies the miner to `%LOCALAPPDATA%\CryptoMiner\{worker}-{build}\miner.exe`
- Registers Windows auto-start (and optional scheduled task)
- Connects back to your dashboard at your **LAN IP:8989**
- Appears on the **Agents** and **Dashboard** pages automatically

## End Result

| Piece | What it does |
|-------|----------------|
| Control PC | Runs the web dashboard on local IP + port **8989** |
| Dashboard | Configure pool/wallet/defaults, build installers, track all miners |
| `install-{name}.exe` | Single file you run once on each worker PC to install + start mining |

| Component | Purpose |
|-----------|---------|
| `server/` | Go control server (REST API, WebSocket hub, pool proxy, builder) |
| `server/web/` | React dashboard (Dashboard, Agents, Builder, Settings) |
| `agent/` | Windows worker source compiled on demand by the builder |
| `data/` | SQLite DB, config, build output, logs |
| `run.bat` | One-click build + launch script |

## Workflow

```
Settings (dashboard)
    -> data/config.json
Miner Builder (dashboard)
    -> POST /api/v1/builder/build
    -> compiles agent/ with baked-in config/builtin.go
    -> writes data/builds/{build-id}/xmr-worker-{name}.exe
Worker .exe (target PC)
    -> WebSocket ws://your-server:8989/ws/agent
    -> receives jobs, mines with RandomX, submits shares
Control server
    -> Stratum proxy to your configured pool
    -> aggregates stats in dashboard
```

## Configuration

All server settings are edited in the dashboard **Settings** page and saved to:

```
data/config.json
```

The **Miner Builder** loads those values as defaults. Per-worker overrides (name, threads, silent mode, etc.) are baked into each `.exe` at compile time.

### Built worker settings

Each generated agent includes:

- Server URL
- Wallet address
- Pool host/port/TLS/password
- Thread count, CPU priority, mining mode
- Max CPU %, minimum free RAM
- Idle/scheduled mining windows
- Silent mode, auto-start, run-as mode

## Build Output Location

After a successful build, the dashboard shows:

- **Absolute path** — full Windows path to the `.exe`
- **Relative path** — path from the project root
- **Download link** — `/api/v1/builds/{id}/download`

Example:

```
G:\crypto miner\data\builds\abc123...\xmr-worker-office-pc-1.exe
```

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/health` | Health check |
| GET/PUT | `/api/v1/config` | Server settings |
| POST | `/api/v1/builder/build` | Build worker `.exe` (returns JSON with file path) |
| GET | `/api/v1/builds` | List recent builds |
| GET | `/api/v1/builds/{id}/download` | Download a built `.exe` |
| GET | `/api/v1/agents` | List connected workers |
| GET | `/api/v1/dashboard/stats` | Fleet stats |
| WS | `/ws/agent` | Worker connection |
| WS | `/ws/dashboard` | Live dashboard updates |

## Manual Commands

```bat
cd server
go build -o ..\bin\miner-server.exe .

cd server\web
npm install
npm run build

cd agent
go build -o xmr-worker-test.exe .
```

Run server manually:

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

## Network Deployment

- **Same LAN:** set Server URL in Builder to `http://YOUR-PC-IP:8989`
- **Remote access:** put the server behind Cloudflare Tunnel or similar and use your HTTPS domain as Server URL (`https://pool.example.com`)

Workers convert `http(s)://...` to `ws(s)://.../ws/agent` automatically.

## Data Files

| Path | Contents |
|------|----------|
| `data/miner.db` | Agents, shares, hashrate history, build records |
| `data/config.json` | Server + default agent settings |
| `data/builds/` | Generated worker executables |
| `data/logs/` | Server logs (if enabled) |

## Security Notes

- This project is intended for **your own machines on your own network**.
- Windows Defender may flag freshly compiled mining executables. Code-signing and Defender exclusions on managed machines are the legitimate mitigation paths.
- Do not expose the dashboard to the public internet without authentication.

## Requirements

- Windows 10/11 (control server and workers)
- Go 1.21+
- Node.js 20+ (for dashboard build only)
- Outbound internet to your chosen Monero pool

## License

Private use. Monero mining uses the RandomX algorithm (BSD-3-Clause) via `git.gammaspectra.live/P2Pool/go-randomx`.