The build toolchain

To turn your code into a running component, Cosmonic Desktop needs a small set of build tools on your machine. The first time you build, Desktop checks for them and offers to install anything missing, so you rarely have to think about them. This page explains what the toolchain is, how Desktop installs and verifies it, and what a ready-to-build machine looks like.

What's in the toolchain

Tool	What it does
Rust toolchain	The compiler (rustc) and cargo that build your component from source.
wasm32-wasip2 target	The compile target that produces a portable, sandboxed component.
wash	The wasmCloud command-line tool. Desktop uses it to build your component and run it on the local host as you develop.
wkg	The package tool that fetches the interface definitions your component builds against.
wasm-tools	The WebAssembly component toolkit. An advisory extra Desktop provisions for the componentize-go / WASI-p3 Go path; a Rust or JavaScript build does not need it, so a machine without it still counts as ready.
A C linker	A system C linker, such as the Xcode Command Line Tools on macOS, gcc or clang on Linux, or the MSVC Build Tools on Windows. Even a WebAssembly build compiles a little host code that needs one.

How Desktop installs it

The first time a build needs the toolchain, Desktop shows an Install build toolchain offer. Accept it, and Desktop installs whatever is missing into an app-owned location, so it never changes a Rust setup you manage yourself. You can install, re-check, or remove the toolchain any time from Settings → Toolchain.

wash, wkg, and wasm-tools do not come from a plain download. Desktop pulls them as cosign-signed artifacts from Cosmonic's namespace on the GitHub Container Registry (ghcr.io) and verifies each one against a key built into the app before installing it. If a signature does not verify, the install stops instead of running an unverified tool.

Desktop also keeps the toolchain current for you. When an app update raises the pinned versions, Desktop re-installs the tools it manages in the background. It never touches a tool you brought yourself.

Using your own toolchain

If you already have Rust, wash, or wkg, Desktop uses them. You do not need rustup, and you do not need to match the exact versions Desktop pins. A different working version shows up as a note, not a problem. Desktop only manages the tools it installed.

What satisfies the readiness check

The readiness check passes as long as nothing is a hard failure. It looks at the tools above and blocks only when one is genuinely missing. Most gaps are one click to fix from Settings → Toolchain. The one exception is the C linker, which you install yourself.

A machine is ready to build when it has:

• Rust installed (any version),
• the wasm32-wasip2 target available,
• a C linker present,
• wash installed (any version),
• wkg installed (any version).

A machine is not ready when:

• Rust is missing. Desktop installs it for you.
• The wasm32-wasip2 target was never added to your Rust toolchain. If your Rust is managed by rustup, Desktop adds it; a non-rustup Rust is assumed to already include the target.
• No C linker is found. This is the one thing Desktop cannot install. On macOS, run xcode-select --install. On Linux, install a C toolchain such as build-essential (Debian, Ubuntu) or gcc (Fedora). Then re-check.
• wash or wkg is missing. Desktop installs them from the signed artifacts.

Version differences never block a build. Only a missing tool does.

Restricted networks and offline machines

On a locked-down network, point Rust at an internal mirror by setting RUSTUP_DIST_SERVER and RUSTUP_UPDATE_ROOT, then re-check. The signed wash, wkg, and wasm-tools tools install from ghcr.io, so route that through your registry mirror.

On a machine with no network access, install the toolchain from a signed bundle instead. See Air-gapped install.

Takeaways

• Desktop installs the build toolchain for you the first time you build, and keeps it current.
• wash, wkg, and wasm-tools are cryptographically verified before they install.
• The check blocks only on a genuinely missing tool. Everything but the C linker is one click from Settings → Toolchain.
• Bring your own toolchain if you prefer. Version differences are fine.