vantage-agent/CLAUDE.md

Vantage agent (vantage-agent)

The lightweight Go agent installed on every managed server, and the Windows installer that packages it. Extracted from the vantage monorepo with its history; the agent is the repository root, so the module is gitea.hostxtra.co.uk/vantage/vantage-agent.

vantage-agent/
├── cmd/main.go                  # flags: -generate-key
├── internal/
│   ├── checker/                 # monitor check execution
│   ├── config/                  # config.yaml load/save
│   ├── exec/                    # workflow step execution
│   ├── grpc/                    # client + the codec registration
│   ├── inventory/               # CPU/mem/disk collection (linux/other/windows)
│   ├── keys/                    # authorized_keys read/diff/write
│   ├── monitors/                # agent-run monitor loop
│   ├── proxy/                   # console relay, always from 127.0.0.1
│   ├── sync/                    # poll loop + command stream + self-update
│   ├── updates/                 # OS package update check/apply
│   ├── winexec/                 # PowerShell invocation on Windows
│   └── workloads/               # containers and units/services
├── installer/                   # Windows: setup.ps1, nssm.exe, WiX .wxs
└── .gitea/workflows/agent-release.yml

Relationship to the other repositories

Repository	Relationship
vantage-shared	a private Go module. grpc/pb and grpc/codec are the wire contract; proto/ there documents them
vantage	the control plane. No import in either direction — the coupling is the gRPC wire, and it is entirely mediated by vantage-shared

vantage-shared is private, so every Go build needs GOPRIVATE=gitea.hostxtra.co.uk/* plus a credential. CI writes a netrc from REGISTRY_USER + RELEASE_TOKEN (that token needs read access to the vantage org) — twice, because the msi job is Windows and Go looks for _netrc in the profile directory there, not .netrc. Locally, either a netrc or git config --global url."git@gitea.hostxtra.co.uk:".insteadOf https://gitea.hostxtra.co.uk/.

A wire change is three steps, in order

shared/grpc/pb is hand-written and shared by both sides, so a new message is a compile error rather than a silent disagreement — but only once each side moves:

1. release vantage-shared (and change proto/vantage/v1/vantage.proto in the same commit as the Go types)
2. bump the pin in vantage's server/go.mod — live at the next push to main
3. bump the pin here — live only at the next agent/v* tag

The control plane runs ahead of the fleet in between. That was true before the split too; it is now explicit in two go.mod files rather than implicit in a shared directory.

Releases

Tags are agent/v*, not bare v*, even though this repository is only the agent. The tag is not a private detail: it is what the fleet downloads by, what UpdateAgentCmd carries, and what the control plane greps release tag names for when answering GET /api/agent/latest-version. Renaming it would be a second breaking change stacked on the repository move.

git tag agent/v1.2.0 && git push origin agent/v1.2.0

Builds linux/amd64, linux/arm64 and windows/amd64, writes checksums.txt, creates the Gitea release. A second msi job on windows-2022 builds the exe again, packages it with WiX and appends the MSI to the same release through the API — gitea-release-action cannot find a tag with a slash in it.

The self-update path, and what the move broke

internal/sync downloads its own replacement from <gitea>/vantage/vantage-agent/releases/download/<tag>/…, verifying the SHA-256 from checksums.txt before swapping itself. That path is compiled into the binary.

Every agent built before this move has the old path — mrhid6/vantage — baked in, and releases are no longer published there. For those agents the push-button update in the UI will fail: the download 404s. They are not stranded, because /update and /update.ps1 are generated by the control plane at request time and point wherever the current server says, so re-running the update one-liner on a host moves it onto a build that knows the new address. After that, self-update works again permanently.

This was a deliberate choice — the alternative was publishing releases to a repository that no longer holds the source — but it means the fleet needs one pass of the update one-liner, and the control plane must be redeployed with the new release paths first, or the one-liner points at the old repository too.

What the agent will not do

• It never reboots a host. ApplyUpdatesCmd installs and stops there; inventory.reboot_required reports that one is owed.
• It decides what it will not touch. The protected workload set is computed and enforced agent-side — vantage-agent.service, VantageAgent on Windows, and its own container ID from /proc/self/cgroup. The control plane may name a target; the agent decides what it will do to itself. A server-side denylist alone would be bypassed by the next dispatch path someone adds, and the failure is unrecoverable from the UI.
• The console relay dials 127.0.0.1 only. The host is hardcoded here, so the control plane can name a port and nothing else.
• No authorized_keys management on Windows, and no package inventory: a Windows agent never calls ReportPackages, so no server_packages document exists for it at all — a different, earlier state than the unsupported a Linux distribution reaches when its family has no security feed.

Platform split

Windows support is build tags, not runtime branches — systemd_linux.go / services_windows.go and the matching control_ and logs_ pairs. Windows collection runs PowerShell through internal/winexec, and every script that reports data emits JSON that a build-tag-free parser reads, so those parsers are tested on Linux. This module has no Windows CI: the control verbs and serviceDisplayName emit no JSON, have no parser, and are exercised only by running the agent on Windows.

Windows updates go through the Windows Update COM API (Microsoft.Update.Session) rather than the PSWindowsUpdate module, which would need a PowerShell Gallery install on every host and fails on an air-gapped fleet. CurrentVersion is empty on Windows and NewVersion carries the KB article ID: a Windows update is not a version bump of a named package.

Two constants that mirror the control plane

Neither can be shared — this is a separate module and the control plane's are under internal/ — so both must change in step, by hand:

• the workload log cap, 500 lines and 256KB whichever binds first, mirrored in the control plane's services.MaxWorkloadLogLines
• streamHealthyAfter and the 70s command-stream watchdog, which pair with the control plane's 20s PingCmd. The watchdog arms only after a first ping has been seen, so an older server that sends none is treated as working rather than put into a reconnect loop.