Set Up the Agent

Install the QuietLS agent on your server — VPS or Docker — and verify it's running.

Setup with an AI Agent (Fastest)

The quickest way to get the agent running is to let an AI assistant handle it for you.

Copy the prompt below and paste it into Claude, ChatGPT, or any AI agent of your choice. The AI will read the raw setup instructions and install the agent automatically:

The AI will open the documentation link, get the markdown text directly, and execute the correct installation steps for your server.

What the Agent Does

The QuietLS agent is a lightweight daemon that runs on your server. It connects to the QuietLS backend, reports your server's OS and web server configuration, and receives commands to manage SSL certificates, reload web servers, and run security checks. Once installed and registered, you can assign domains to it from the dashboard.

The agent is open source under Apache-2.0: github.com/quietls/agent. You can read every line — it's read-only by design, executes only a fixed allowlist of commands, and never touches your private keys.

Prerequisites

• A server running Ubuntu 20.04+, Debian 11+, CentOS 7/8, RHEL, AlmaLinux, or Rocky Linux (or compatible distributions).
• Root or sudo access.
• Outbound HTTPS (port 443) to quietls.com.
• For Docker installs: Docker and Docker Compose installed.

Option 1: Install on a VPS (Ubuntu / Debian)

Run the following command on your server, replacing <TOKEN> with the setup token from your QuietLS dashboard:

SSL_AGENT_TOKEN=<TOKEN> \
curl -sSL https://quietls.com/v1/agents/install \
| sh

Prefer not to pipe to sh? The script is scripts/install.sh in the open-source repo — read it first, then run it however you like.

The installer will:

1. Detect your OS and architecture.
2. Download the ssl-agent binary and verify its checksum.
3. Create a system user and config directory.
4. Register the agent with QuietLS using your token.
5. Install and start the systemd service.

Option 2: Install with Docker Compose

Choose the variant that matches your reverse proxy.

Nginx (certbot)

Use this if you run Nginx with Let's Encrypt certificates stored in the default certbot directory:

version: '3.8'
services:
  quietls-agent:
    image: quietls/agent:latest
    restart: unless-stopped
    environment:
      - SSL_AGENT_TOKEN=<TOKEN>
      # Path inside this container to the mounted nginx config. Required so
      # the agent can read vhosts and cert paths without a local nginx binary.
      - SSL_AGENT_CONFIG_PATH=/mnt/nginx/nginx.conf
      # Command the agent runs to reload nginx after installing a certificate.
      # nginx runs in a separate container, so reload it via the mounted docker
      # socket. Replace `nginx` with your nginx container's name.
      - SSL_AGENT_RELOAD_COMMAND=docker exec nginx nginx -s reload
    volumes:
      - /etc/letsencrypt:/etc/letsencrypt
      - /var/run/docker.sock:/var/run/docker.sock
      # Mount the same nginx config your nginx container uses, read-only:
      - ./nginx/nginx.conf:/mnt/nginx/nginx.conf:ro
      # Persist the agent's own config (agent_id, tokens) across restarts:
      - quietls_config:/etc/ssl-agent
volumes:
  quietls_config:

The agent container has no nginx binary installed, so it can't run nginx -v or nginx -T to discover vhosts. SSL_AGENT_CONFIG_PATH tells the agent to parse the mounted config file directly — this is what makes metric.tls-drift, metric.cert-local, and certificate installation work in a sidecar setup. Point the volume at the same nginx.conf your nginx container reads from.

How certificate installation works here. When QuietLS issues a certificate for a domain assigned to this agent, the agent parses the mounted nginx.conf, finds the ssl_certificate / ssl_certificate_key paths for the matching vhost, and writes the new certificate to exactly those paths (that's why /etc/letsencrypt is mounted read-write — it's the directory your nginx config points at). It then runs SSL_AGENT_RELOAD_COMMAND to reload nginx. Because the agent can't reload a separate container itself, the reload command uses the mounted docker.sock to reach the nginx container. If you omit SSL_AGENT_RELOAD_COMMAND, the certificate is still written but nginx keeps serving the old one until it's reloaded.

Coexisting with certbot. If your nginx.conf points at a certbot path (/etc/letsencrypt/live/<domain>/...), the agent overwrites those files when it installs a QuietLS certificate — nginx serves it fine, but certbot and QuietLS are now both managing the same domain. Pick one: either stop certbot's auto-renewal for that domain (e.g. remove it from the certbot service / certbot delete --cert-name <domain>), or point ssl_certificate / ssl_certificate_key at a dedicated path QuietLS owns (such as a shared ./nginx/ssl volume) so the two never clobber each other.

docker.sock is mounted so the agent can detect running containers and reload the nginx container after installing a certificate (via SSL_AGENT_RELOAD_COMMAND). The nginx config file must be mounted and SSL_AGENT_CONFIG_PATH set, because nginx vhost config lives on the host filesystem and isn't reachable via docker.sock.

Traefik or Caddy? They manage their own certificates, and agent support for them isn't built yet — the agent currently supports Nginx and Apache. QuietLS's external monitoring covers Traefik/Caddy setups without an agent: CT logs, expiry, renewal-failure detection, and header drift all work from the outside.

Post-Install Verification

After installing, check that the agent is running:

VPS (systemd):

systemctl status ssl-agent

Docker:

docker compose logs quietls-agent

You should see a log line confirming the agent connected to QuietLS. In the dashboard, the agent status will change from "Waiting for connection" to "Online" and you can proceed to assign domains.

Assign Domains

Once the agent is connected:

1. In the QuietLS dashboard, go to Agents.
2. Find your new agent and click Assign Domains.
3. Select the domains this agent should manage and confirm.

You can also assign domains later from the agents table at any time.