Installing the agent
Every way to install the aethercert agent - the one-command install on Linux and Windows, the graphical setup wizard, and what the installer does to the host.
Everything installs through one binary, aethercert-installer, built per operating
system. The dashboard's enrollment wizard picks the component, the OS and the token type
for you, and hands back a ready-made download link and command.
This page covers what that command does. For an unattended fleet rollout see Unattended rollout; for a container, see Containers.
You need a token first
Every install consumes an enrollment token generated under Manage > Agents. A single-provision token is single-use; a multi-provision token can be redeemed by up to 500 hosts with the identical command. Either way it is shown once, and it expires an hour after it is created.
Build the agent in the dashboard
Start at Manage > Agents > New agent. The wizard has three sections:
- Platform - the operating system, whether you want the graphical setup or the command line, a single- or multi-provision token, and optionally the agent group the host should join. Picking a group here means any certificate policy on it applies before the agent's first ordinary check-in.
- Installation - the token is minted when you reach this section. The wizard shows the download and the command, with the token already in it.
- Verify - the wizard polls for the agent's first check-in.
The same wizard mints a CA connector pairing token when you start from Manage > Certificate Authorities. The install command is identical either way: the token itself decides which component is installed, and the installer resolves that with the control plane before consuming it.
The one-command install
This is what the wizard hands you, and what to use unless you need something it does not cover.
curl -fsSL https://cdn.aethercert.com/install.sh \
| sudo sh -s -- --token <token> --api https://api.aethercert.com| Option | Meaning |
|---|---|
--token <token> | The enrollment token. Required. Also read from AETHERCERT_TOKEN. |
--api <url> | Control plane base URL. Defaults to the published one; also read from AETHERCERT_API. |
--version <ver> | Pin a published installer version instead of tracking the current one. |
-- | Everything after a bare -- is passed straight to aethercert-installer. |
Linux amd64 only, and it has to run as root. The script refuses anything else rather
than half-installing.
What the script does before it runs anything
It downloads aethercert-installer, fetches the SHA-256 published beside it, compares
them, and only then executes. There is no flag to skip that: a script piped into a root
shell that runs whatever it just downloaded is exactly the shape of install the checksum
exists to rule out. On a mismatch it exits non-zero having executed nothing.
When the build was published with a signing key configured, the download is additionally
checked against a detached Ed25519 signature published beside it. That is a stronger
guarantee than the checksum alone, because a compromised CDN cannot forge it. The
signature check needs openssl on the host; its absence, or the absence of a signature to
check, is tolerated - the checksum already ran. A signature that is found and does not
verify is always fatal.
Step by step, without the bootstrap script
If you would rather see each step, or your environment does not allow piping a script into
a shell, download the installer yourself. This is also the form the wizard shows when
there is no CDN to serve install.sh from.
curl -fsSL -o aethercert-installer-linux-amd64 \
"https://cdn.aethercert.com/installer/latest/aethercert-installer-linux-amd64" \
&& curl -fsSL -o aethercert-installer-linux-amd64.sha256 \
"https://cdn.aethercert.com/installer/latest/aethercert-installer-linux-amd64.sha256" \
&& sha256sum -c aethercert-installer-linux-amd64.sha256 \
&& chmod +x aethercert-installer-linux-amd64 \
&& sudo ./aethercert-installer-linux-amd64 install \
--api https://api.aethercert.com --token <token>The steps are chained with && on purpose. Written as independent statements, a shell
would run the install anyway after the comparison failed, which would make the check
decorative.
latest moves with each release. A versioned path - .../installer/2026.8.3.0.0/... -
is immutable, so pin one in a golden image or a configuration-management manifest.
The graphical setup, on Windows
Double-click the installer, or start it with no arguments, and a setup window opens:
choose install, repair or uninstall, choose the fleet agent or the CA connector, paste the
control plane URL and the token, adjust the options, and watch the install log. It follows
the Windows display language, in German or English. aethercert-installer gui opens it
explicitly from a shell.
That is the path for a server somebody is sitting in front of. Everything it does is also a command-line flag - see the CLI reference.
A GUI-subsystem process does not block a script
The Windows installer is linked as a GUI-subsystem executable so double-clicking it does
not flash a console window. PowerShell and cmd.exe therefore do not wait for it. Use
Start-Process -Wait -NoNewWindow, or pipe its output, when a script has to block until
the install finishes. Output still appears in the calling console: with arguments
present, the process attaches to its parent's console first.
What the install does to the host
- Resolves which product the token belongs to, without consuming the token.
- Enrolls with it, obtaining this host's own credentials.
- Downloads that product's current build using those credentials.
- Places the binary at the standard location and writes
config.jsonbeside it. - Registers and starts an operating-system service.
- Best-effort, installs the shared tray icon (Windows) and the aethercert Update Service alongside it.
The last step is best-effort by design: the component you asked for is already installed and running by the time it is reached, and neither companion being absent stops it doing its job today. A host without the Update Service simply never updates itself.
Both the config path and the binary path are printed on stdout when the install finishes, and the whole run is written to an install log - see File locations.
Service accounts on Windows
By default the service runs as LocalSystem. Pass --service-account (and
--service-password, unless it is a group managed service account whose name ends in $)
to run it as a named account instead.
When you do, the installer grants that account the Log on as a service right, verifies the credentials actually work as a service logon before creating the service, and waits for the service to report running afterwards. A wrong password, a disabled account or a Deny log on as a service policy is reported as exactly that rather than as a generic start failure. The password never reaches a log line or an error message.
A dedicated service account is strongly recommended for the CA connector, because it is what the CA rights get granted to.
Confirming it worked
Click Verify connection in the wizard. The agent polls outbound, so this works from behind NAT and a closed inbound firewall.
On the host, aethercert-installer status prints what is installed - component, version,
service state, binary and config paths, and the control plane it points at - and exits 0
either way, which makes it safe to run from a configuration-management dry run.
HTTP-01 without a webroot needs port 80
If a certificate uses HTTP-01 and no webroot is configured, the agent binds port 80 during issuance. The Linux systemd unit carries the ambient capability to bind low ports, so the service does not have to run as root for that step. Prefer DNS-01, or HTTP-01 with a webroot, where a web server already owns port 80.
Requirements
| Platform | Needs |
|---|---|
| Linux | amd64, systemd, root for the install, outbound HTTPS to api.aethercert.com and cdn.aethercert.com. |
| Windows | amd64, local administrator, the same outbound HTTPS. Windows Server for the CA connector. |
Exact hostnames and ports are in Network requirements.