Agents

How the aethercert agent behaves - enrollment tokens, the outbound check-in cycle, every per-agent setting, re-registering, revoking and deleting.

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 to the dashboard: how it enrolls, what you can configure per agent, and how to retire one. 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 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.


Idle cadence	3 hours by default on every plan. Configurable per agent down to 1 hour on Standard and the MSP tiers, 30 minutes on Pro. Fixed at 3 hours on Free.
When work is queued	The heartbeat response shortens the next check-in to 10 seconds, so issuance does not wait out the idle cadence.
What travels outbound	Heartbeat (hostname, OS version, agent version, architecture, internal IP), job results (serial, fingerprint, validity, success or the error text), and at most every six hours the external certificate inventory.
What never travels	Private keys.

An agent is online until it misses its own deadline. The control plane stamps an expected-poll time on every check-in, derived from that agent's own interval and doubled to absorb clock skew and one dropped heartbeat. Past that stamp it reads as offline - so a Free agent on a 3-hour cadence is not called offline until 6 hours have passed, while a Pro agent on 30 minutes is called offline after one hour.

Enrollment

An agent exists once it has connected, not when you create a token for it. The wizard under Manage > Agents generates the token; the agent appears in the list the first time it checks in.

Token type	Behaviour
Single-provision	One use. Carries the name you typed. The next host to run the same command is rejected.
Multi-provision	Redeemable by up to 500 hosts with the identical command. Each host becomes its own agent, named from its own reported hostname.
Re-register	Scoped to one existing agent. Redeeming it replaces that agent's credentials in place instead of creating a new agent.

A token can also carry an agent group, so every host that redeems it joins that group as it enrolls, and any certificate policy on the group applies before the agent's first ordinary check-in.

Tokens expire after one hour

Every enrollment token, single- or multi-provision, is valid for one hour from creation. For a golden image or a configuration-management rollout, mint the token as part of the run rather than baking a long-lived one into an artifact.

A token is a credential

Anyone holding a valid enrollment token can register an agent in your organization. Tokens are shown once, at generation.

Re-registering

Re-register on an agent's page mints a fresh token scoped to that agent and shows the same install command. Running it updates that agent's credentials in place; certificates, history and group membership are unchanged.

Use it when a host's config.json was lost or its credentials stopped being accepted. It is the only way to give an existing agent a new secret - there is no rotate operation, and re-enrolling with an ordinary token would create a second agent.

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, AD FS, SQL Server, Skype for Business, Hyper-V Replica, Horizon, StoreFront targets	The agent must run on that server, with the relevant management tooling already present. aethercert installs none of it.
Docker target	Access to the Docker socket or named pipe, equivalent to `docker` group membership on Linux.

Per-agent settings

Manage > Agents > Manage opens an agent with four tabs: Overview, Certificates, Settings and Danger zone. These are the settings.

Setting	What it does
Name	Display name. Jobs are routed by identity, not by name.
Group	Which agent group it belongs to, if any - at most one. Saving a new group applies every policy on that group; removing it from a group unapplies them and cancels their queued jobs.
Check-in interval	The idle cadence for this agent, in seconds. Bounded by your plan; leave empty for the plan default.
Preferred challenge type	DNS-01, HTTP-01 or TLS-ALPN-01, used as the default when a new certificate is created for this agent against an external ACME CA. Internal REST authorities ignore it - they sign directly, with no challenge.
Standalone challenge ports	Where the agent binds locally for HTTP-01 and TLS-ALPN-01. Leave blank for the standard 80 and 443. Set them only when this host's firewall or NAT forwards the real public port to a different local one.
Automatic updates	On by default. Off pins this agent's version and reveals the exact manual update command.
Update channel	Which release ring this agent follows - `internal`, `test`, `canary` or `stable`. Defaults to inheriting the organization's. Override it only to canary a build on one host. See Updates.
Network stack	Dual-stack (default), IPv4 only or IPv6 only. Restricts the agent's own outbound connections and the bind address of its standalone HTTP-01 listener.
Local log retention	How many days of archived on-host logs the agent keeps. Fixed at 7 days on Free; up to 30 on Standard and the MSP tiers, 90 on Pro.

What the network stack setting does not cover

It does not decide which stack a CA validates over - the CA resolves your public DNS itself. It also does not apply to Route 53 DNS-01, which uses the AWS SDK's own client, or to the PowerShell-based Windows deploy targets (Exchange, AD FS, IIS), which bypass the agent's networking entirely. On a dual-stack host, pick a single-stack mode only when the other stack genuinely cannot reach the internet; otherwise issuance requests can time out on the unreachable one.

Updates

The agent does not update itself. A separate aethercert Update Service, installed alongside it, checks twice a day whether a newer build exists for the components on that host, verifies it and swaps the binary in. Turning automatic updates off for an agent pins its version, and the settings page then shows the exact command to update it by hand. See Updates and release channels.

Revoking, deleting and uninstalling

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 Repair and uninstall.

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.