Skip to main content

Maintain the Windows agent configuration

Use this page when the installed agent cannot load a change or a private-CA ACME client fails. Public-CA setups do not need private-CA client adjustments; configuration maintenance still applies.

Edit enrolled configuration safely​

Use an elevated administrator session and edit C:\ProgramData\TokenTimerAgent\state\config.json in place. Preserve agentId, API/workspace settings, signing trust and existing policy. Do not replace the whole file with a fresh-host template.

Get-Service TokenTimerAgent
# After saving the intended configuration change:
Restart-Service TokenTimerAgent
Get-Service TokenTimerAgent

Confirm Running and a fresh heartbeat. Restart only the agent, not IIS. If startup fails, inspect the service log before submitting work.

If even an elevated editor reports Access denied, inspect the file's owner and DACL. Agent-created state can be SYSTEM-only, and replacing a config file can change its permissions. This is not a reason to disable ACL validation or grant broad access to the state directory. Have an authorized administrator preserve the original owner/DACL and configuration, obtain maintenance access to this config file only, then restore any temporary access after the edit/restart. Do not widen access to the enrolled credential, keys or journal. Never delete identity or custody state to clear the error. The installer's ACL model describes accepted principals; a persistent inability to maintain the config needs an agent fix rather than a repeated permissions workaround.

Private ACME authorities: separate the trust paths​

Check each connection separately:

  • The agent's caBundlePath trusts the TokenTimer API.
  • The external ACME client's TLS configuration trusts the ACME directory's HTTPS endpoint.
  • The Windows chain must trust the CA that signs the issued certificate, which may differ from the directory's transport CA.
  • Independent probes must validate the served hostname and the issued chain.

With acme.sh on Windows, inspect the exact allowlisted Bash executable and the curl it launches in the service's environment. Git's bin/bash.exe launcher can change PATH; an interactive shell's curl version is not proof of the service's selection. In a private-CA setup, verify the intended Bash/curl TLS backend and accessible service HOME/CA configuration. The actual usr/bin/bash.exe can avoid that launcher behavior when it is the path you have installed and qualified. Update the command allowlist consistently if changing it.

Do not install a different curl build or change global PATH/HOME merely because a tutorial used a test CA. Do not disable certificate verification or Schannel protections. Diagnose the actual chain/backend error and scope any required configuration to the agent service. Use public-CA defaults where they already work.