Agents & automation

1. Enable agent registration

Registration is gated by a shared bootstrap token. Set it on the server (the appliance wizard can also do this for you):

# in the server's .env
ENS0KEY_AGENT_BOOTSTRAP_TOKEN=$(openssl rand -hex 24)

Without the token, registration is disabled.

2. Install the agent

The agent ships as supervisor and worker binaries. The fastest path: under Agents & jobs → Agents, expand Agent installation and uninstall and download the ready-made archive for Linux (.tar.gz) or Windows (.zip).

Download the package from your local ens0key appliance and transfer it to the target host. Installed agents retrieve upgrades from the appliance; the host does not need access to an Internet download portal or registry.

Linux (systemd)

tar xzf ens0key-agent-linux-amd64.tar.gz && cd ens0key-agent-linux-amd64
sudo sh ./install.sh                 # binaries -> /opt/ens0key-agent/bin, user 'ens0key'
sudo nano /etc/ens0key/agent.env     # server URL + bootstrap token
sudo systemctl enable --now ens0key-agent
journalctl -u ens0key-agent -f       # logs

Windows (service)

# put both .exe (agent + worker) into a permanent folder
$dir = "C:\Program Files\ens0key"
Expand-Archive ens0key-agent-windows-amd64.zip .; Copy-Item .\ens0key-agent-windows-amd64\* $dir

# configuration
@"
ENS0KEY_SERVER_URL=https://pki.example.com
ENS0KEY_AGENT_BOOTSTRAP_TOKEN=<token>
ENS0KEY_AGENT_NAME=win-01
"@ | Set-Content C:\ProgramData\ens0key\agent.conf

cd $dir; .\ens0key-agent.exe install   # registers + starts the service

Trusting the server

In production, give the agent the CA that signed the server's certificate via ENS0KEY_AGENT_SERVER_CA (a PEM bundle) — or use a publicly trusted server certificate. ENS0KEY_AGENT_INSECURE exists for labs only: it skips server authentication entirely.

3. Approve the agent

A newly registered agent lands in pending and cannot claim jobs until an admin approves it on the Agents tab. Once approved it gets its mTLS identity and starts polling. Online/offline status uses authenticated agent activity. From 1.0.35, the upgraded supervisor also sends heartbeats every 15 seconds while executing work or retrying result delivery; recent logs can be pulled into the UI.

The optional FQDN is displayed alongside the hostname. A missing FQDN does not block work or change the agent's identity. In 1.0.29, authenticated job polling refreshes capabilities after an upgrade while preserving the agent ID, credentials, approval, stores and history. Upgrade both binaries if a newly supported store type is unavailable; re-registration is not required.

4. Put certificates on auto-renewal

• ▸Certificate stores — a location the agent manages: a PEM directory, an nginx PEM profile, a PKCS#12 or JKS keystore, or a Windows IIS binding. Add service checks to confirm the endpoint actually serves the deployed certificate.
• ▸Auto-renewals — bind a CA + Common Name + store: ens0key issues, the agent deploys, and it renews before expiry — optionally running a reload command (e.g. nginx -s reload) after each push. If post-deploy verification fails, the agent restores the previous certificate automatically.
• ▸Blueprints — a reusable template (stores + renewals + checks) you apply to each new agent for fleet rollout.
• ▸Jobs — live status and exact-job links for work dispatched to agents.

Follow the nginx host setup guide for separate certificate/key files and the HTTPS verification guide to confirm the served certificate after deployment.

Scheduled store inventory

From 1.0.35, each agent store can use an inventory interval of 1–8760 hours; zero means manual. Existing stores remain manual until explicitly enabled. The scheduler waits for an online, approved agent with the required capability and avoids overlapping inventory jobs for that store. Unavailable agents do not accumulate a periodic backlog.

Review the last successful inventory, next run, observed additions and removals, and the latest job. The first successful scan establishes a baseline; later changes can include external operations without identifying who made them. Failed scans preserve the last successful snapshot and deltas. A successful empty scan is authoritative. Inventory membership remains separate from deployment history.

Capabilities and readiness are separate from installation and service verification. Both agent binaries at 1.0.35 support readiness checks for saved JKS/PKCS#12 stores, including file contents/password and replacement permissions. Linux PEM/nginx checks remain available. With Windows supervisor and worker 1.0.36 or newer, IIS readiness inspects sites, bindings, hostname, SNI and certificate thumbprints without changing bindings or importing certificates. It does not prove installation permissions or successful TLS service verification; validate those on the actual target.

5. Upgrade agents from the UI

An agent older than the server shows an outdated badge with an Upgrade button. The supervisor downloads updated worker and supervisor binaries over mTLS, checks SHA-256 and self-tests both before replacing either. Each file is replaced by rename; previous copies are retained and restored if a later swap fails. After reporting the job result, a changed supervisor restarts: Linux re-execs the process, while Windows relies on the service recovery configuration.

