Upgrading and versions
To upgrade the Hosted Agent you run a newer container image. This page explains how, and how the version string you see in the console relates — and doesn't relate — to what you're actually running.
Image tag vs. reported version
Two different values describe an agent's "version," and they are independent:
| Value | Example | What it is |
|---|---|---|
| Image tag | apisec/hostedagent:<date>-<build> | The Docker image the container runs. This is the software you actually have. Take the current tag from the install command. |
| Reported version | v3.1 | The BROKER_VERSION environment variable, which the agent includes in every status report. The console displays this string as the agent's version. |
The reported version is display-only passthrough: the agent sends whatever BROKER_VERSION is set to, and the platform stores and shows it. Changing BROKER_VERSION does not change the agent's behavior, and nothing validates that the string matches the image tag. The install command sets both values together, which keeps them consistent — an agent deployed any other way can report a version that has nothing to do with its image.
To know what software an agent runs, check the container's image tag on the Docker host (docker inspect), not the version shown in the console.
Upgrade to a newer image
Re-download the install command rather than hand-editing your old one — the download always carries the current image tag and template.
-
In Manage Hosted Agents, download the install command for your agent again.
-
On the Docker host, stop and remove the existing container:
docker stop <container-name>
docker rm <container-name> -
Run the newly downloaded install command.
-
Confirm the agent shows ACTIVE in the console and reports the new version.
If you run the new install command while the old container is still running, the script warns and prompts before continuing — it asks the platform whether an instance on the same token has heartbeated within the last 30 seconds, so detection works even when the old container runs on a different host. (On the same host, the second docker run also fails outright because the container name is fixed per agent.) Two containers on one token both stay registered and share the agent's work — see Scaling with replicas if that's what you want; for an upgrade, stop and remove the old container first.
Token lifecycle during upgrades
Upgrading does not require touching the token:
- Re-downloading the install command renews the token. While the agent's current token is still valid, the download issues a token with the same identity and a fresh 180-day lifetime. The token already running stays valid, so re-downloading never invalidates a running agent.
- Rotating the token revokes immediately. Rotation invalidates all previously issued tokens the moment it happens and sets the agent back to PROVISIONED. Every running container for that agent starts getting 401s and must be redeployed with the new
BROKER_TOKEN.
Tokens are valid for 180 days. If the token has expired, re-downloading the install command mints a fresh one automatically.
Re-downloading also renews a token that has not expired yet: every download carries a fresh 180-day expiry, and access is judged on the token presented, not on a stored date.
A running container keeps using the token it was started with, so it keeps the expiry that token was issued with. To move an agent onto the renewed expiry you have to redeploy it with the re-downloaded command, which restarts that container. What you avoid is a simultaneous cutoff: because the old token stays valid, you can redeploy replicas one at a time rather than having every replica lose access at once.
Renewal this way is not unlimited. A re-download reuses the existing token identity only while the agent's recorded expiry is still in the future. Once that date passes, the next download mints a new identity, which invalidates the token any running container is still using. Rotating the token is what moves the recorded date forward, and it revokes the old token for every replica at once — so plan a rotation for a window where the whole fleet can be redeployed together.
The expiry date shown in the console reflects the last rotation, not the last re-download. After renewing this way, the console — and the expiry warnings derived from it — can continue to show the older date.
Rotate when you need to revoke, not to renew: a token you believe was exposed, or one you want to invalidate deliberately.
Redeploy or refresh the token?
| Situation | Do this |
|---|---|
| A newer agent image is available | Re-download the install command and redeploy. The token is untouched. |
| Token already expired | Re-download the install command and redeploy — the download mints a fresh token because the old one is unusable. |
| Diagnostics warn the token expires in 7 days or less | Re-download the install command and redeploy. That moves the agent onto a fresh 180-day expiry. The redeploy restarts the container, but the old token stays valid meanwhile, so replicas can be rolled one at a time. Rotation is not needed here. |
| Token may have been exposed | Rotate the token in the console, then redeploy every container for that agent with the new token — rotation cuts them all off immediately. |
What this page doesn't cover
The console may show additional upgrade- or version-related labels. What those labels mean, and whether any platform behavior is gated on an agent's version, is determined outside the agent and is not documented here. If an agent appears blocked on a version-related message, contact APIsec support.