Air-gapped install

Cosmonic Desktop normally installs the build toolchain the first time you build, pulling wash, wkg, and wasm-tools from Cosmonic's namespace on the GitHub Container Registry (ghcr.io). On a machine with no internet access, you bring the same signed tools in an offline bundle instead. The trust model is unchanged: the bundle carries the cosign signatures, and the daemon verifies every tool against the key built into the app before installing it, exactly as it would online.

How it works

On a connected machine, the signed tool artifacts and their signatures are packed into a single OCI image-layout archive. You carry that archive to the air-gapped machine and import it into Desktop's local store. From then on the toolchain installs with no network: the tools are already present locally, and they still verify against Cosmonic's key.

Prerequisites

• A connected machine to build the bundle on.
• The target air-gapped machine with Cosmonic Desktop installed.
• The cosmonicd command (the Cosmonic Desktop daemon) on both. It ships inside the app; see the daemon CLI.

1. Build the bundle on a connected machine

Match the platform to the air-gapped machine, for example x86_64-unknown-linux-gnu. For a mixed fleet, build one bundle covering every supported platform with --all-platforms.

cosmonicd toolchain bundle --triple x86_64-unknown-linux-gnu
# → toolchain-bundle-x86_64-unknown-linux-gnu.tar
# --all-platforms → toolchain-bundle-all.tar

The bundle contains the signed wash, wkg, and wasm-tools artifacts for that platform plus their cosign signatures, each verified against Cosmonic's key as it is packaged, so a bundle never carries a tool that would not install. It does not contain the Rust toolchain. Install Rust from your internal mirror instead (see Restricted networks).

2. Transfer and import on the air-gapped machine

Copy the archive across through your usual transfer process, then import it:

cosmonicd oci import toolchain-bundle-x86_64-unknown-linux-gnu.tar

The import verifies every blob against its digest as it loads, and never reaches the network.

3. Install

In Cosmonic Desktop, open Settings → Toolchain, select Re-check, then install. Desktop finds wash, wkg, and wasm-tools in the imported store, verifies each against Cosmonic's key, and installs them with no network access.

Building still resolves project dependencies

Installing the toolchain offline does not make a build fully offline. Compiling a component still resolves its own dependencies, and those come from registries: a Rust build fetches crates from crates.io, and a Go or TypeScript build may resolve WIT interface definitions (through wkg) and language packages from their registries. On an air-gapped machine, satisfy those ahead of time (a warm ~/.cargo cache or vendored crates for Rust, or vendored wit/deps for a component that resolves WIT at build), or point each tool at an internal mirror. This bundle covers the signed toolchain, not your project's dependency graph.

Keeping it current

When a Desktop update raises the pinned tool versions, rebuild the bundle on the connected machine and import it again. The bundler will not overwrite an existing .tar, so remove or rename the previous one first, or pass a new --out path. A stale bundle is harmless: the daemon installs only what verifies against the current pinned digests, so an out-of-date bundle is ignored until you refresh it.

Takeaways

• Air-gapped installs use the same signed tools and the same verification as online installs.
• Build the bundle on a connected machine, transfer it, and cosmonicd oci import it.
• Match the bundle's platform to the target, or bundle every platform for a fleet.
• Install Rust from an internal mirror; the bundle covers wash, wkg, and wasm-tools.
• The bundle installs the toolchain offline, but a build still resolves your crates and WIT deps; vendor or mirror those too.