# Agent lifecycle script

`vps-agentctl.sh` installs signed/checksummed release artifacts without piping a
network response into a shell. Run a locally inspected copy as root.

```bash
./vps-agentctl.sh install --version v0.1.0
./vps-agentctl.sh update --version v0.1.1
./vps-agentctl.sh status
./vps-agentctl.sh restart
./vps-agentctl.sh version
./vps-agentctl.sh rollback
./vps-agentctl.sh remove
./vps-agentctl.sh remove --purge --yes
```

Set `VPS_AGENT_RELEASES_URL` or pass `--releases-url` for a GitHub-compatible
releases root. Set `VPS_AGENT_MINISIGN_PUBLIC_KEY` to require verification of
`SHA256SUMS.minisig`; checksums are always mandatory. Supported artifact names
are `vps-agent-linux-amd64` and `vps-agent-linux-arm64`.

Each architecture can be built and packaged independently on its matching Linux
builder. An amd64-only release does not require an arm64 binary:

```bash
./scripts/build-agent-native.sh dist
```

The script detects the current Linux host architecture, builds the release
binary, and packages only that architecture. To package an existing binary:

```bash
./package-agent-release.sh --output dist --amd64 path/to/x86_64/vps-agent
```

Use `--arm64 path/to/aarch64/vps-agent` on a separate arm64 Linux builder. Both
options may also be passed in one invocation after the artifacts have been copied
to the same machine. The script regenerates `SHA256SUMS` for every canonical
artifact already present in the output directory and supports both Linux
`sha256sum` and macOS `shasum -a 256`.

Native macOS builds produce Mach-O binaries and cannot be published as Linux
agent artifacts. macOS may be used to combine and sign Linux binaries that were
built independently on matching Linux hosts.

Packaging produces the selected canonical names and `SHA256SUMS`; when
`VPS_AGENT_MINISIGN_SECRET_KEY` is set it also creates `SHA256SUMS.minisig`.

Install checks root, Linux/systemd and architecture, creates the locked service
user/directories, validates the binary before installation, writes safe config
and a random token, installs hardening, and starts the unit. Update stages the
new binary and automatically restores the previous one when the service health
check fails. `rollback` swaps current/previous versions.

Remove preserves `/etc/vps-agent` by default. `--purge` removes credentials and
requires a terminal confirmation or the explicit `--yes` flag.