Skip to main content
View as MarkdownOpen in ChatGPTOpen in Claude

Run the edge agent

This guide is for the person who runs the Axiad edge agent on a host inside your network — usually someone on your IT or infrastructure team. Your Mesh administrator will send you a one-time enrollment token and a command to run.

Who this is for

If you manage connectors in the Mesh dashboard instead, see Set up an on-prem connector.

What the edge agent is​

The edge agent is a small container you run on a host inside your network. It lets Mesh collect from internal systems that aren't reachable from the internet. It connects out to Mesh over HTTPS and keeps a secure channel open — it never accepts inbound connections, so you don't open any firewall ports for it.

Before you begin​

You'll need:

  • A Linux host inside your network with Docker (or a compatible container runtime) installed.
  • Outbound HTTPS (443) from that host to Mesh. No inbound ports.
  • Network reachability from that host to the internal systems you want Mesh to collect from.
  • From your Mesh administrator: the one-time enrollment token and the run command.
warning

The enrollment token is valid for a short time and can be used only once. Run the command soon after you receive it. If it expires, ask your administrator to issue a new one.

Step 1 — Prepare the data directory​

The agent runs as a non-root user (uid 65532) and keeps a little state on disk, so create its data directory and give it ownership. The command from your administrator includes these two lines:

sudo mkdir -p /var/lib/axiad-edge
sudo chown 65532:65532 /var/lib/axiad-edge
warning

If you skip this, the container fails to start with an error like mkdir .../store: permission denied.

Step 2 — Pull and run the agent​

Run the command your administrator gave you. Your token and the exact image version are filled in for you; it looks like this:

docker pull axiadciregistry.azurecr.io/mesh-edge-agent:<version>

docker run -d --name axiad-edge-agent --restart unless-stopped \
  -e ENROLL_TOKEN='<your-one-time-token>' \
  -e MESH_SSRF_ALLOW_PRIVATE=1 \
  -v /var/lib/axiad-edge:/var/lib/mesh-edge \
  axiadciregistry.azurecr.io/mesh-edge-agent:<version>

What the parts mean:

  • ENROLL_TOKEN — your one-time enrollment token. The agent uses it once to enroll, then keeps its own identity, so you won't need it again. The token also tells the agent where Mesh is — there's nothing else to configure.
  • MESH_SSRF_ALLOW_PRIVATE=1 — lets the agent reach systems on your private network. Leave it in if any target is internal (the usual case); you can omit it if every target is publicly reachable.
  • -v /var/lib/axiad-edge:/var/lib/mesh-edge — gives the agent the data directory you prepared in Step 1.
  • --restart unless-stopped — brings the agent back automatically after a reboot.

Step 3 — Verify it enrolled and connected​

Watch the logs:

docker logs -f axiad-edge-agent

Look for these lines, in order:

  • enroll: success — the agent registered with Mesh.
  • connect: gateway stream open — the secure channel is up.
  • heartbeat: initial tick sent — it has checked in and is healthy.

You can also ask the agent directly:

docker exec axiad-edge-agent agent status
  • Enrolled: agent kid=... issued_at=... not_after=... (the not_after value is when its certificate expires — renewal is automatic).
  • Not yet enrolled: agent: not enrolled.

Once it's up, let your administrator know — the agent will show Enrolled in the Mesh dashboard.

Keeping it running​

  • Restart: docker restart axiad-edge-agent. The agent reuses its stored identity and reconnects — no new token needed.
  • Stop: docker stop axiad-edge-agent. It shuts down cleanly (boot: shutdown complete) and won't start again until you tell it to.
  • After a host reboot: --restart unless-stopped starts it automatically.
  • Certificate renewal: handled automatically while the agent is running — nothing for you to do.
  • Decommission: if your administrator decommissions the agent in Mesh, it shuts itself down and won't reconnect. To retire a host yourself, stop and remove the container (docker rm -f axiad-edge-agent) and delete /var/lib/axiad-edge.

Behind a proxy​

If the host reaches the internet through an HTTP proxy, pass it to the container the usual Docker way, for example by adding -e HTTPS_PROXY=http://proxy.example.com:8080 to the docker run command.

Troubleshooting​

SymptomFix
Container exits immediately; logs show mkdir .../store: permission deniedThe data directory isn't owned by uid 65532. Re-run the chown from Step 1.
Logs show enroll: ENROLL_TOKEN expired or enroll: ENROLL_TOKEN required...The token expired or wasn't passed. Ask your administrator to issue a new one and re-run.
You never see connect: gateway stream openThe host can't reach Mesh outbound on 443. Check your egress firewall and DNS.
A connector test can't reach an internal systemConfirm the host can reach that system, and that MESH_SSRF_ALLOW_PRIVATE=1 is set.
tip

For more detail while diagnosing, add -e MESH_LOG_LEVEL=debug to the docker run command.

Verify​

  • docker logs shows enroll: success and connect: gateway stream open.
  • docker exec axiad-edge-agent agent status shows agent kid=....
  • Your administrator sees the agent as Enrolled in Mesh.