Update an agent

The Agents page shows each agent’s version. When an agent is behind the current release, its row and page show Update to version, which opens the commands for the way it runs (Docker, Docker Compose or the installer). The console cannot update an agent by itself: the command runs on the agent’s host.

An update keeps the agent’s key, its hostnames and its TCP services. Open previews pause for a few seconds while it reconnects.

Docker

docker pull ghcr.io/synically-ackward/houseguest-agent:<version>
docker rm -f houseguest-agent

Then run the original docker run command again with the new image tag and without HG_JOIN. The key stays in the houseguest-agent volume, so it reconnects as the same agent.

Docker Compose

Set image: ghcr.io/synically-ackward/houseguest-agent:<version> in compose.yaml, then in its folder:

docker compose pull
docker compose up -d

No Docker (Linux)

curl -fsSL https://get.houseguest.dev/install-agent.sh | sudo sh -s -- --upgrade

--upgrade installs the current release over the houseguest-agent service, checks its checksum, keeps the settings and key, and restarts it. Add --version X.Y.Z for a particular release. During early access, the download details come with your early-access invitation, as for the first install.

Check

The agent’s page shows the new version once the agent reconnects. From the host, docker logs houseguest-agent (or journalctl -u houseguest-agent) shows connected to ….

Rotate an agent’s key

There is no in-place key rotation. To give a host a new key, join it again as a new agent:

1. Create a new join token in the console (Agents → Add agent) with the same name and hostnames.
2. On the host, stop the agent, delete its volume (docker volume rm houseguest-agent), and start it again with the new HG_JOIN.
3. Turn the same hostnames on for the new agent, if it uses a wildcard.
4. Remove the old agent in the console.

If your workspace is at its agent limit, remove the old agent first.