# MinerOps Windows Agent

The Windows Agent runs at a mining site and performs local discovery, polling,
API3 enrichment, pool polling, and approved queued miner-control operations.
MinerOps does not send API3 credentials through the hub command queue; those
credentials remain in the Agent's local `agent-config.json`.

## Recovered Baseline

The seven runtime and support scripts in this directory were recovered from the
live `C:\MinerOpsAgent` installation. `BASELINE_SHA256SUMS` records their exact
pre-change hashes. Historical backups, live configuration, state, logs, and
probe output are intentionally excluded.

## Local Files

Create `agent-config.json` from `config.example.json` on the Agent host. Never
commit that file. `site_id` is the durable MinerOps site UUID. `agent_zone_id` is the optional
durable network-reachability Zone UUID; older configurations may omit it only
when the Hub can preserve an established assignment or resolve exactly one
enabled Zone at the Site. `site_name` is retained only for transitional display
compatibility.

The Agent writes runtime state to `agent-state.json` and logs under `logs/`.
Installation and upgrades preserve all three paths.

## Security

API3 account and password values are local secrets. Missing credentials make
miner control unavailable. Passwords, API tokens, salts, and the Agent secret
must not be written to normal logs or returned to MinerOps command history.

New Agent identities use per-Agent credentials created through secure
one-time enrollment. The permanent Agent secret is returned only to the
enrolling Agent and is stored locally in `agent-config.json`; MinerOps stores
only its hash. The legacy deployment shared secret remains only for explicitly
retained compatibility behavior and must not authenticate a newly enrolled
per-Agent identity.

## Legacy Compatibility

The older direct Hub API3, `/agent-control`, password-change, bulk-control, and
scheduling paths remain available for compatibility and are deprecated for the
Internal Alpha. The new Miner Detail controls use only the typed control API and
Agent queue; the modular control backend does not connect directly to miners.

## Deployment

### New Agent enrollment

For a new Agent, use Agent Management in MinerOps:

1. Choose the Site and an enabled, unassigned Agent Zone.
2. Enter a descriptive Agent name.
3. Create a Windows enrollment.
4. Download MinerOpsAgent-Windows.zip before the enrollment expires.
5. Copy the ZIP to the intended Windows machine and extract it.
6. Open Windows PowerShell as Administrator in the extracted
   MinerOpsAgent-Windows directory.
7. Run:

       .\Enroll-MinerOpsAgent.ps1

8. Enter the local WhatsMiner API3 account/password when prompted, or leave
   the account blank if API3 functionality is not being configured yet.
9. The bootstrapper exchanges the short-lived token with POST /api/agent/enroll,
   saves the resulting permanent Agent identity locally, and hands off to the
   safe runtime installer.
10. Verify the Agent appears in Agent Management and checks in successfully.
11. Delete the downloaded ZIP and extracted setup directory.

Do not place enrollment.json, enrollment tokens, Agent secrets, or API3
credentials in screenshots, chat, tickets, logs, or source control.

### Existing Agent upgrade

For an already enrolled/configured Agent, do not run the enrollment
bootstrapper. Copy the new canonical Agent files to a temporary directory and
run install.ps1 from an elevated Windows PowerShell session.

The installer copies only managed runtime code to C:\MinerOpsAgent and
preserves agent-config.json, agent-state.json, logs\, backups, probe output,
and other runtime data. Existing Scheduled Task definitions are authoritative
and are not rewritten. Missing tasks are created for a fresh or incomplete
installation without hard-coded user names.

If MinerOpsAgent was running before an upgrade, the installer stops only that
Scheduled Task, waits for it to stop, replaces the managed files, and starts it
again. A previously stopped Agent remains stopped. Before replacing runtime
files, the installer copies them to a timestamped backup under
C:\MinerOpsAgent\backups.

A failed deployment restores managed files, removes tasks created by that
failed attempt, and restores the main Agent's prior running state.

uninstall.ps1 unregisters the four MinerOps Scheduled Tasks and removes runtime
code while preserving local configuration, state, logs, and backups.