Skip to main content
View as MarkdownOpen in ChatGPTOpen in Claude

Edge agent versions and upgrades

This page lists every released version of the Axiad edge agent, what changed in each one, and how to move your agent from one version to another. It's for whoever runs the agent on your host. If you haven't installed the agent yet, start with Run the edge agent.

The agent never updates itself. You choose when to upgrade, and you can stay on an older version until you're ready.

Which version should I run?​

Run the latest version in the table below unless Axiad support asks you to use a different one. When your administrator registers a new agent, the command they send you already names the version to use.

To see which version you're running now, either:

  • ask your administrator — Mesh shows it on the agent's Overview tab, or

  • check the container on your host:

    docker inspect axiad-edge-agent --format '{{.Config.Image}}'

    The part after the last : is the version, for example ...mesh-edge-agent:1.0.3.

Release history​

Select a version, or its Details button, to see everything that changed in it and anything to know before you upgrade or go back.

VersionReleasedWhat changedUpgrade notesDetails
latestOctober 26, 2026Stronger protection for connector credentials, cleaner decommissioning, smoother upgradesNo extra steps to upgrade. Going back to 1.0.2 or earlier needs one extra step.
September 3, 2026New agent status command, clearer error messagesNo extra steps.
August 25, 2026Compatibility updateNo extra steps.
August 24, 2026First release—

Version 1.0.3latest

Released October 26, 2026

What's new

  • Stronger protection for your connector credentials. The agent now adds an extra layer of protection to the passwords and API keys it keeps for your connectors. It applies this to your existing connectors automatically the first time 1.0.3 starts — there's nothing for you to do.
  • Cleaner decommissioning. When your administrator decommissions the agent in Mesh, the agent now removes its certificate, connector settings and credentials from your host by itself, then stops for good. If the agent is offline at the time, it tidies up as soon as it reconnects. If you're on an earlier version, see Remove it under Keeping it running to tidy up the host yourself.
  • Additional safeguards for the instructions the agent receives from Mesh.
  • Smoother upgrades and restarts. If you start a new agent container before the old one has fully stopped, the new one now waits up to a minute for the old one to finish. If the old one is still running after that, the new one stops and tells you (in use by another agent process).
  • More reliable certificate renewal. Improvements to how the agent renews its certificate automatically.
  • Updates to the third-party components the agent is built on.

Upgrading to 1.0.3: follow Upgrade to a new version. No extra steps.

Going back from 1.0.3: 1.0.3 saves the agent's settings in a new format that versions 1.0.2 and earlier don't understand. To go back to one of those, follow Roll back to 1.0.2 or earlier rather than just starting the old container — it's one extra step.

Version 1.0.2

Released September 3, 2026

  • New agent status command. Check the agent's state from inside the container, as shown in Step 3 of Run the edge agent.
  • Clearer start-up messages. If the enrollment token didn't make it into the container, the agent now says so plainly (config: ENROLL_TOKEN is set but empty). It also stops with a clear message if a MESH_GATEWAY setting points somewhere other than the address in your token, so it can't join the wrong Mesh environment by mistake.
  • Clearer connection messages. If a secure connection fails because of a certificate mismatch, the message now names both the host the certificate was issued for and the host the agent expected, which makes the cause easy to spot.
  • Updates to the third-party components the agent is built on.

Version 1.0.1

Released August 25, 2026

  • A small compatibility update for the agent's connection to Mesh. Nothing changes in how you run the agent or what it does.

Version 1.0.0

Released August 24, 2026

  • First release of the Axiad edge agent.

Every version runs on Linux, on both x86-64 (amd64) and ARM64 hosts. Docker picks the right one for your machine automatically.

Tags that start with beta-

The image registry also holds tags named beta- followed by a number. These are pre-release builds — whatever their number, they are not newer releases than the ones listed here. Use one only if Axiad support asks you to.

Upgrade to a new version​

An upgrade swaps the container for one running the new version. The agent's identity and settings live in its storage (the mesh-edge-data volume), which the new container reuses — so you don't need a new enrollment token, and your connectors carry on where they left off.

In the commands below, replace 1.0.3 with the version you're upgrading to, and axiad-edge-agent with your container's name if it's different.

Write down your current settings first​

You can't recover these after the old container is removed

Whatever flags your running container actually has — a custom --user, an extra -e, a host directory instead of the named volume — only exist in that container's own settings. Check what's really running, not just what the example in this guide shows:

# Storage — confirm the exact volume (or host path) and where it's mounted. If this
# doesn't match -v mesh-edge-data:/var/lib/mesh-edge, use what's shown here instead
# when you start the new container.
docker inspect axiad-edge-agent --format '{{range .Mounts}}{{.Type}} {{.Name}}{{.Source}} -> {{.Destination}}{{"\n"}}{{end}}'

