Onboarding overview

Onboarding is how you bring a host and its application under Churchill’s protection. It is one wizard with two sides. An operator drives the Register application wizard in the dashboard, and an administrator runs a few commands on the host. The two sides meet in the middle: the wizard watches the host’s progress and advances on its own.

The journey has two distinct milestones, registered and protected, and the gap between them is a change approval. Keeping the two apart is the key to understanding the whole flow.

The journey

1. Issue a provisioning code. In the dashboard, open Protected apps and select + Register application. The wizard asks for the tenant, environment, and source network scope, then issues a one-time code with a lifetime of 15 minutes, 1 hour, or 8 hours. The code is shown once. Copy it then. See Provisioning codes.
2. Run chrlctl on the host. chrlctl is the Churchill Host CLI. The wizard’s connect step supplies the download, a hash check, and the command: sudo ./chrlctl register --code <code>. Run on a terminal, chrlctl walks the administrator through the application to protect, the paths to monitor, and whether to record interactive logins, and registers nothing until they confirm the summary. The host then generates its own identity key and pairs outbound. Churchill never reaches into the host. The host receives a per-host certificate, and chrlctl uploads the configuration. See Running chrlctl.
3. Watch the wizard advance. Back in the dashboard, the wizard moves past the code screen on its own as soon as the host pairs. The discovered configuration appears for review shortly after. You do not need to refresh anything.
4. Review and submit. Name the application, check the discovered configuration, and submit. This stages a change request for approval. Nothing deploys yet. See Registering an application.
5. Wait for CAB approval, then publish. The change request needs quorum from your Change Advisory Board. Once quorum lands, an operator publishes the change from its detail view. See Approvals.
6. The host picks up the signed bundle. On its next poll (the poller runs continuously and polls about every 15 seconds), the host fetches the published bundle, verifies its signatures and hashes, and loads everything into a sealed, read-only, in-memory runtime. Protection starts, and the application’s baseline locks on its first report. Nothing from the bundle persists on disk. The only Churchill footprint that stays on the host is its identity record, its certificate, the tenant it joined, a copy of chrlctl, and the small poller service.
7. Verify. Confirm the host in Fleet and the application on Protected apps. See Verifying enrollment.

Note

A provisioning code is single-use. Exactly one host redeems it, once, and it is then dead. Each host needs its own fresh code.

The two milestones

• Registered (steps 1-4). The host paired with the control plane, and its application’s configuration was discovered, reviewed, and submitted. The host has a durable identity, but nothing is enforced yet.
• Protected (steps 5-7). The CAB approved the change, the host loaded the signed bundle, and the application is online under enforcement with its baseline locked.

Registration takes minutes. Protection waits on the CAB. Plan for the gap between the two: the application runs unprotected until the change request is approved, published, and deployed.

What success looks like

A finished onboarding ends with all of the following true:

• The host is listed in Fleet with a healthy state and fresh heartbeats: a low φ and a small Last HB.
• The application’s card on Protected apps shows a running lifecycle chip and a deployed governance pill.
• The registration’s change request shows deployed on the CAB page.
• No lockdowns are in effect on the host.

Common failure causes

If onboarding stalls, it is usually one of these:

• The code expired or was revoked before the host paired. Issue a new code and run chrlctl again.
• The host is outside the code’s network scope. The pairing is refused and the code is not consumed. Retry from a network inside the scope, or issue a new code with the right scope.
• Discovery finds more than one candidate service. On a terminal chrlctl lists what it found and asks you to pick. Run unattended, it does not guess: run it again with --unit to name the service explicitly. See Running chrlctl.
• The change request is not yet approved or published. The application stays unprotected until the CAB reaches quorum and the change is published. Check its status under Approvals.
• The registration was left unfinished. A registration whose host already uploaded its configuration parks under Discovered apps awaiting review on Protected apps. Resume it from there, or discard it. See Registering an application.

Caution

Churchill is fail-closed. Once protection starts, an unauthorized change to the protected application means Churchill terminates the affected process rather than let it keep running. Plan onboarding, and every change after it, with that behavior in mind, especially on production hosts.

Where to go next

Work through these pages in order for a new host:

1. Host requirements: confirm the host can run Churchill and reach the control plane.
2. Provisioning codes: issue, track, and revoke the one-time codes that pair a host.
3. Running chrlctl: run the enrollment command on the host, and what it does there.
4. Registering an application: review the discovered configuration and submit it for approval.
5. Verifying enrollment: confirm the host and application reached the protected milestone.

For terms used throughout these pages, see the glossary.