Agent configuration
The agent's config.json: what is in it, the two settings that are only configurable there, and what belongs in the dashboard instead.
Almost everything about an agent's behaviour is configured in the dashboard, not on the host: check-in cadence, preferred challenge type, standalone challenge ports, network stack, update channel and log retention all arrive in the heartbeat response. See Agents.
What lives on the host is config.json.
Where it is
| Platform | Path |
|---|---|
| Linux | /etc/aethercert-agent/agent/config.json |
| Windows | C:\ProgramData\aethercert\agent\config.json |
| CA connector | C:\ProgramData\aethercert\ca-connector\config.json |
--config <absolute path> on install or enroll puts it somewhere else. The path has
to be absolute; a relative one is rejected.
The file is written 0600 inside a 0700 directory, because it holds this host's bearer
secret. Do not commit it, copy it between hosts, or bake it into an image.
What is in it
{
"api_base": "https://api.aethercert.com",
"agent_id": "<agent-id>",
"secret": "<the host's bearer secret>",
"check_in_interval_seconds": 300
}| Key | Meaning |
|---|---|
api_base | The control plane this host talks to. Written at enrollment. |
agent_id | This host's identity. Written at enrollment. |
secret | This host's credential. Written at enrollment. Never log it, never copy it. |
check_in_interval_seconds | A fallback only - see below. |
check_in_interval_seconds is not the real cadence
It is the value --check-in-interval wrote at install time. The cadence the agent
actually uses is whatever the control plane returns on every heartbeat, derived from the
agent's own setting and its plan. The agent also checks in immediately on its first
cycle rather than waiting this out.
Change the cadence under Manage > Agents, not here.
The two settings that only exist here
Both tune the external certificate inventory - the periodic scan that reports certificates already installed on this host. Neither has a dashboard equivalent; both are hand-edited.
{
"certificate_scan_paths": ["/opt/myapp/tls", "/srv/certs/server.pem"],
"disable_certificate_scan": false
}| Key | Effect |
|---|---|
certificate_scan_paths | Extra directories or individual files to include, on top of the platform defaults. For a host that keeps its certificates somewhere the defaults do not cover. |
disable_certificate_scan | true turns the inventory off for this host entirely. The scan reads public certificate material only and never opens a private key, but an operator who does not want their installed certificates catalogued can opt out. |
Restart the agent service after editing the file.
Blocking Target Registry scripts on this host
A Target Registry package can bring its own PowerShell script. Whether it may run is decided by your organization's registry policy - and, as a last word, by the host itself:
{
"registry_powershell_scripts": "deny"
}"deny" refuses every script a registry package defines on this host, whatever the
control plane allows; the deployment fails with a message naming this setting. Your own
custom scripts are not affected. Leave the key out (or set
"allow") to follow the organization's policy. Restart the agent service after editing
the file.
The scripts directory
A custom-script deploy target runs a script from a fixed directory beside the config. It is not configurable and never remotely settable.
| Platform | Path |
|---|---|
| Linux | /etc/aethercert-agent/agent/scripts/ |
| Windows | C:\ProgramData\aethercert\agent\scripts\ |
A script has to be a regular file in that directory, owned by root, not group- or
world-writable, and named .sh on Linux or .ps1 on Windows. The dashboard selects it by
bare filename - a path, a traversal or a symlink out of the directory is rejected.
Outbound proxy
If the host reaches the internet only through a proxy, tell the agent which. The installer
writes it for you (--proxy and --no-proxy, or the proxy field in the Windows setup);
in config.json it is two keys:
{
"proxy": "http://proxy.corp.example:3128",
"no_proxy": "corp.example, 10.0.0.0/8"
}proxy | Effect |
|---|---|
| not set | As before 2026.10.7.0.0: direct. Libraries that use Go's default HTTP client - some DNS provider SDKs - follow HTTPS_PROXY, as they always did. |
none | Always direct, whatever the environment says. |
environment | The service's HTTPS_PROXY, HTTP_PROXY and NO_PROXY variables. |
system | Windows only: the machine's WinHTTP proxy (netsh winhttp show proxy, often set by group policy) - the proxy Windows services use, not the one in a user's browser settings. |
http://…, https://…, socks5://… | That proxy. One that needs a login takes it in the URL: http://user:password@proxy:3128. |
no_proxy lists hosts that go direct: comma separated; corp.example also matches its
subdomains, and IP addresses and CIDR ranges work. Some destinations never use the proxy:
localhost, private and link-local addresses, names without a dot, the CA connector and the
certificate connector (they are on your network, and the agent checks each by its key), and
the hosts a Target Registry package talks to. Deploy scripts do not inherit the proxy.
The CA connector's and the certificate connector's config.json take the same two keys.
The Update Service has none of its own: it uses the agent's setting, or a connector's on a
host without an agent.
Restart the service after editing the file. A value the agent cannot use is logged
(ignoring the proxy setting: …) and it connects directly. The password in a proxy URL
never appears in a log, but it is in config.json - one more reason the file is readable
only by administrators and the service.
Exempt aethercert from TLS inspection
A proxy that breaks TLS open with a corporate root certificate sees this host's
credentials and can change what it is told to do - the jobs an agent runs, and the keys
the CA connector and the certificate connector check every request against. Exempt
api.aethercert.com and cdn.aethercert.com from inspection on the proxy.
The control-plane hostname
An agent enrolled before the control plane split across dedicated hostnames carries a
www.-style api_base. The agent rewrites that to the api. form once, silently, and
persists the change the first time it actually makes a call - so an already-deployed fleet
moves on its own without being re-enrolled.
Changing api_base by hand to point at a different control plane does not work: the
credentials belong to the control plane that issued them. Enroll again instead.