Installing the agent

The agent is a single, dependency-free binary. There's one binary per OS for the fleet agent, plus a separate Windows-only binary for the CA connector. This page covers every install case; for what the agent does once it's running, see Agents.

You need an enrollment token first

Every install consumes a one-time enrollment token. Create one in Build > Agents (button: Create enrollment token) — it's shown once, so copy it. A token is single-use and expires; see Dashboard reference › Agents.

Case 1 — Linux, as a systemd service

The standard production install. Run it as root on the target server.

Download the binary

Grab the Linux build from the download link shown next to your enrollment token, then make it executable:

chmod +x aethercert-agent-linux-amd64

Run the one-command install

sudo ./aethercert-agent-linux-amd64 install \
  --api https://your-app.example.com \
  --token <token>

This copies the binary to /usr/local/bin/aethercert-agent, writes config to /etc/aethercert-agent/config.json, and creates and enables a systemd unit at /etc/systemd/system/aethercert-agent.service.

Confirm it's up

Back in Build > Agents, click Verify connection. The agent polls out, so no inbound firewall rule is required.

HTTP-01 standalone needs port 80

If a certificate uses HTTP-01 in standalone mode, the agent binds port 80 during issuance. On Linux, systemd is configured with the ambient capability to bind low ports without running the whole service as root for that step. Prefer DNS-01 or HTTP-01 webroot where you already have a web server on 80.

Case 2 — Windows, as a service

Run from an elevated PowerShell (Administrator) on the target server.

Run the one-command install

.\aethercert-agent-windows-amd64.exe install `
  --api https://your-app.example.com `
  --token <token>

Installs the binary to C:\Program Files\AetherCertAgent\aethercert-agent.exe, writes config to %ProgramData%\AetherCertAgent\config.json, and creates and starts a Windows Service (AetherCertAgent) with restart-on-failure via the Service Control Manager.

Confirm it's up

Click Verify connection in the dashboard.

Service account & permissions

The service account needs local admin rights to write to the LocalMachine certificate store and, if configured, to update IIS bindings. For Exchange and ADFS deploy targets the agent must run on that server with the relevant management tooling already present.

aethercert.com/dashboard/manage/agents

web-01

Linux · amd64

Online

web-02

Linux · amd64

Online

exch-01

Windows Server

Online

adcs-01

Windows Server

Pending

Manage › Agents — connection health and the certificates each one serves.

Case 3 — Manual / foreground (containers, custom supervisors)

When you don't want aethercert to register an OS service — inside a container, or under your own process supervisor — split enrollment and running:

# Enroll only: writes config, registers no service
aethercert-agent enroll --api https://your-app.example.com --token <token>

# Run in the foreground; responds cleanly to Ctrl+C / SIGTERM
aethercert-agent run

Foreground mode doesn't self-update

Running via aethercert-agent run without systemd/SCM supervision will not self-update — there's nothing to restart the process after a swap, so an available update is logged and skipped. Update the image/binary yourself, or install as a service.

Updating & self-update

When installed as a service, the agent updates itself: a heartbeat response can say a newer build is available, the agent downloads it (checksum-verified), swaps it in, and exits so the service manager restarts it on the new version. You ship an update by rebuilding the binaries, copying them into the control-plane's agent-downloads/ folder, and bumping its VERSION file. Enrolled agents pick it up on their next check-in.

Uninstalling

# Linux (root) / Windows (Administrator)
aethercert-agent uninstall

Stops and removes the service and leaves the binary and config in place. Revoke the agent from Manage > Agents as well if the server is gone for good — a revoked agent can no longer authenticate.

Case 4 — Windows CA connector (Active Directory Certificate Services)

A separate Windows-only binary, installed on the AD CS server itself. It answers CSR sign/revoke requests from fleet agents over your internal network, and only reports liveness and discovered templates back to aethercert. Set it up from Manage > Certificate Authorities > Connector (offered only for an Internal CA (REST)).

Create a pairing token

In the dashboard, generate a one-time connector pairing token for the internal_rest CA.

Install on the CA server

.\aethercert-ca-connector-windows-amd64.exe install `
  --api https://your-app.example.com --token <token> `
  --public-url https://adcs01.corp.internal:8443 `
  --ca-config "adcs01\CorpIssuingCA" --template WebServer `
  --service-account "CORP\svc_adcs_connector" --service-password "..."

Grant the service account rights on the CA

The account you pass needs Enroll on the template and Issue and Manage Certificates on the CA. Without a--service-account, the service runs as the machine account, which usually lacks both and every sign fails with Access Denied.

TLS for the connector's own listener

Provide --tls-cert/--tls-key from your internal PKI for the connector's HTTPS listener. Without them it generates a self-signed certificate and pairing sets insecure_skip_verify automatically — fleet agents still authenticate every request with the shared API key, so this only affects transport-level pinning. install also opens the firewall for --listen's port (default 8443); pass --no-firewall-rule to manage that yourself.

Distributing the binaries (self-hosting)

If you self-host aethercert, the agent binaries are served from the control plane's agent-downloads/ folder (outside public/, only reachable with a valid session or agent token). Build them from the aethercert-agent repository and copy them in — see the project README for the exact go build commands and the VERSION file the self-update path reads.