Mutual TLS (mTLS)

The agent authenticates to this backend by enrolling for its own mTLS client certificate — there is no API key, no bearer token to configure at runtime, and no alternative auth mode. You never have to create or handle the certificate yourself; the agent generates its own key and gets it signed during enrollment.

The key idea: the agent enrolls to obtain a certificate. On first boot it proves who it is with a one-time credential (an enrollment token, or its cloud identity), the backend issues it a certificate, and the agent saves that certificate to disk. From then on it presents the certificate on every connection — that's the whole authentication story; there's no separate key to manage, rotate, or fall back to.

You don't create the certificate

CONNXL_MTLS_CERT and CONNXL_MTLS_KEY are just file paths where the agent stores the certificate it's issued — not a certificate you supply. The agent generates its own private key (which never leaves the host) and gets the signed certificate from the backend during enrollment.

Where the enrollment token comes from

Most of the time you never touch a token: Download configured agent on the environment's Agent page (the Deploy tab) stamps a fresh one straight into the binary, and the agent spends it enrolling on first boot. Each configured download mints its own token and they accumulate — downloading several never invalidates the earlier ones, so you can stand up many replicas of an environment's agent.

You only copy a token by hand for the manual path (containers, IaC, automation). Click Regenerate on the same panel to reveal one once — copy it now — alongside a ready-made env-var snippet pre-filled with your IDs. Note that Regenerate revokes every token already issued for this environment (every configured binary you'd downloaded and any prior manual token) and hands you a single fresh one in their place. So reach for it in two cases: to mint a manual token, or to cut off a leaked or stale download.

Who can do this

Minting an enrollment token — whether by downloading a configured agent or clicking Regenerate — is an admin action, and the token is least-privilege: it does nothing except let one agent obtain its certificate for this one environment.

Regenerate takes this environment's running agents offline

Regenerate is a kill switch, not just a re-mint. On top of superseding the old tokens it revokes every active mTLS certificate for this environment and force-closes the live control and config channels, so every agent already running here drops immediately and stays out until it re-enrols with the new token.

That is deliberate — it is how you cut off a leaked token and the agents it stood up, in one click. But it means Regenerate is not the way to get a token for an extra replica. For that use Download configured agent, which mints its own token and revokes nothing.

Set the certificate paths and the token

On the agent host, set the backend URL, the enrollment token, and the two paths where the agent should store its certificate and key:

environmentsh

CONNXL_BACKEND_URL=https://<this-backend-host>
CONNXL_ENROLL_TOKEN=<your-enrollment-token>
CONNXL_MTLS_CERT=/etc/connxl/agent-cert.pem
CONNXL_MTLS_KEY=/etc/connxl/agent-key.pem

Two different certificates — don't mix them up

These CONNXLMTLS* paths are for the agent-to-backend channel. They are not the cert.pem / key.pem that Office requires for the agent's own HTTPS — that pair is separate and still required. Point the two at different files.

Start the agent

Start the agent as usual. Because there's no certificate on disk yet, it enrolls: it generates a key and a signing request, sends the request to the backend with your token, and writes the issued certificate to the two paths above. On every later start it finds the certificate already there and just presents it — no re-enrollment.

The token is spent the moment it's used

Once the agent has an enrolled certificate, that certificate is its ONLY credential — the enrollment token that got it there is already consumed and can be discarded. To re-enroll a replacement host, download a fresh configured binary (each carries its own token) or mint a manual one with Regenerate — remembering that Regenerate revokes all outstanding tokens for the environment, so use it deliberately.

No token? Use the agent's cloud identity

If the agent runs on AWS, GCP, or Azure, it can enroll with no token to copy at all — it proves its identity with the cloud provider's signed instance document. Two things to set up:

Authorize the instance first. On the environment's Agent page, open the Security tab and add a rule under Trusted cloud identities for the provider and the account, project, or subscription the agent runs in (optionally pinned to specific regions). Only instances matching a rule may enroll.
Set the attestation env vars instead of the token — the provider plus the add-in and environment IDs (both shown on the Agent page):

environmentsh

CONNXL_BACKEND_URL=https://<this-backend-host>
CONNXL_ENROLL_ATTESTATION=aws        # or gcp | azure
CONNXL_ADDIN_ID=<your-add-in-id>
CONNXL_ENV_ID=<your-environment-id>
CONNXL_MTLS_CERT=/etc/connxl/agent-cert.pem
CONNXL_MTLS_KEY=/etc/connxl/agent-key.pem

Renewal is automatic

Once enrolled, the agent renews its certificate on its own well before it expires — there's nothing to rotate by hand and no downtime to plan for.

If the agent stays offline long enough for the certificate to lapse entirely, renewal is no longer possible — a lapsed certificate can only be replaced. The agent handles that too: as long as its enrollment token is still set it enrols again automatically, at startup or as soon as it notices. If no token is configured it stops at startup and tells you which variable to set, rather than retrying quietly.

Install the add-in

The base agent setup that mTLS builds on — host, TLS, and the manifest.

Dashboard

Where the install page and environment settings live.