Plan, deploy, and verify

Enclavr deploys only the record whose hostname exactly matches the current machine. It validates first, plans in the Go control plane, then sends complete action envelopes to narrow operating-system adapters.

Open the deployment flow full size

Before the change

1. Refresh the checkout through the approved repository update process.
2. Confirm hostname and the intended namespace.
3. Confirm the protected .env still selects the accepted OpenBao connection.
4. Read the change to authoritative assets or service documents before applying it.
5. Choose an end-to-end verification from the real client path, not only a local healthcheck.

Validate and review

./enclavr config validate
./enclavr host plan

These commands have deliberately different boundaries:

• config validate authenticates the selected provider, loads canonical documents, materializes assets, rejects duplicate JSON keys, applies the schema, and checks topology.
• host plan selects the current host and emits an ordered, value-free action plan. It leaves protected action templates unresolved.
• Neither command proves that every secret needed by a later action is readable. That happens narrowly during deployment for the selected action inputs.

If the current hostname is absent, normal deployment reports a successful no-op. Fix the authoritative inventory rather than adding a fallback source or forcing another hostname.

Apply

After reviewing the plan:

./enclavr host deploy --yes

To reconcile one action only, use its exact catalog ID:

./enclavr host deploy --only caddy-mask-proxy.deploy --yes

--only narrows execution; it does not bypass configuration validation, host selection, secret resolution, confirmation, or action verification. Never place a protected value in --only, another argument, or an environment shown in a terminal transcript.

Verify at three levels

1. Control plane: the command completed with structured action results and no unresolved input.
2. Managed host: run ./enclavr host status and inspect the affected file, service, container, or package through its normal local status surface.
3. Consumer path: verify DNS, TLS, routing, authentication, and the application from the network and identity that actually use it.

A container healthcheck proves only its declared local check. It is not evidence that public DNS, certificates, private access policy, or an upstream application works end to end.

Prove convergence

Run the same deployment again with unchanged authoritative inputs:

./enclavr host plan
./enclavr host deploy --yes
./enclavr host status

The second run must preserve effective state: no unconditional reinstall, rewrite, recreation, restart, credential reset, or re-enrollment. A required stopped service may be started, and real drift must still be reconciled. Record initial application, unchanged repeat, changed-input reconciliation, and retry after partial failure when the affected component is stateful.

If deployment stops

• Missing provider input: check Repository environment and authentication. OpenBao is the only supported provider and requires an accepted configr_openbao_config_file. Retired service-account credentials cannot repair a missing connection. --yes does not supply authentication.
• Provider or cluster identity failure: do not fall back to 1Password. Check the accepted connection and contact the OpenBao operator.
• Schema or topology failure: correct the authoritative document through the protected edit workflow.
• Protected action input unreadable: correct that reference or the host identity's exact item scope; unrelated host secrets are not required.
• Caddy publication rejected: follow Caddy publication troubleshooting. Publication checks the Caddyfile's own content hash; unrelated assets, secrets or users edits do not invalidate it. A changed or unpublished Caddyfile can be prepared and published on the writer through ./enclavr → Config → Prepare Caddy publication, then Publish Caddy publication. A successful host plan does not check that protected execution payload. Older errors mentioning source-version mismatches require updating and relaunching Enclavr.
• Adapter failure: preserve the diagnostic command, status, file, line, and caller stack. Correct the cause and rerun; adapters are designed to converge after partial work.
• Live service verification fails: treat the deployment as incomplete even if the local command succeeded.

For provider responsibilities, see Secret-store boundaries. For configuration changes, see Edit private data safely.

Command metadata is recorded under logs_enclavr_local/commands/; execution logs are under logs_enclavr_local/deploy/. A deployment rejected during execution-plan validation can have a command failure record without an adapter log, because no adapter started. Keep these files private; the command's terminal diagnostics may contain additional context that is intentionally absent from the value-free metadata.