canic-host

Host-side build, install, deployment, App-source, and multi-root staging tooling for Canic workspaces.

When to use it

Use this crate directly when you need:

• Canic build/install backend code in CI or local automation
• Coordinator/root/Store staging from published backend APIs
• the lower-level host library surface without cloning the full repo

For normal local setup, prefer the root INSTALLING.md guide. From a Canic checkout, use the maintainer setup target:

make install-dev

That path requires Rustup and Cargo, then installs the pinned internal toolchain, the canic CLI, wasm/Candid utilities, and checksum-bound external executables. This README documents the lower-level host library surface.

What this crate is not

This crate is not a general deployment framework and it is not the main Canic application facade. It owns host-side build/install/Fleet/staging utilities for standard Canic Coordinator/root/Store flows. For normal operator use, prefer the installed canic CLI and the compact v1 workflow documented in docs/architecture/v1-operator-walkthrough.md; use install commands only for the local managed-fleet flows that document them explicitly.

It is also separate from:

• canic-backup, which owns backup/restore manifests, journals, topology snapshots, backup layout validation, and restore planning.
• canic-core and canic-control-plane, which run inside canisters or provide canister-runtime support. canic-host runs on the operator machine and may call Cargo, icp, and the local filesystem.

Current 0.100 installation flow:

• compile the App's complete Component Topology and resolve the required operator Fleet input before effects
• build and freeze the exact Fleet Coordinator, Fleet Subnet Root, and Wasm Store infrastructure artifacts
• build one topology-qualified application artifact union and project an exact admitted release set for every planned root
• journal, create, install, and independently verify the Coordinator first
• journal, create, install, and independently verify every planned Fleet Subnet Root
• stage each root's exact release set, bootstrap one root-local Store, and verify its live catalog independently
• register and independently verify every root as Registry Joining
• stage and independently verify the exact all-Joining snapshot and Coordinator acknowledgement at every root
• atomically commit and independently verify the complete Coordinator Registry as all-Active
• atomically activate and independently verify every root's exact all-Active Registry Mirror and Registry-derived Fleet Directory
• seal each root's exact empty initial Component inventory, independently activate its runtime, and publish the terminal Coordinator-anchored Fleet catalog only after every root is reverified

The local driver permits one clean local icp restart attempt when icp ping local fails. Exact journals own same-release interruption recovery; the host does not fall back to the removed single-root installer.

Build profile selection:

• canic build <app> <role> --profile debug builds raw debug wasm
• canic build <app> <role> --profile fast builds the middle shrunk local/test/demo lane
• canic build <app> <role> --profile release builds the shipping/install lane

If omitted, CLI builds default to release.

When the Rust workspace root and ICP CLI/project root differ, pass --workspace, --icp-root, and --config to canic build. The low-level build_artifact example takes those three paths after its role and profile.

If canister crates live outside the default apps/ directory, host discovery first tries Cargo workspace metadata. Every Canic-managed canister package must declare the App-scoped role it implements in Cargo metadata:

[package.metadata.canic]
app = "project"
role = "project_ledger"

For canic install, the implicit environment default is always local; use --environment <name> for one command against another environment. The public CLI requires canic install <app> <fleet> --fleet-input <path>, uses apps/<app>/canic.toml for reusable App topology, and reads concrete placement, admission, limit, and funding policy only from the separate Fleet input.

Canonical network identity is trust-derived rather than environment-derived. IC mainnet profiles resolve from Canic's compiled DER root key. Pre-existing local and connected profiles resolve only through the exact root key and enrollment record under .canic/networks/<canonical-network-id>/; the environment profile is revalidated as a non-authoritative lookup on every resolution.

Disposable physical-root deletion proof

The fleet_subnet_root_deletion example exists for the bounded 0.100 real-network proof. It is not a general operator command. Both phases mutate the selected Fleet: prepare may return excess root cycles and durably freezes the Coordinator execution intent; execute stops and irreversibly deletes the exact root before recording typed absence at the surviving Coordinator.

Use it only after the selected disposable root has completed logical removal, Store deletion, and retained the same nonzero operation ID. Run preparation and execution as separate processes to prove recovery from remote authority:

cargo run -p canic-host --example fleet_subnet_root_deletion -- \
  prepare --confirm-disposable-root-deletion \
  icp . <environment> <coordinator> <root> <64-hex-operation-id>

cargo run -p canic-host --example fleet_subnet_root_deletion -- \
  execute --confirm-disposable-root-deletion \
  icp . <environment> <coordinator> <root> <64-hex-operation-id>

The prepare output is the exact Coordinator execution receipt. The execute output is its terminal deletion receipt; repeating execute returns that same terminal receipt without another root effect.