Upgrade the server first, then agents. Confirm both the reported version and a fresh heartbeat for the same agent ID after completion. A successful job alone does not prove the restarted process is healthy. Retain host access and previous files: a pair of renames is not atomic across power loss, and arbitrary failures after restart do not trigger automatic rollback. The nginx helper is installed and updated separately by a host administrator.

Reliable execution and result delivery

From 1.0.35, Jobs distinguishes Executing on host, Result awaiting server acknowledgement and Outcome unconfirmed. Upgrade both supervisor and worker to use the new telemetry and durable results. Older agents remain compatible. Keep the private agent state directory persistent, writable and restricted to its service account.

The supervisor records a marker before execution and persists the result afterwards. If delivery fails, it retries the saved result without repeating the host operation; new work waits for acknowledgement. An interrupted execution, timeout or lost claim response can require inspection of the host and job history. Do not delete the result journal or submit a duplicate deployment to resolve an uncertain outcome.

Cancel is available only before claim. Revoking access or resetting an agent cannot stop an already running OS operation. Lost connectivity does not prove that execution stopped or failed.

Deployment outcomes and IIS

Locations distinguish pending, running, successful and failed work. A failed retry retains the previous successful installation. Older agent deployment records can remain unverified until inventory or redeployment confirms them. Renew-everywhere targets previously successful explicit deployments; an observed certificate alone does not authorize delivery of its private key.

Installed means the installation job succeeded. Service verified requires matching results for all service endpoints requested by that job. Missing or failed probes need attention; an older job without retained probe results is not proof of TLS success.

IIS deployment checks the exact imported leaf, its private key and the resulting thumbprint/store binding. A Site|port target must identify one HTTPS binding. Multiple SNI/IP bindings on the same site and port are rejected as ambiguous; individual selection is not yet supported. Verify the served certificate on the actual Windows/IIS target.

A later successful IIS deployment makes the prior binding historical for that agent, site and port. Pending or failed replacements retain the previous successful binding. Deployment immediately after issuance uses the certificate just issued and displays the job's progress. Operators can remove a failed location only if it has never succeeded; certificates, stores, jobs and remote files remain intact.

Agent uninstall

Agents → Uninstall is an administrator-confirmed host operation, separate from deleting server records. Enter the exact agent name. Both binaries must be at least 1.0.27, the native agent must be online and approved, and the job queue must be idle. Follow the exact uninstall job; an offline agent or an accepted request is not proof of removal.

• ▸Windows requires service-management and file-removal rights. Linux GUI uninstall supports the standard root-run systemd layout; the default hardened non-root service requires manual host-admin removal. Containers and custom layouts also require host/runtime-side removal.
• ▸Confirmed success retires agent credentials, disapproves the agent and disables its managed renewals while retaining stores, certificates and history.
• ▸A missing callback leaves the outcome unconfirmed; inspect the host and receipt before further action. Partial removal can require manual cleanup and administrative revocation.
• ▸The separate nginx helper, sites, certificate files and private recovery backups are not removed by agent uninstall.

In 1.0.35, the detached uninstall helper retries reporting its saved outcome for up to 24 hours while it remains alive; it does not repeat removal. A reboot, helper crash or lost final acknowledgement can leave the result unconfirmed. Inspect the local receipt and server history.

6. Agentless connectors

Open Deploy → Agentless connectors to configure certificate deployment to devices, cloud services and Kubernetes. The ens0key server connects directly to the target through its supported API or SSH interface; no ens0key agent is installed on the target.

Add a target with its address, credentials and connector-specific settings, then choose Deploy and select a certificate with an available private key. Available connectors include:

• ▸F5 BIG-IP (iControl REST) and Cisco ISE (OpenAPI) — REST upload, serial-matched to the inventory.
• ▸Cisco ESA — over SSH (certconfig); the issuing chain is resolved for supported chains and mail-listener bindings are reapplied on renewal. Management HTTPS binding is not currently ready for use; LDAPS and device-version compatibility require target verification. Importing a self-signed internal root trust remains manual.
• ▸Cisco WLC — Catalyst 9800 uses verified HTTPS upload and pinned SSH import, with WebAdmin/WebAuth selection and durable recovery. HTTP is an explicitly acknowledged compatibility mode; AireOS retains TFTP. Follow the WLC deployment guide.
• ▸Fortinet FortiGate and Citrix NetScaler — deploy and renew over their management APIs.
• ▸Cloud certificate stores — Azure Key Vault, AWS ACM and GCP Certificate Manager; renewal updates the stored certificate in place.
• ▸Kubernetes TLS Secret — create or update a named TLS Secret through the Kubernetes API. Configure the consuming Ingress or Gateway separately.

Deployment shows live progress. The target's Log button opens its last deployment log, including a CLI transcript where applicable.

For Cisco IOS / generic SSH key inventory, use SSH → SSH targets (agentless). That screen discovers host keys and configured SSH keys; it is separate from certificate deployment through Agentless connectors.