Installing the agent

:::note Placeholder page Paths and names below are taken from the agent's source as of a recent build and will be reconfirmed against each release. :::

The agent runs as a Windows service on each Hyper-V host you want Ballast to manage. It never invents intent — it only enforces the desired state most recently handed to it by the centre, which is what lets it keep a host steady if the centre goes offline.

1. Fetch the agent binary

If the centre was started with -agent-binary, it serves the installer directly, so a host with network access to the centre needs nothing pre-staged:

Invoke-WebRequest https://centre.example.internal:8080/agent/ballast-agent.exe `
  -OutFile ballast-agent.exe

2. Install and point at the centre

.\ballast-agent.exe -install -centre centre.example.internal:9443

This step:

• Installs the BallastAgent Windows service (process ballast-agent).
• Places the binary at C:\ballast\ballast-agent.exe.
• Requests and stores an agent certificate — ca.pem, agent-cert.pem, agent-key.pem — under C:\ballast, and adds the CA to the host's trusted root store.
• Creates C:\ProgramData\Ballast for the local state store (agent.db, holding the last-honoured desired state) and the agent log (agent.log).

The agent pulls its desired state and reports status on an interval controlled by -heartbeat, default 15 seconds.

Running -install -centre again on a host already pointed at a different centre repoints it — the new centre takes over that host. See Troubleshooting before doing this on a host you did not mean to move.

3. Confirm registration

Once the service starts, the host should appear in the centre's console inventory within one heartbeat interval. If it does not, see Troubleshooting.

Uninstalling

.\ballast-agent.exe -uninstall

This removes the service and binary. It does not delete C:\ProgramData\Ballast — remove that directory separately if you want the local state store and log cleared as well.