Upgrade a sensor on Linux (Docker)
An upgrade is a new image tag and a container replacement. Because the sensor's identity lives in the mounted data directory rather than in the container, the upgraded sensor rejoins as the same sensor — same name, same history, same integration assignments. There is no re-enrolment and no new deployment token.
This assumes the layout from
Install a sensor on Linux (Docker), where ./data/
and ./logs/ are mounted from the host. A sensor installed from an older version
of that page may also mount a config.json, and its service may have a different
name; both keep working, and neither needs to change for an upgrade.
Before you start
Find the version to move to. The release notes list every Velum Edge release, newest first — the latest entry is the version you want, and its notes are where anything you need to know before upgrading is called out. Subscribe to the RSS or Atom feed if you would rather be told than remember to look.
Pick your moment. A task the sensor is running when the container stops is requeued when the sensor comes back rather than lost, but it does start again from the beginning. For a sensor that runs long active scans, upgrade between runs: Scan history shows what its integrations are running.
The console refuses every request from a disabled sensor, uploads included, so a scan that finishes while its sensor is disabled cannot deliver its result. See Disabling, revoking and deleting.
Note the version you are on. The sensor list shows it, and it is what you compare against afterwards.
Let the console tell you
On the sensor's detail view, Update agent compares the version the sensor runs with the platform's own, and either says the agent is up to date or shows the image line to set and the command to run. It works for sensors whose Installation reads Docker. A sensor on an agent older than 0.9.1 does not report how it is installed, so the console answers "Unknown installation type": upgrade it by hand as below, and from then on it reports Docker.
The console cannot update a sensor itself. The container runs on your host, so the steps are always yours to run.
Update the image tag
Set the tag to the version the console names, or the one you took from the release notes:
image: ghcr.io/davydovvn/velumedge-agent:v0.9.1
Nothing else in the compose file changes. In particular, do not put a deployment
token back — the sensor already has its own API token in ./data/.
Pull and recreate
From the folder with docker-compose.yml:
sudo docker compose pull && sudo docker compose up -d
Confirm
Within a poll interval the sensor's Version in the console shows the new build and its last-seen time is current.
If the version does not move, the container is probably still the old one: a
docker compose up -d with an unchanged tag is a no-op. Check the tag, then the
sensor's output (sudo docker compose logs) or its log in the mounted logs/
directory. A self-test after the upgrade
confirms the new build has what it needs.
Rolling back
Set the previous tag and repeat the pull-and-recreate. The data directory is forward- and backward-compatible in the ordinary case, so the sensor rejoins on the older build as the same sensor.
Document which sensor versions are safe to roll back to, and whether any release changes the on-disk data format in a way that prevents it.
What not to do
Deleting ./data/, or starting with MODE: reset, throws away the API token. The
host then enrols as a new sensor with a fresh identity, and the old entry stays
in the console holding the integration assignments — which now point at a sensor
that no longer exists. Recovering means reassigning every integration by hand.
Upgrade a single, low-consequence sensor and let it run a full cycle before rolling the fleet. Mixed versions are expected and tolerated in the meantime; the sensor list's Version column is what tells you how far along you are.
See also
- Release notes — what each version contains, and which is current
- Install a sensor on Linux (Docker) — the layout this page assumes
- Sensors — status, mode and health