Registering an application

The Register application wizard is how you place an application under Churchill’s protection. Registration is host-driven. The console issues a one-time provisioning code, and you run chrlctl, the Churchill Host CLI, on the target host. The host pairs outbound, discovers the application, and sends a configuration back for your review. As the wizard’s own intro puts it: “No change is staged until you submit at the end.”

Open the wizard from Protected applications by selecting + Register application. A step rail across the top tracks your progress: provision → connect host → discover → review → submit.

Before you start

• The CAB must be sealed. Until your tenant’s genesis baseline is sealed, the wizard and Protected applications show a gate card instead: “Protected-app registration is gated — CAB uninitialized. The genesis baseline must be sealed by the Change Advisory Board before applications can be registered.” See CAB onboarding.
• A shell on the target host with sudo. You run chrlctl there during the flow. See Running chrlctl.

The wizard

Step 1: issue a provisioning code

The Registration session card sets the scope of the code:

Field	What it sets
tenant	The tenant the registration belongs to.
environment	The environment the application registers under. Defaults to prod.
source CIDR scope	The address range the code can be redeemed from.
code lifetime	How long the code stays redeemable: 15 min, 1 hour, or 8 hours.
change ticket	Optional reference to your ticketing system, recorded with the registration.

Select Issue provisioning code. Codes are single-use and shown exactly once. Churchill keeps only a SHA-256 digest of the code, so this screen is the only place you will ever see it. See Provisioning codes for how codes behave.

Tip

Pick the shortest lifetime that covers your work. If a live code must die early, revoke it from the Provisioning codes register. An unrevoked code stays live until its lifetime runs out.

Step 2: connect the host

The wizard displays the one-time code with a state pill (awaiting host) and a Run on the host card. The card’s own intro reads: “Run the commands below on the host you want to protect. chrlctl pairs out to Churchill using this one-time code — Churchill never reaches into your host.”

The card includes the download itself. Pick the Host architecture (amd64, arm64, or s390x) and copy the three commands in order:

1. Download chrlctl with curl from your console’s own address (the Download chrlctl block).
2. Verify the binary’s SHA-256 with sha256sum -c before you run it.
3. Register: sudo ./chrlctl register --code chrl1-aeabky-3iovzg-…-osa6d4, with the whole code pasted in.

The version being served is shown beside the architecture buttons, and under the commands the card names the release certificate that signed the binary and links to the vendor’s published copy, so the hash is not the only thing you can check it against.

Below the commands, a status panel reads Waiting for host to connect…. The step advances on its own once the host pairs, and the panel switches to show the address the host paired from. If the administrator ran chrlctl on a terminal, expect a pause here: the client walks them through the application, the monitored paths, and the session-recording question before it pairs. See Running chrlctl.

If the code dies first, the wizard says so plainly: “The provisioning code expired before the host paired.” (or “was revoked”). Select Start over to issue a fresh code.

Step 3: wait for discovery

Once paired, the host inspects itself. chrlctl resolves the application’s systemd unit, hashes the binary, and computes the manifest. Discovery runs on the host, never in your browser. The view updates on its own when the host sends its configuration up for review.

Step 4: review the discovered configuration

Everything on this screen except the name was discovered on the paired host and reported by chrlctl. Confirm it before staging the change:

Field	What it shows
application name	The only editable field, and it is required. You name the application here. Continue to submit stays disabled until you do.
binary path	The executable the host resolved for the application.
systemd unit	The unit the application runs under.
scan cadence	How often the host sentinel re-hashes the manifest.
Monitored paths	Every path placed under watch, with a count.
binary sha256 and manifest sha256	The hashes computed on the host. These pin the baseline that enforcement measures against.

Note

You review the manifest, you do not hand-author it. The choice of monitored paths is made on the host: chrlctl’s guided flow offers a checklist and takes additions, and --paths /opt/app,/etc/app sets the list outright. If the review is missing paths you need watched, start over and run the register command again with the full list. Once the application is registered, its manifest changes only through change control.

When the configuration looks right, select Continue to submit. Start over here abandons the registration and returns to the first step.

Step 5: submit for CAB approval

The final screen is explicit about what submitting does: “This stages a protected_app_register change. It is approved by CAB quorum, not deployed on submit.” A Change request card recaps the operation, the target application name, and the manifest hash.

Select Submit for CAB approval. On success you land on the CAB page with the new change request pending. Nothing has reached the host yet. That is the point.

After you submit

1. CAB members approve the change to quorum. The registration sits as a pending change request until enough members sign. See Approvals.
2. The change publishes. The host’s deploy poller (churchill-deploy.service, installed by chrlctl during registration) fetches and adopts the signed bundle.
3. The application comes under protection. Its lifecycle chip on Protected applications reads running once the bundle is adopted. See Verifying enrollment to confirm the result.

Leaving and resuming a registration

Cancel on the first step returns you to Protected applications without issuing anything. Back on the connect step and Start over on the later steps drop the in-progress registration and reset the wizard. Nothing is staged. An unredeemed code is not recalled when you start over. It expires on its own, or you revoke it from the register.

A registration that got as far as an uploaded configuration is not lost when you leave the wizard. It parks on Protected applications under Discovered apps awaiting review, with two actions per row:

• Resume… re-enters the wizard at the discovery step and carries you to review. The code panel is skipped: the plaintext code was served exactly once and cannot be shown again. The wizard notes it is “Reloading the configuration this host already sent up for review.”
• Discard… opens a typed-confirm dialog on the code’s SHA-256 digest. The dialog is explicit about the cost: “The host already uploaded a discovered configuration under this registration. Discarding revokes its provisioning code, so that configuration can no longer be reviewed or staged — registering the application after this means running chrlctl on the host again. Nothing is deployed either way: no change request has been opened yet.”

Every step of the flow lands on the operator audit chain. Issuing a code, staging a configuration, and creating the change request are all recorded with who did what and when.