Agents > Xedant Agent > Docs > SSL Certificates

SSL Certificates

When the agent runs at your own domain address, the connection to it is worth protecting: the HTTPS protocol encrypts the traffic, and the browser shows the real site address and a “lock” icon instead of unsafe-connection warnings. This normally takes third-party programs and manual setup, but Xedant Agent can issue free Let’s Encrypt SSL certificates right from its web interface — no Docker containers, no extra programs, no manually placed verification files. Open Settings → SSL Certificates in the app, enter the domain and an email — the certificate is obtained automatically and stored in the project’s configuration folder (.xedant/ssl/).

How it works

Built-in ACME client. The certificate is issued over the open ACME protocol — the technology behind automated certificate issuance at authorities like Let’s Encrypt. The application acts as the ACME client itself (the embedded Certes library runs right inside its process) — no separate certbot or Docker commands needed.

Domain ownership check (HTTP-01). The authority must confirm the domain is really yours: it requests a one-time code at http://{domain}/.well-known/acme-challenge/{code}. While the check is active, the application answers this request itself — you do not place anything anywhere.

Saving the files. The finished certificates are stored in the domain’s subfolder inside the SSL folder: fullchain.pem (the full certificate chain) and privkey.pem (the private key). The ACME account key (account-key.pem) is saved once and reused for later requests.

Progress in real time. Every step of the process shows up in the interface instantly (updates arrive over SignalR) — you see the current state, from account registration to saving the certificate.

Getting a certificate

  1. Open Settings → SSL Certificates in your Xedant Agent instance.
  2. Enter the domain (for example, agent.example.com) and the email for registering the ACME account. The browser remembers the email and fills it in automatically next time.
  3. Check “Use staging server (testing)” only for experiments — browsers do not trust staging certificates, so for real work the box must stay unchecked. (“Staging certificates are not trusted by browsers. Uncheck for production.”)
  4. Press “Get Certificate” — the application registers the ACME account, creates the order, passes the domain ownership check, and saves the certificate files.
  5. The progress shows step by step: Registering ACME account → Creating certificate order → Setting up challenge → Validating domain ownership → Generating certificate → Saving certificate files.

Repeated requests for the same domain are fine — the files are overwritten, and the existing ACME account is reused.

Checking the current certificate

The check button next to the domain field shows which certificate is currently installed for the domain: who it was issued to and by whom, the validity period, and the days remaining (highlighted in yellow when fewer than 30 days remain). If there is no certificate — a warning appears.

Certificate list and deletion

All issued certificates are listed in the SSL Certificates dialog: the domain, the issue date, the validity period, and the saved file names. A certificate you no longer need can be deleted with one button.

What you need for issuance

  • The domain (or subdomain) must point to the IP address of the server running Xedant Agent;
  • Port 80 (HTTP) must be reachable from outside — Let’s Encrypt runs the check through it;
  • Let’s Encrypt rate limits apply to real issuances — use the staging server for experiments.

Self-signed certificate (no domain)

If you have no domain — say, the agent runs on a server by IP address or inside a local network — Let’s Encrypt does not apply: without a domain, ownership cannot be proven. For these cases there is a built-in self-signed certificate mode: HTTPS turns on with a single switch, no registration and no external services.

The browser cannot verify that such a certificate came from a trusted authority, so on your first visit it shows a security warning — you need to skip it once (the “Proceed to site” button). After that the connection is fully encrypted: passwords, tokens, and chat content are protected from interception in transit.

How to enable it. Just set the AGENT_SSL=auto environment variable at startup. Environment variables are launch parameters: you set them once, and the application applies them automatically. At startup the application generates the certificate itself (valid for 5 years — no renewal needed) and starts listening on the HTTPS port:

  • AGENT_SSL_PORT — the HTTPS port (by default, the HTTP port number + 1; for example, HTTP on 8080 → HTTPS on 8081);
  • the certificate is stored in the .xedant/ssl/auto/ folder (fullchain.pem + privkey.pem) and reused on later launches while it stays valid;
  • the server’s hostnames and IP addresses are included in the certificate automatically — it works for access by IP and by local-network name alike;
  • HTTP keeps working as before — both protocols are available at the same time.

The AGENT_SSL_DOMAINS variable lets you list explicitly, comma-separated, the domains/IPs to add to the certificate (used in MultiAgent Docker containers, where the hostname and addresses inside the container differ from the address the browser reaches the agent at).

Which option to pick: if you have a domain and port 80 open — use Let’s Encrypt (a trusted certificate, no browser warnings); if there is no domain or access is by IP only — turn on the self-signed certificate.

Connecting to nginx

After issuance, wire the certificate into your web server’s configuration. Example for nginx (paths relative to the project root where the .xedant folder lives):

server {
    listen 443 ssl;
    server_name agent.example.com;

    ssl_certificate     /srv/xedant/.xedant/ssl/agent.example.com/fullchain.pem;
    ssl_certificate_key /srv/xedant/.xedant/ssl/agent.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }
}

There is no automatic renewal in the application yet — re-request the certificate through the SSL Certificates dialog before it expires. Let’s Encrypt issues certificates for 90 days.