Documentation / Start here
Start here · v0.0.1 Install the lifecycle agent Deploy the container-first agent, establish its trust and placement contract, then verify heartbeat and version compatibility.
Audience Platform administrators, network and security teamsReading time 15 minCommands in context 19 guided stepsReviewed source fcc5871 · 30 July 2026
RC Exact release scope. This page documents the reviewed v0.0.1 source at fcc5871. Check release status before enabling a gated capability.
Placement and host baseline The Linux agent runs as a long-lived container. The release includes a Compose deployment and an optional systemd wrapper. Supported host baselines are Ubuntu 22.04 or newer, Debian 12 or newer, and RHEL/Rocky/AlmaLinux 9 or newer.
Trust mode Use when Requirement Public CA TLS The API endpoint has a publicly trusted certificate. Hostname verification and complete chain must succeed. Private CA TLS The customer PKI signs the API endpoint. Provide the trusted CA path; do not disable certificate verification. mTLS The deployment profile requires mutual identity. Provision client identity and CA trust through the supported secret boundary. Loopback/local Agent and API share the approved single-node profile. Keep the bind local and document the placement exception.
Commands for this step Choose exactly one agent installation model Systemd is the normal Linux service path; the container path is suitable for approved container-managed hosts.
Choose one path Run only the command that matches your situation.
01
Privileged Linux
Install the systemd-managed agent Use this when Recommended for a dedicated Linux lifecycle-agent host.
Install the same container deployment with a boot-managed systemd wrapper.
Before you run it Supported systemd Linux host Docker Engine and Compose v2 Linux · agent-systemd-install Copy
sudo ./agent/linux/bin/install-systemd.sh
sudoedit /etc/clusterpilot-agent/clusterpilot-agent.env✓ Expected result The unit is installed but not started until validation succeeds.
Reviewed source docs/agent/self-hosted-install.md02
Privileged Linux
Install agent container artifacts Use this when Use on an approved container-managed agent host.
Install the container-first lifecycle agent files, safe directories and signed conformance tool material.
Before you run it Supported Linux host Docker Engine and Compose v2 Exact agent files from the signed release bundle Linux · agent-container-install Copy
sudo ./agent/linux/bin/install-container.sh
sudoedit /etc/clusterpilot-agent/clusterpilot-agent.env✓ Expected result Agent files are installed under /opt/clusterpilot-agent and a protected environment file exists.
Reviewed source docs/agent/self-hosted-install.mdCommands for this step Install under custom protected paths Use this only when the organization prohibits the standard agent roots and has approved equivalent ownership, permissions, backup, and monitoring.
Use when needed Do not run these commands unless the described condition applies.
01
Privileged Linux
Install the agent at explicit protected paths Use every supported container-installer path override while retaining the release trust key explicitly.
Before you run it Supported Linux host Exact files and public key from the signed release Approved absolute install and environment paths Linux · agent-custom-install-root Copy
sudo ./agent/linux/bin/install-container.sh \
--env-file /etc/clusterpilot-agent/clusterpilot-agent.env \
--install-root /opt/clusterpilot-agent \
--release-public-key ./release-signing-public-key.pem✓ Expected result The bounded install root, environment path and canonical release public key are installed with protected ownership.
Stop conditions and operator notes Do not substitute an unverified public key. The default install root is the supported production path unless an approved packaging profile says otherwise. Reviewed source agent/linux/bin/install-container.shBootstrap configuration /etc/clusterpilot-agent/clusterpilot-agent.env Copy
CP_AGENT_BACKEND_URL=https://clusterpilot.example.com
CP_AGENT_ID=agent-prod-eu-01
CP_AGENT_BOOTSTRAP_TOKEN_FILE=/run/secrets/clusterpilot-bootstrap-token
CP_AGENT_TRUSTED_CA_PATH=/etc/ssl/certs/customer-root-ca.pem
CP_AGENT_IMAGE=registry.example.com/clusterpilot/clusterpilot-agent@sha256:<digest>
CP_AGENT_SHUTDOWN_GRACE_SECONDS=300Long-lived installs should use CP_AGENT_BOOTSTRAP_TOKEN_FILE. The parser accepts strict KEY=VALUE input and rejects shell substitution, backticks, pipes, and redirects.
Commands for this step Prepare the selected agent Install the token through the protected file boundary, validate configuration, reconcile permissions, and materialize the approved Kubernetes tools.
Run in order Complete each step successfully before continuing.
01
Privileged Linux
Install the agent bootstrap token file Use this when Always install the short-lived bootstrap token through the protected token file.
Deliver the one required bootstrap credential without placing it in the environment file or command history.
Before you run it Fresh bootstrap token issued through the approved administrative path Linux · agent-token Copy
sudo install -m 0600 /dev/stdin /etc/clusterpilot-agent/bootstrap.token
# Paste the token, press Enter, then Ctrl-D.✓ Expected result The token file exists with mode 0600 and is not echoed into logs.
Reviewed source docs/agent/self-hosted-install.md02
Read-only Linux
Validate agent configuration Validate strict KEY=VALUE parsing, immutable image identity, trust, token and runtime settings before start.
Before you run it Configured environment and token file Linux · agent-validate Copy
sudo /opt/clusterpilot-agent/bin/clusterpilot-agent-bootstrap.sh \
validate --env-file /etc/clusterpilot-agent/clusterpilot-agent.env✓ Expected result Exit 0 with no E7_BOOTSTRAP_* issue.
Reviewed source agent/linux/bin/clusterpilot-agent-bootstrap.sh03
Privileged Linux
Reconcile agent directory permissions Create and repair the bounded state, log, Secret and tool directories using the configured runtime identity.
Before you run it Validated agent environment Linux · agent-ensure-dirs Copy
sudo /opt/clusterpilot-agent/bin/clusterpilot-agent-bootstrap.sh \
ensure-dirs --env-file /etc/clusterpilot-agent/clusterpilot-agent.env✓ Expected result Required directories exist with the supported root:65532 and 65532:65532 ownership boundaries.
Reviewed source agent/linux/bin/clusterpilot-agent-bootstrap.sh04
Privileged Linux
Repair and verify managed SSH file permissions Restore the supported agent UID/GID access boundary when SSH material exists but is unreadable.
Before you run it Confirmed ownership problem No active command using the file Linux · agent-ssh-permissions Copy
sudo chown root:65532 /var/lib/clusterpilot-agent /var/lib/clusterpilot-agent/secrets
sudo chmod 0770 /var/lib/clusterpilot-agent /var/lib/clusterpilot-agent/secrets
sudo chown 65532:65532 /var/lib/clusterpilot-agent/secrets/cluster-managed-ssh-key
sudo chmod 0600 /var/lib/clusterpilot-agent/secrets/cluster-managed-ssh-key
docker exec -u 65532:65532 clusterpilot-agent \
test -r /var/lib/clusterpilot-agent/secrets/cluster-managed-ssh-key✓ Expected result The agent runtime identity can read the key and no broader permission is introduced.
Reviewed source docs/runbooks/cluster-node-preparation-troubleshooting.md05
Read-only Linux
Verify agent-local kubectl and lifecycle kubeconfig Diagnose Kubernetes read/lifecycle work without installing a host-global kubectl or exposing kubeconfig.
Before you run it Agent container access Expected lifecycle materialization already attempted Linux · agent-kubectl-materialization Copy
docker exec -u 65532:65532 clusterpilot-agent \
find /var/lib/clusterpilot-agent/tools/kubectl -maxdepth 2 -type f -name kubectl -perm -0100
docker exec -u 65532:65532 clusterpilot-agent \
find /var/lib/clusterpilot-agent/secrets -maxdepth 1 -type f -name '*lifecycle-kubeconfig' -perm -0600
docker exec -u 65532:65532 clusterpilot-agent sh -lc \
'k=$(find /var/lib/clusterpilot-agent/tools/kubectl -maxdepth 2 -type f -name kubectl | head -n 1); c=$(find /var/lib/clusterpilot-agent/secrets -maxdepth 1 -type f -name "*lifecycle-kubeconfig" | head -n 1); test -n "$k" && test -n "$c" && "$k" --kubeconfig "$c" get --raw=/readyz >/dev/null'✓ Expected result A bounded executable and protected kubeconfig exist and /readyz succeeds.
Reviewed source docs/runbooks/cluster-node-preparation-troubleshooting.md06
Read-only Linux
Verify agent-local Helm materialization Diagnose add-on work using the release-pinned agent tool rather than a host-global binary.
Linux · agent-helm-materialization Copy
docker exec -u 65532:65532 clusterpilot-agent \
find /var/lib/clusterpilot-agent/tools/helm -maxdepth 3 -type f -name helm -perm -0100
docker exec -u 65532:65532 clusterpilot-agent sh -lc \
'h=$(find /var/lib/clusterpilot-agent/tools/helm -maxdepth 3 -type f -name helm | head -n 1); test -n "$h" && "$h" version --short'✓ Expected result The expected executable exists and reports the supported version.
Reviewed source docs/runbooks/cluster-node-preparation-troubleshooting.mdCommands for this step Start exactly one agent service model Choose the command that matches the installed service model. Do not start both systemd and container-managed loops for the same agent identity.
Choose one path Run only the command that matches your situation.
01
Privileged Linux
Install and start a preconfigured systemd agent Use this when Use when the systemd configuration is complete and the service should be enabled and started now.
Use the systemd installer's complete override surface and start only an already prepared, valid environment.
Before you run it Supported systemd Linux host Complete protected environment and token files already present API, registry, DNS, TLS and time reachability proven Linux · agent-systemd-enable-now Copy
sudo ./agent/linux/bin/install-systemd.sh \
--env-file /etc/clusterpilot-agent/clusterpilot-agent.env \
--install-root /opt/clusterpilot-agent \
--enable-now✓ Expected result The installer validates configuration, enables the unit and starts a healthy agent container.
Stop conditions and operator notes Omit --enable-now when configuration or network acceptance is not yet complete. Reviewed source agent/linux/bin/install-systemd.sh02
Changes state Linux
Enable and start the systemd agent Use this when Use when the systemd unit is installed but should be started as a separate approved step.
Start the validated agent and enable restart at boot.
Before you run it systemd wrapper installed Agent validation passes Linux · agent-start-systemd Copy
sudo systemctl enable --now clusterpilot-agent.service
sudo systemctl status clusterpilot-agent.service --no-pager✓ Expected result The unit is active and the underlying Compose service is healthy.
Reviewed source docs/agent/self-hosted-install.md03
Changes state Linux
Start the container-managed agent Use this when Use only for the container-managed installation path.
Start the digest-pinned long-lived agent and wait for container health.
Before you run it Agent validation passes API, DNS, time, registry and trust reachability pass Linux · agent-start-container Copy
sudo docker compose \
--file /opt/clusterpilot-agent/container/compose.yaml \
--project-name clusterpilot-agent \
up --detach --wait✓ Expected result The clusterpilot-agent container is running and healthy.
Reviewed source docs/agent/self-hosted-install.mdValidate locally and verify heartbeat Then verify the agent in GET /api/v1/agent/active and the administrator fleet view. Do not enable lifecycle operations until placement, trust, runtime, reachability, clock, and contract-version checks are accepted.
Commands for this step Accept the agent only after local and backend proof Verify the process locally, confirm the backend heartbeat, pin a fixed observation time, run the smoke test, and retain bounded logs.
Run in order Complete each step successfully before continuing.
01
Read-only Linux
Verify local agent health Check the agent-local health and readiness endpoints.
Linux · agent-verify-local Copy
sudo /opt/clusterpilot-agent/bin/clusterpilot-agent-bootstrap.sh \
verify-local --env-file /etc/clusterpilot-agent/clusterpilot-agent.env✓ Expected result Both local health and readiness probes succeed.
Reviewed source docs/agent/self-hosted-install.md02
Read-only Linux
Verify the first backend heartbeat Confirm that the configured agent appears in the active fleet at the current UTC time.
Before you run it Running agent Control-plane API reachable Linux · agent-verify-heartbeat Copy
sudo /opt/clusterpilot-agent/bin/clusterpilot-agent-bootstrap.sh \
verify-heartbeat --env-file /etc/clusterpilot-agent/clusterpilot-agent.env✓ Expected result The configured CP_AGENT_ID is present in GET /api/v1/agent/active.
Reviewed source docs/agent/self-hosted-install.md03
Read-only Linux
Verify heartbeat and smoke state at a fixed UTC instant Reproduce time-sensitive agent acceptance deterministically during incident review or controlled validation.
Before you run it Running agent A recorded ISO-8601 UTC decision time Control-plane API reachability Linux · agent-time-bounded-verification Copy
sudo /opt/clusterpilot-agent/bin/clusterpilot-agent-bootstrap.sh \
verify-heartbeat \
--env-file /etc/clusterpilot-agent/clusterpilot-agent.env \
--as-of-utc <iso-8601-utc>
sudo /opt/clusterpilot-agent/bin/smoke-test.sh \
--env-file /etc/clusterpilot-agent/clusterpilot-agent.env \
--as-of-utc <iso-8601-utc>✓ Expected result Heartbeat-window and full smoke checks are evaluated against the same explicit UTC instant.
Stop conditions and operator notes Use the current-time commands for normal acceptance; fixed time exists for deterministic evidence and testing. Reviewed source agent/linux/bin/clusterpilot-agent-bootstrap.sh; agent/linux/bin/smoke-test.sh04
Read-only Linux
Run the complete agent smoke test Execute validation, local readiness and heartbeat verification as one bounded check.
Before you run it Running agent and active control plane Linux · agent-smoke Copy
sudo /opt/clusterpilot-agent/bin/smoke-test.sh \
--env-file /etc/clusterpilot-agent/clusterpilot-agent.env✓ Expected result ClusterPilot agent bootstrap checks passed.
Reviewed source agent/linux/bin/smoke-test.sh05
Read-only Linux
Inspect agent service and logs Collect bounded agent diagnostics without exporting its environment or token.
Linux · agent-logs Copy
sudo systemctl status clusterpilot-agent.service --no-pager
sudo journalctl -u clusterpilot-agent.service --since '-30 min' --no-pager
docker logs clusterpilot-agent --tail 200✓ Expected result Service state, first failing code and correlation identifiers are visible; no secret is copied.
Reviewed source docs/agent/troubleshooting-and-migration.mdVersion and shutdown contract State Behavior N Current agent version; fully compatible. N-1 Accepted during a rolling upgrade; upgrade before the next control-plane version. N-2 or older Rejected with AGENT_VERSION_INCOMPATIBLE and receives no work. Missing contract advertisement Incompatible; no work is issued.
Preserve cleanup time The agent forwards HUP, INT, and TERM to the lifecycle executor and reserves up to 300 seconds for cleanup by default. Keep the container stop grace above that value; the release Compose contract uses 330 seconds.
Safe rollout order 01 Deploy agents that advertise the new contract Keep the control plane on the existing run contract during this step.
02 Verify the active fleet Confirm version, placement, trust, clock, and supported contract versions.
03 Enable the new run contract Only after a compatible agent is active should the control plane issue new-version work.
04 Retire N-1 agents Drain or let compatible work finish, then converge the fleet before the next upgrade.
Commands for this step Check and apply an approved agent update The check is read-only. Apply only a compatible, approved update after the control plane has been upgraded and verified.
Run in order Complete each step successfully before continuing.
01
Read-only Linux
Check for an agent self-update Query the governed update manifest and inspect the target version, digest and rollout posture without changing the agent.
Before you run it Running registered agent Scoped update-manifest access Approved backend and registry trust Linux · agent-self-update-check Copy
sudo /opt/clusterpilot-agent/bin/agent-self-update.sh \
check --env-file /etc/clusterpilot-agent/clusterpilot-agent.env✓ Expected result The script reports no update or a digest-pinned eligible target without replacing the running agent.
Reviewed source agent/linux/bin/agent-self-update.sh02
Privileged Linux
Apply an approved agent self-update Download, verify and apply the governed digest-pinned agent update with health verification and rollback behavior.
Before you run it Approved update decision and maintenance window No active lifecycle step Successful check result Current agent files and environment backed up Linux · agent-self-update-apply Copy
sudo /opt/clusterpilot-agent/bin/agent-self-update.sh \
apply --env-file /etc/clusterpilot-agent/clusterpilot-agent.env✓ Expected result The new digest becomes healthy; on failed health verification the script restores the previous agent state.
Stop conditions and operator notes Never run apply while the agent owns active work. Re-run verify-local, verify-heartbeat and compatibility acceptance after completion. Reviewed source agent/linux/bin/agent-self-update.sh