# Harness VM Control

> Agent-first onboarding site that puts a Mac or VM on a private WireGuard control
> network so an administrator can manage it remotely. The site serves text and one
> bash script; it never executes anything and never receives a key. Everything runs
> on the user's machine, driven by the user's own AI agent or by hand.

Base URL: https://harness-vm-control-dev.zeabur.app

## Start here (agents)
- Canonical operating playbook (zh-Hant, with a four-language intent table): https://harness-vm-control-dev.zeabur.app/playbook (alias https://harness-vm-control-dev.zeabur.app/agent)
- The client script, single bash file, auditable: https://harness-vm-control-dev.zeabur.app/hvc — checksum: https://harness-vm-control-dev.zeabur.app/hvc.sha256 (same-origin: detects a corrupted download, not a compromised origin; provenance rests on HTTPS and trusting this domain)
- Installer (POSIX sh; downloads hvc to ~/.local/bin, verifies sha256, runs the sub-command you pass or `hvc doctor`): https://harness-vm-control-dev.zeabur.app/setup.sh
- Zero-knowledge flow: the user does three things — pastes this URL to their agent, pastes the administrator's WireGuard config to the agent, pastes ONE line into their own terminal. The agent writes the config to ~/.hvc/wg0.conf (0600) and hands over: `curl -fsSL https://harness-vm-control-dev.zeabur.app/setup.sh | sh -s -- join ~/.hvc/wg0.conf`
- hvc lands in ~/.local/bin, which is often NOT on the agent's PATH: when `hvc` is not found, call `~/.local/bin/hvc` instead.

## One-sentence entry points (any language; the sentence carries this URL)
- 幫我把這台機器接進控制網路：https://harness-vm-control-dev.zeabur.app  → full flow (playbook part 1 → part 2)
- Connect this machine to the control network: https://harness-vm-control-dev.zeabur.app
- このマシンをコントロールネットワークに接続して：https://harness-vm-control-dev.zeabur.app
- 帮我把这台机器接进控制网络：https://harness-vm-control-dev.zeabur.app
- "I got the parameters from the admin, apply them" → part 2 (`hvc join <file>`; parameters only: `hvc prepare` + `hvc apply`)
- "Check this machine's VPN status" → `hvc verify --json`
- "Reconnect the tunnel" → `hvc restart` (user's terminal)
- "Enable SSH so the admin can reach this machine" → `hvc enable-ssh --authorized-key "<admin key>"`

## What hvc does (idempotent; every step checks state first)
- doctor: detect macOS/Linux/WSL2, Intel/Apple Silicon, VM or bare metal, Xcode CLT, Homebrew, wireguard-tools, keys, tunnel state; prints the next step (`join` when no config is installed yet). Read-only, no sudo. `--json` available.
- join FILE [--ssh-key KEY] [--iface wg0] [--no-ssh] [--mirror ustc]: the main path, one sudo run. Installs only what is missing (Xcode CLT + Homebrew + wireguard-tools on macOS; `wireguard-tools iproute2 iputils-ping` on Linux), installs the administrator's .conf 0600 root-owned into `$(brew --prefix)/etc/wireguard` (macOS) or `/etc/wireguard` (Linux), brings the tunnel up (Linux with systemd: also enabled at boot), verifies, turns on SSH and authorises the administrator's key (given with --ssh-key or read from a `# SSHKey = …` comment line inside FILE), prints the registration report. Re-running with the same file is a no-op for the config; a different file asks the user to type `replace`.
- prepare: parameter path. Same tool installation, then generate a key pair under ~/.hvc/keys (umask 077) and print the public key. `--mirror ustc` for mainland-China networks (also usable before join).
- apply: parameter path — build `<iface>.conf` from `--address --endpoint --peer-key [--allowed-ips --dns --direct-route --persist --iface --force --no-up]` using the LOCAL private key; `apply --conf FILE` is what join calls internally.
- up / down / restart, status / verify (`--json`; status always exits 0, verify exits 0 only when connected), enable-ssh, report (registration block, no secrets; shows this machine's public key in both paths), rotate-key (typed confirmation; parameter path only), remove, update, enroll (reserved, not yet available).

## Trust model
- Hosts contacted: this site (update), Homebrew / distro package repositories (join/prepare), the team's WireGuard gateway (tunnel). Nothing else.
- Private key: in the main path it is generated by the administrator and delivered once inside the .conf; these machines are disposable VMs, so pasting the config into the agent conversation is an accepted product decision (2026-09-19). The agent writes it to ~/.hvc/wg0.conf (0600) and must not echo it back, upload it, copy it to another machine, or read the system WireGuard config afterwards. hvc never prints or traces the key. In the parameter path the key is generated locally and never leaves the machine. Public key and `hvc report` output are always safe to share.
- sudo: only in the user's own terminal. hvc refuses to run privileged steps when no interactive terminal is present, instead of hanging. Agent shells normally have no TTY.
- Typed confirmations (no --yes exists, refused without a TTY, cannot be bypassed by an agent): a .conf containing PreUp/PostUp/PreDown/PostDown hook lines (they run as root) → type `run-hooks`; replacing a different installed config → type `replace`; rotate-key → `rotate`; remove --purge-keys → `purge`.
- One config, one machine: the same .conf enabled on two machines makes the gateway flap between them ("works on and off"); a cloned VM needs a new .conf from the administrator (rotate-key refuses in .conf mode).
- Peer registration is manual in this deployment: the administrator hands the user a complete .conf (optionally with the `# SSHKey = …` line); the user sends back `hvc report`. `hvc enroll <token>` is reserved for future automatic enrollment.

## Humans
- Product page (zh-TW / zh-CN / en / ja): https://harness-vm-control-dev.zeabur.app/welcome
- Step-by-step manual, including the parameter path, the fully manual path without hvc, VM notes and troubleshooting: https://harness-vm-control-dev.zeabur.app/manual (markdown per language at https://harness-vm-control-dev.zeabur.app/manual/zh-TW.md, /manual/zh-CN.md, /manual/en.md, /manual/ja.md)

## Misc
- Version: https://harness-vm-control-dev.zeabur.app/version.json · Health: https://harness-vm-control-dev.zeabur.app/health · robots: https://harness-vm-control-dev.zeabur.app/robots.txt
- Supported: macOS (Intel, Apple Silicon, including macOS guests in UTM/Parallels/VMware), Debian/Ubuntu, Fedora/RHEL family, Arch, WSL2; Alpine only after `apk add bash`. The official macOS GUI app is App Store-only (no dmg, no Homebrew cask) and cannot manage the same tunnel as hvc at the same time, so this site is CLI-only by design.