Set up an on-prem connector

This guide is for Mesh administrators. You'll register an edge agent, hand its install command to your agent operator, then add and test connectors once the agent is online.

Who this is for

If you're the person who runs the agent on a server, see Run the edge agent instead.

Before you begin

• A Mesh administrator account with permission to manage connectors.
• An agent operator — someone who can run a container on a host inside your network. You'll hand them a command; they can start as soon as you issue it.
• Details for the internal system you want to connect: its base URL and how it authenticates (for example, an API token).

Step 1 — Open On-prem agents

In the Mesh dashboard, go to Settings → On-prem agents. This page lists the agents running in your environments and notes that they are outbound-only. If you haven't added one yet, you'll see "No on-prem agents yet."

Step 2 — Register an agent

Select Add on-prem agent. In the dialog:

• Name — a name you'll recognize later, for example prod-east-1.
• Labels (optional) — key=value pairs that help you filter the list, for example region=us-east-1, env=prod.

Select Issue token →.

Step 3 — Copy the token and command

Mesh shows a one-time enrollment token and a ready-to-run command:

• Enrollment token — select Copy.
• Run on the customer host — the full command your operator runs. Select Copy in the top-right of the command block.

warning

The enrollment token is shown once. Copy it before you close the dialog — otherwise you'll need to register the agent again to get a new one.

Send both the token and the command to your agent operator over a secure channel. They'll follow Run the edge agent.

Tick "I've copied the token. I understand it can't be shown again.", then select Close.

tip

The token is valid for a short time and can be used only once. If it expires before your operator uses it, just add the agent again to issue a fresh one.

Step 4 — Wait for the agent to come online

Back on the On-prem agents list, your agent appears with a Status. Once your operator runs the command, the status turns Enrolled within a minute or so.

Status	Meaning
Unenrolled	Registered, but hasn't connected yet.
Enrolled	Connected and healthy.
Stale	Was enrolled, but hasn't checked in recently.
Decommissioning / Decommissioned	Being shut off / no longer trusted.

The list also shows each agent's Agent ID, Last seen, Labels, and Cert expires.

note

The agent renews its own certificate automatically while it's running. The Cert expires column is informational — you don't need to act on it.

Step 5 — Add a connector to the agent

Select the agent's row to open its details, then open the Connectors tab and select + Add connector. Follow the guided steps to point Mesh at your internal system — its base URL, the data you want to collect, and how to authenticate. Give the connector a display name and save it.

Connectors on an agent are grouped by status: Running, Pending, Failed, and Disabled.

Step 6 — Test the connection

While adding or editing a connector, select Test connection. Because the test runs on the agent — inside your network — it can reach systems that aren't publicly accessible.

• On success, you'll see Connection successful.
• On failure, you'll see an error describing what to fix (for example, authentication failed).

Managing an agent

Open an agent to see its details across several tabs:

• Overview — agent version, platform, when it enrolled, when it was last seen, and its labels.
• Connectors — the connectors running on this agent.
• Activity, Heartbeats, Logs — its recent history and check-ins.

To permanently retire an agent, open it and select Decommission, then confirm. This stops the agent from being trusted the next time it tries to connect, and the action is recorded in your audit log. Use it when a host is retired or you suspect it's compromised.

Verify

• The agent shows Enrolled.
• Your connector shows Running, or you saw Connection successful.
• Data from your internal system appears in Mesh on its next collection.

Next step

Hand off to your operator if you haven't already: Run the edge agent. Or add more connectors to the same agent — one agent can serve several internal systems.