# Connecting a server to the dashboard

> Add your OpenShield server in the console, test the connection against /health, understand each failure, and read live metrics.
>
> Canonical: https://xdp.network/docs/openshield-xdp/connecting-a-server · Updated 2026-08-09

Once the agent is installed and metrics are enabled, you connect the server in the console
so the dashboard can poll it. The whole flow takes about a minute per server.

## Add the server in the console

1. Open your product page in the dashboard and choose **Add server**.
2. Enter a name, the **Metrics API URL**, and the **API key** — both printed by
   `openshield key` on the server.
3. Click **Test connection**. The console calls `/health` on the agent from the server
   side, using your key.
4. When the test passes, click **Save**.

## What each test failure means

| Failure | Cause | Fix |
| --- | --- | --- |
| Unreachable | The console cannot open a connection to the URL | Check the URL, and that the `metrics.listen` port is reachable from outside |
| 401 | Invalid key | Re-copy the key from `openshield key` |
| 403 | Caller IP not whitelisted | Add the console egress range to `metrics.whitelist` and run `openshield reload` |
| Timeout | The agent accepted the connection but answered too slowly | Set `auto_fetch.mode: dedicated` so large updates do not stall responses, and confirm the port is reachable |

:::tip
If the test fails, run the same check by hand from an allowed host:
`curl -H "Authorization: Bearer osk_…" http://server:9100/health`. Whatever curl reports is
what the console is seeing.
:::

## After the server connects

Within a few seconds of saving, the server row turns green and the **live metrics** tab
starts filling in: traffic, attack forensics, bans, and geo analytics. The console polls
the agent from the server side; your API key is stored server-side and never shown to
browsers.

If the row stays grey or flips back to offline, work through the
[troubleshooting guide](/docs/troubleshooting/server-shows-offline).

## Next steps

- [Server shows offline](/docs/troubleshooting/server-shows-offline)
- [Tuning profiles](/docs/openshield-xdp/tuning-profiles)
- [Enabling metrics](/docs/openshield-xdp/enabling-metrics)