# 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.

> **note**
If you're the person who runs the agent on a server, see
**[Run the edge agent](./run-the-edge-agent.md)** 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](./run-the-edge-agent.md)**.

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](./run-the-edge-agent.md)**. Or add more connectors to the same
agent — one agent can serve several internal systems.