Installing the agent

Every way to install the aethercert agent - one-command install on Linux and Windows, unattended fleet rollout, containers, updating, repairing, uninstalling.

Everything installs through one binary, aethercert-installer, built per operating system. The dashboard's install 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 actually does, and every case the wizard's happy path does not. For what the agent does once it is running, see Agents.

Where the binaries come from

Every build is published on the download CDN at cdn.aethercert.com, and the download needs no sign-in. That is deliberate: the target server usually has no browser and no dashboard session, and the binary is the same client software every customer runs. The secret in an install is the enrolment token, which you pass on the command line and which never touches the download.

What replaces the login is the checksum. Every file has a .sha256 published beside it, and every release has a SHA256SUMS:

https://cdn.aethercert.com/manifest.json                     every component and version
https://cdn.aethercert.com/installer/latest/…                the current build
https://cdn.aethercert.com/installer/latest/….sha256         its SHA-256
https://cdn.aethercert.com/installer/0.9.4/…                 pin a version - never changes

latest moves with each release; a versioned path is immutable, so it is the one to pin in a golden image or a configuration-management manifest.

Linux, as a systemd service

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

`sha256sum -c` prints `OK` and exits zero on a match. Because the steps are chained
with `&&`, a mismatch stops here and the file is never made executable.

This enrolls the host, downloads the agent build, installs it to
`/opt/aethercert-agent/aethercert-agent`, writes configuration to
`/etc/aethercert-agent/agent/config.json`, and creates and enables a systemd unit.
It also installs the aethercert Update Service alongside it if this host does not
already have one.

Windows, as a service

Two ways to run the same download.

Double-click it - 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. That is the path for a server someone is sitting in front of.

Or use the command line, which drives exactly the same code and is what you want for anything scripted. From an elevated PowerShell:

Enrolls, downloads the agent build, installs it to
`C:\Program Files\aethercert\agent\aethercert-agent.exe`, writes configuration to
`%ProgramData%\aethercert\agent\config.json`, and creates and starts a Windows
service (`AetherCertAgent`) with restart-on-failure through the Service Control
Manager. The shared tray icon and the aethercert Update Service are installed
alongside it.

Unattended and fleet rollout

Nothing extra is needed for this - it is the same command, with a multi-provision token, run by whatever already provisions your servers.

For a one-liner, the CDN also serves a bootstrap script that does the download, the checksum comparison and the install in one step, and refuses to run a binary whose digest does not match:

curl -fsSL https://cdn.aethercert.com/install.sh | sudo sh -s -- --token <token>

& ([scriptblock]::Create((irm https://cdn.aethercert.com/install.ps1))) -Token '<token>'

Both accept --api / -Api to point at a different control plane and --version / -Version to pin a published build instead of tracking the current one.

Approach	How
Golden image	Bake the installer and the command into the image build. Each host that boots enrolls as its own agent. Pin a versioned CDN path so the image is reproducible.
cloud-init / user data	Add the one-liner above as a `runcmd` step.
Configuration management	Ansible, Puppet, Chef, DSC - run the installer as an ordinary command resource, guarded by whether the service already exists.
Group Policy / Intune	Deploy the installer and run it as a startup script with the token as an argument.

Pick the agent group in the wizard before generating the token and every host arrives already in that group - so any certificate policy on it applies before the agent's first ordinary check-in.

Manual and foreground, for containers

When you do not want aethercert to register an operating-system service - inside a container, or under your own process supervisor - download the agent binary directly, not the installer, and split enrollment from running:

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

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

Updating

The aethercert Update Service is a separate binary installed alongside the agent. Once a day - or on demand from the Windows tray icon - it checks whether a newer build exists for whichever components are on that host, downloads it with checksum verification, stops the service, swaps the binary in, and starts it again.

Neither the agent nor the CA connector check for or apply updates themselves.

Turning auto-update off for an agent (Manage > Agents > Edit > Settings) pins its version. The settings page then shows the exact manual command:

aethercert-update-service update --agent
aethercert-update-service update --connector

Self-hosting: ship an update by rebuilding the binaries, copying them into the control plane's agent-downloads/ folder, and bumping the relevant VERSION file. Enrolled hosts pick it up at the Update Service's next daily check.

Repairing an installation

Windows only, and no token is needed - it works from the credentials already on the host.

Repair re-registers the services including restart-on-failure, refreshes the Apps & Features entries, reinstalls the tray icon and its autostart task, makes sure the Update Service is present, and re-adds the CA connector's firewall rule.

.\aethercert-installer-windows-amd64.exe repair
.\aethercert-installer-windows-amd64.exe repair --redownload

--redownload also replaces the installed executables with the current build from the control plane. That is the fix for a binary an endpoint-protection product removed or quarantined.

.\aethercert-installer-windows-amd64.exe status

prints what the host currently has installed.

Uninstalling

# One component - Linux as root, Windows as Administrator
aethercert-agent uninstall

# Everything, Windows (Administrator)
.\aethercert-installer-windows-amd64.exe uninstall --all

Both stop and remove the service and leave the binary and configuration in place, so a later install reuses this host's existing enrollment instead of needing a fresh token.

Add --purge - or tick the matching box in the setup window - to delete the binaries, configuration and logs as well.

Certificates already deployed into the Windows certificate store are never touched by an uninstall. Removing the agent stops management; it does not remove certificates the host is serving.

Distributing the binaries when self-hosting

If you self-host aethercert, you publish the binaries yourself. Build them from the aethercert-agent repository (./build.sh) and copy the resulting dist/ into the control plane's agent-downloads/ folder; the project README has the exact commands and the version files the update path reads.

The simplest setup needs nothing else: the control plane serves those files directly from /api/agent/download?os=linux&kind=installer, unauthenticated, with the digest in an X-Sha256 response header and &checksum=1 returning it as a sha256sum -c file.

For a dedicated download host of your own - your own cdn. hostname, immutable per-version paths, a one-line install script - run node --experimental-strip-types scripts/release/build-cdn-tree.ts --dist dist --out ./upload against the same dist/ and upload the result to any S3-compatible object store (R2, S3, Backblaze B2, ...). See docs/agent-update-distribution.md in the repository for the full setup.