# User — if the value in quotes is not empty, pass the same --user value to the new
# container. Otherwise it can fail with `permission denied` on its own storage.
docker inspect axiad-edge-agent --format 'User: "{{.Config.User}}"'

# Environment variable names in use (values are left out on purpose, so a token
# doesn't end up in your terminal history).
docker inspect axiad-edge-agent --format '{{range .Config.Env}}{{.}}{{"\n"}}{{end}}' | cut -d= -f1

Step 1 — Download the new version​

docker pull axiadpublicregistry.azurecr.io/mesh-edge-agent:1.0.3

Step 2 — Stop the current agent and keep it as a backup​

Rename the old container instead of removing it. If anything goes wrong, getting back is a rename and a start rather than rebuilding the container from memory.

docker stop axiad-edge-agent
docker rename axiad-edge-agent axiad-edge-agent-previous

Step 3 — Start the new version​

Use the same settings you wrote down above. This is the standard command from Run the edge agent, with the token left empty because the agent already has its identity:

docker run -d --name axiad-edge-agent --restart unless-stopped --user 0:0 \
  -e ENROLL_TOKEN="" \
  -e MESH_SSRF_ALLOW_PRIVATE=1 \
  -e STRICT_CONFIG_SIGNING=true \
  -v mesh-edge-data:/var/lib/mesh-edge \
  axiadpublicregistry.azurecr.io/mesh-edge-agent:1.0.3

Step 4 — Check that it's healthy​

Check it the same way as Step 3 of Run the edge agent:

docker logs axiad-edge-agent 2>&1 | grep -E 'agent.connect ok|heartbeat|permission denied'

You want to see agent.connect ok and a heartbeat, and no permission denied lines. Your administrator should see the new version on the agent's Overview tab in Mesh.

Step 5 — Remove the backup when you're sure​

Keep the backup until you're confident you won't need to go back — for example, until each of the agent's connectors has completed a collection run on the new version. Both ways of rolling back start from it. A stopped container does nothing in the meantime.

When you're ready, remove it:

docker rm axiad-edge-agent-previous

Roll back to the previous version​

If the new container won't start or keeps restarting, go back to the version you had. How you do that depends on the versions involved.

Both procedures below start the backup container from Step 2. If you've already removed it, use the Step 3 command instead, with the version you're going back to in place of 1.0.3 and the settings you wrote down.

Roll back to 1.0.3 or later​

If the version you're going back to is 1.0.3 or later, remove the new container and start the backup:

docker rm -f axiad-edge-agent
docker rename axiad-edge-agent-previous axiad-edge-agent
docker start axiad-edge-agent

Roll back to 1.0.2 or earlier​

Version 1.0.3 and later save the agent's settings in a format that 1.0.2 and earlier don't understand. So before you start the older version, run a quick one-time prepare step with the newer version. It converts the saved settings back to the older format.

Only for rolling back

Run the prepare step only when you're going back to 1.0.2 or earlier, and only as the one-off command below — never add EDGE_AGENT_PREPARE_DOWNGRADE to a container you keep running.

  1. Stop the newer agent. The prepare step refuses to run while an agent is using the storage.

    docker stop axiad-edge-agent

  2. Run the prepare step with the newer version, using the same storage and --user as your agent:

    docker run --rm --user 0:0 \
      -e EDGE_AGENT_PREPARE_DOWNGRADE=1 \
      -v mesh-edge-data:/var/lib/mesh-edge \
      axiadpublicregistry.azurecr.io/mesh-edge-agent:1.0.3
    echo "exit code: $?"

    It doesn't connect to Mesh and doesn't need a token. Check how it finished:

    Exit codeWhat it meansWhat to do
    4Done. The log ends with stop this agent and install the older binary.Go to step 3.
    2Some connectors have credentials the older version can't use yet. The message names them.Start the newer agent again (docker start axiad-edge-agent). Ask your administrator to turn off those connectors on the agent's Connectors tab in Mesh. Once the agent's Activity tab shows Config applied, stop the agent and rerun this step.
    5An agent is still running on this storage. Nothing was changed.Stop it and rerun this step.
    6Almost done — a final clean-up didn't finish.Rerun this step until it exits with 4.
    1Something else went wrong. Nothing was changed.Read the message, fix what it describes, and rerun. If you're stuck, contact Axiad support — we're happy to help.

  3. Start the older version from your backup (or, if you no longer have one, with the Step 3 command and the older version's tag):

    docker rm -f axiad-edge-agent
    docker rename axiad-edge-agent-previous axiad-edge-agent
    docker start axiad-edge-agent

  4. Turn the connectors back on. If your administrator turned off any connectors in step 2, they can turn them back on now. They'll work with the older version.

Last updated on