Before you install

Before you run an installer, you need three things ready: a supported OS, a broker URL, and a per-device token. This unit covers what each one is, what actually ships in a release, and how Massar verifies the binary before it ever touches disk.

Supported platforms today

Linux and Windows are the two install targets that actually end in a running, self-restarting OS service. macOS is deferred, and ADR-0002 says so plainly: "macOS (launchd) is deferred until there is a customer for it." There is no install/launchd/ unit, and install.sh's own service-installation step only knows how to write a systemd unit - running the script on a Mac clears the OS-detection check and then fails the moment it reaches systemctl daemon-reload, which doesn't exist there.

CI does cross-compile massar-agent for x86_64-apple-darwin and aarch64-apple-darwin on every release, alongside the Linux and Windows targets, so a macOS binary exists in every GitHub Release. That is not the same as macOS being a supported install path - there is no installer or service definition to put that binary into.

Both supported platforms build for two architectures: x86_64 and aarch64 on Linux, x86_64 on Windows.

What a release actually contains

Every tagged release carries, per architecture, the binary plus its supply-chain sidecars:

massar-agent-linux-x86_64          massar-agent-linux-x86_64.sha256
massar-agent-linux-x86_64.cdx.json massar-agent-linux-x86_64.sig / .pem
massar-agent-linux-aarch64         ...same set...
massar-agent-windows-x86_64.exe    ...same set (the .exe is also cosign-signed,
                                   because it is built on the Linux runner;
                                   Authenticode is an additional layer, pending an EV cert)...

Each artifact is also covered by a SLSA build-provenance attestation (actions/attest-build-provenance). The installer scripts themselves are run from the repository - the release job attaches the per-architecture binary and its supply-chain sidecars, and nothing else, so treat install/install.sh and install/install.ps1 in the repo as the installers.

What you need before you start

Both installers need the same two facts about your Diyar-connected account:

• A broker URL - the WebSocket address of the Diyar console broker this device will dial out to, for example wss://diyar.cogitave.com/api/v1/console/agent. The agent only ever makes an outbound connection to this address; it opens no inbound port and needs no VPN.
• A per-device token - the secret issued at enrollment for this specific device. The agent sends it as an Authorization: Bearer header when it dials the broker, and the broker derives the device's identity from it - the token is the credential, not just a lookup key.

Both installers also accept a device identifier (--device-id / -DeviceId), which defaults to the machine's hostname ($(hostname) on Linux, $env:COMPUTERNAME on Windows). It is used for logging only; the broker derives the device's real identity from the token, so the device id plays no part in authentication.

How the binary is verified before it's placed

Every release build goes through the same chain before the installer will write it to disk:

1. SHA-256 checksum - checked unconditionally, on both platforms, whether or not anything else below runs. install.sh downloads the .sha256 sidecar next to the binary and refuses to continue on a mismatch; install.ps1 does the equivalent with Get-FileHash -Algorithm SHA256.
2. Signature. On Linux, a keyless cosign signature:

   cosign verify-blob \
     --certificate-identity-regexp 'https://github.com/cogitave-cloud/.+' \
     --certificate-oidc-issuer https://token.actions.githubusercontent.com \
     --signature "${asset}.sig" --certificate "${asset}.pem" "${asset}"

That checks the artifact was signed by CI's own GitHub Actions OIDC identity - no long-lived signing key sits anywhere. On Windows, the equivalent check is Authenticode: Get-AuthenticodeSignature must report Valid.

1. SBOM + provenance. A CycloneDX SBOM and a SLSA build-provenance attestation (actions/attest-build-provenance) are produced and attached to the release for every artifact, so the binary's build inputs and dependency graph stay inspectable after the fact. Neither installer fetches these at install time - they exist for audit, not as an install-time gate.

Both installers have a development escape hatch - --skip-signature on Linux, -SkipSignatureCheck on Windows - for locally built, unsigned binaries. Both print a loud warning when used, and neither one skips the checksum: that check has no off switch on either platform.

Before you move on

Have these ready, whichever OS you're installing on:

• [ ] A Linux machine with systemd, or a Windows machine - not a Mac.
• [ ] Root (Linux) or an Administrator shell (Windows). Both installers refuse to run without it, because registering a service requires it.
• [ ] The broker URL for your Diyar-connected environment.
• [ ] The per-device token issued at enrollment for this device - tokens are per-device, not shared across a fleet.
• [ ] cosign installed if you want the Linux installer to check the signature, not just the checksum. It's optional: without it, install.sh warns and continues on the verified checksum alone, rather than failing.

Next: install on Linux, or install on Windows, whichever matches the device in front of you.