Agent configuration

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 isCopy Anchor Link

--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 itCopy Anchor Link

{
  "api_base": "https://api.aethercert.com",
  "agent_id": "<agent-id>",
  "secret": "<the host's bearer secret>",
  "check_in_interval_seconds": 300
}

The two settings that only exist hereCopy Anchor Link

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
}

Restart the agent service after editing the file.

Blocking Target Registry scripts on this hostCopy Anchor Link

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 directoryCopy Anchor Link

A custom-script deploy target runs a script from a fixed directory beside the config. It is not configurable and never remotely settable.

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 proxyCopy Anchor Link

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"
}

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.

The control-plane hostnameCopy Anchor Link

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.