Connector management
Admins manage connectors from the Connectors area of the app. A connector is healthy when it is enrolled, has a valid identity, and reports a current heartbeat.
Common tasks
Add a connector
Use Add connector to generate an enrolment token and download the installer for the target host. The app shows the next step for Docker or the native binary.
If the deployment does not use persistent /data, treat the connector as guided-recovery capable only. The configuration must still be preserved outside /data; only runtime identity is expected to break on restart.
Rotate an enrolment token
If a token expires before installation, generate a fresh one from the connector detail page. Tokens are meant to be short-lived and single-use.
Monitor health
Watch the connector status column for:
- Online when the heartbeat is healthy.
- Offline when the connector is not reporting.
- Degraded when the connector is alive but cannot reach everything it should.
Read connector logs
Use the logs view when you need installation errors, heartbeat gaps, or routing failures. Logs are the fastest way to confirm whether the connector can reach the target network.
Delete a connector
Delete a connector only when you are sure nothing routes through it anymore. If the connector lost its identity and can no longer recover, generate a new enrolment token and pair a replacement instead of trying to reuse the broken record.
Certificate lifecycle and renewal
When a connector enrols, it generates a private key and receives a short-lived client certificate. That certificate is the connector's identity: it is what authenticates the connector's tunnel to the platform (mutual TLS). Certificates are intentionally short-lived, so every connector renews its certificate automatically — no admin action is required in normal operation.
How renewal works
A connector renews its certificate before the current one expires. Each certificate has a renew-after point (by default, 12 hours before expiry). Renewal is triggered two ways, and you do not need to choose between them:
- Proactively, on a background timer. A healthy, continuously-connected connector checks roughly every 5 minutes whether it has reached the renew-after point, and renews on its own — even if it never disconnects. This keeps long-lived connectors current without waiting for a reconnect.
- On reconnect. Whenever a connector reconnects (after a network blip, a restart, or a host reboot), it also renews if it has passed the renew-after point. This has always been the behaviour and remains as a safety net.
During renewal the connector generates a fresh key and certificate and stores them; the previous certificate is superseded.
What you may notice
Adopting a freshly renewed certificate requires the connector to re-establish its tunnel. This is a brief reconnect — typically under a second — but it does momentarily interrupt in-flight sessions routed through that connector. With proactive renewal this reconnect happens around the renew-after point (well before expiry), at a predictable time, rather than at the unpredictable moment the certificate would otherwise expire. The connector returns to Online immediately afterwards.
If you see a connector briefly flip to Reconnecting and back to Online roughly twelve hours before its certificate would expire, that is expected — it is the renewal adopting the new certificate.
Advanced: disabling proactive renewal
Proactive renewal is on by default. In rare cases an operator can disable it on a specific connector host by setting the environment variable PAM_AGENT_PROACTIVE_RENEWAL=0 before the connector starts. The connector then falls back to renewing only on reconnect. Leave this enabled unless instructed otherwise by support — disabling it on a connector that stays connected for long periods can let its certificate approach expiry.