6.9 Agent Proxy Configuration

Route CertKit Agent API traffic through an HTTP or HTTPS proxy

The CertKit Agent uses Go’s ProxyFromEnvironment support for its HTTP client. Set proxy environment variables when the agent host cannot connect directly to CertKit.

The default CertKit API endpoint is https://app.certkit.io. The proxy must allow HTTPS connections to that host.

Supported variables

Variable	Purpose
`HTTPS_PROXY`	Proxy used for HTTPS requests, including the default CertKit API connection.
`HTTP_PROXY`	Proxy used when an agent or keystore endpoint uses plain HTTP. This is normally not required.
`NO_PROXY`	Comma-separated destinations that must be reached directly.

Lowercase forms such as https_proxy and no_proxy are also supported. Use uppercase names consistently in service configuration.

The proxy value can be a complete URL or host:port. When no scheme is specified, Go assumes http. It is normal for an HTTPS destination to use an http:// proxy URL because the proxy carries the TLS connection with HTTP CONNECT.

Examples:

HTTPS_PROXY=http://proxy.example.com:8080
NO_PROXY=localhost,127.0.0.1,::1,keystore.internal.example.com,.internal.example.com,10.0.0.0/8

Do not add app.certkit.io to NO_PROXY when it must use the proxy. Add an on-premise CertKit Keystore host to NO_PROXY when that connection should remain on the local network.

Windows

The CertKit Agent runs as the certkit-agent Windows service under LocalSystem by default. A variable set only in an administrator’s PowerShell session or user profile is not available to that service. Set it at Machine scope from an elevated PowerShell prompt:

[Environment]::SetEnvironmentVariable(
    "HTTPS_PROXY",
    "http://proxy.example.com:8080",
    [EnvironmentVariableTarget]::Machine
)

[Environment]::SetEnvironmentVariable(
    "NO_PROXY",
    "localhost,127.0.0.1,::1,keystore.internal.example.com,.internal.example.com",
    [EnvironmentVariableTarget]::Machine
)

Restart-Service certkit-agent

Confirm the persistent Machine values:

[Environment]::GetEnvironmentVariable("HTTPS_PROXY", "Machine")
[Environment]::GetEnvironmentVariable("NO_PROXY", "Machine")
Get-Service certkit-agent

If a service restart does not pick up a newly created Machine variable, restart Windows so the Service Control Manager and agent receive a new environment block.

To remove the proxy configuration:

[Environment]::SetEnvironmentVariable("HTTPS_PROXY", $null, "Machine")
[Environment]::SetEnvironmentVariable("NO_PROXY", $null, "Machine")
Restart-Service certkit-agent

Linux with systemd

Shell exports and files such as .bashrc do not configure the systemd service. Add a service override:

sudo systemctl edit certkit-agent

Enter:

[Service]
Environment="HTTPS_PROXY=http://proxy.example.com:8080"
Environment="NO_PROXY=localhost,127.0.0.1,::1,keystore.internal.example.com,.internal.example.com"

Apply the change and restart the agent:

sudo systemctl daemon-reload
sudo systemctl restart certkit-agent
sudo systemctl show certkit-agent --property=Environment
sudo journalctl -u certkit-agent -n 100 --no-pager

To remove the proxy, run sudo systemctl edit certkit-agent, delete the two Environment= lines, then run systemctl daemon-reload and restart the service.

Authenticated proxies

Proxy credentials can be included in the URL:

HTTPS_PROXY=http://proxy-user:password@proxy.example.com:8080

Percent-encode reserved characters in the username or password. Environment variables and systemd unit configuration are visible to administrators, so use a restricted proxy account and follow the organization’s credential-management policy.

TLS inspection

When a proxy intercepts TLS, the agent host must trust the proxy’s issuing CA in the operating-system trust store. Without that CA, the agent can reach the proxy but TLS validation fails with an error such as x509: certificate signed by unknown authority.

Scope and troubleshooting

Proxy variables apply to the agent’s Go HTTP client, including its CertKit API requests and certificate downloads. They do not automatically configure PowerShell, curl, SSH, vendor CLIs, or other tools called by deployment scripts. Configure those tools separately when a deployment target also requires a proxy.

After changing proxy settings, confirm the agent returns online in CertKit and review its logs:

Windows:

Get-Content "C:\ProgramData\CertKit\certkit-agent\certkit-agent.log" -Tail 100

Linux:

sudo journalctl -u certkit-agent -n 100 --no-pager

Common causes of failure are an unreachable proxy address, proxy authentication rejection, TLS inspection without a trusted CA, or an overly broad NO_PROXY entry.