Agents
How the aethercert agent works - enrollment tokens, the outbound check-in cycle, host requirements, automatic updates, and revoking or removing an agent.
The agent is a small binary that runs on the server that needs a certificate. It is the only aethercert component that ever touches a private key.
This page covers what the agent is and how it behaves. For the commands that put it on a machine, see Installing the agent.
The check-in cycle
The agent makes one kind of network call: an outbound HTTPS request to the control plane asking whether there is work for it. It never listens, so it needs no inbound firewall rule and works unchanged behind NAT, behind a proxy, or on a host with no public address at all.
| Idle cadence | 3 hours by default on every plan, to keep fleet-wide API traffic low. Configurable per agent; as low as 1 hour on Standard, 30 minutes on Pro/MSP. |
| When work is queued | The control plane shortens the interval to roughly 10 seconds, so issuance does not wait out the idle cadence. |
| What travels outbound | Job results: serial, fingerprint, validity, success or the error text. Plus a heartbeat and, at most every six hours, the external certificate inventory. |
| What never travels | Private keys. |
Enrollment
An agent exists once it has connected, not when you create a token for it. The install wizard under Manage > Agents generates the token; the agent appears under Manage > Agents the first time it checks in.
| Token type | Behaviour |
|---|---|
| Single-provision | One use. The next host to run the same command is rejected. |
| Multi-provision | Redeemable by any number of hosts with the identical copy-pasted command. Each host becomes its own agent as it runs the install. |
Multi-provision is the one to use for a scripted rollout - the same command in a golden image, a configuration-management module or a cloud-init file provisions every host that boots from it.
What the agent needs on the host
| Platform | Requirements |
|---|---|
| Linux | Root for the install. systemd. Outbound HTTPS. Write access to wherever the deploy target puts files. |
| Windows | Local administrator, so it can write to the LocalMachine certificate store and, if configured, update IIS bindings. |
| Exchange / ADFS targets | The agent must run on that server, with the relevant management tooling already present. aethercert does not install Exchange or ADFS tooling. |
| Docker target | Access to the Docker socket, equivalent to docker group membership on Linux. |
Settings on an agent
Editing an agent under Manage > Agents exposes:
| Setting | What it does |
|---|---|
| Name | Display name. Purely cosmetic - jobs are routed by identity, not by name. |
| Check-in interval | The idle cadence for this agent. Bounded by your plan; leave it empty for the plan default. |
| Group | Which agent group it belongs to, if any. Changing this applies or unapplies every certificate policy on those groups. |
| Auto-update | Whether the update service may replace this agent's binary. Off pins the current version. |
| Local log retention | How many days of on-host log files the agent keeps. Bounded by your plan. |
Updates
The agent does not update itself. A separate aethercert Update Service, installed alongside it automatically, checks once a day - or on demand from the tray icon on Windows - whether a newer build exists, downloads it with checksum verification, stops the service, swaps the binary in, and starts it again.
Turning auto-update off for an agent pins its version. The agent's settings page then shows the exact command to update it by hand instead. See Installing the agent.
Grouping agents
Servers doing the same job - replicas behind a load balancer, a cluster of the same application - can be put in an agent group. Attach a certificate policy to that group and every agent that joins gets its certificate automatically, including hosts rolled out months later.
You can pick the group in the installer step, so a freshly provisioned host arrives with its certificate already being issued.
Revoking and removing
Three different things, in increasing order of finality:
| Action | Effect |
|---|---|
| Revoke | The agent can no longer authenticate or collect jobs, immediately. It stays in the list. Irreversible from the agent's side - the host must be re-enrolled with a fresh token. |
| Delete | Removes the agent record. Blocked while certificates still target it; reassign or delete those first. |
| Uninstall | Run on the host. Stops and removes the service. See Installing the agent. |
Revoking and uninstalling are complementary, not alternatives. Uninstalling removes the software; revoking removes the credential. For a server that is gone for good, do both - and revoke first, since a decommissioned host may not be available to uninstall from.
Certificates already deployed to a host are never retracted by any of these. They keep working until they expire.