{
  "uid": "cogitave.learn.install-the-massar-agent.before-you-install",
  "kind": "moduleUnit",
  "href": "/modules/install-the-massar-agent/before-you-install/",
  "title": "Before you install",
  "summary": "",
  "type": null,
  "products": [],
  "roles": [],
  "levels": [],
  "subjects": [],
  "headings": [
    "Supported platforms today",
    "What a release actually contains",
    "What you need before you start",
    "How the binary is verified before it's placed",
    "Before you move on"
  ],
  "source": "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.\n\n> [!NOTE]\n> Installing the agent grants Cogitave operators audited remote-console access to this device, once an authorized operator opens a session through Diyar. Both installers state this consent plainly before they finish running - do not install unless you intend to authorize that access.\n\n## Supported platforms today\n\n| Platform | Installer | Service model | Status |\n| --- | --- | --- | --- |\n| Linux | `install/install.sh` | systemd unit | Shipped |\n| Windows | `install/install.ps1` | Windows service | Shipped |\n| macOS | - | launchd (not written) | Deferred |\n\nLinux 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.\n\nCI 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.\n\nBoth supported platforms build for two architectures: `x86_64` and `aarch64` on Linux, `x86_64` on Windows.\n\n## What a release actually contains\n\nEvery tagged release carries, per architecture, the binary plus its supply-chain sidecars:\n\n```text\nmassar-agent-linux-x86_64          massar-agent-linux-x86_64.sha256\nmassar-agent-linux-x86_64.cdx.json massar-agent-linux-x86_64.sig / .pem\nmassar-agent-linux-aarch64         ...same set...\nmassar-agent-windows-x86_64.exe    ...same set (the .exe is also cosign-signed,\n                                   because it is built on the Linux runner;\n                                   Authenticode is an additional layer, pending an EV cert)...\n```\n\nEach 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.\n\n## What you need before you start\n\nBoth installers need the same two facts about your Diyar-connected account:\n\n- **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.\n- **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.\n\n> [!IMPORTANT]\n> Enrollment today is a pre-issued static token you obtain out of band and hand to the installer with `--token` / `-Token`. A guided graphical setup wizard and a device-code/QR pairing flow exist as designs in Massar's frontend, but the backend commands behind them are not implemented - the CLI installer with a static token is the path that actually enrolls a device today.\n\nBoth 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.\n\n## How the binary is verified before it's placed\n\nEvery release build goes through the same chain before the installer will write it to disk:\n\n1. **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`.\n2. **Signature.** On Linux, a **keyless cosign** signature:\n\n   ```bash\n   cosign verify-blob \\\n     --certificate-identity-regexp 'https://github.com/cogitave-cloud/.+' \\\n     --certificate-oidc-issuer https://token.actions.githubusercontent.com \\\n     --signature \"${asset}.sig\" --certificate \"${asset}.pem\" \"${asset}\"\n   ```\n\n   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`.\n3. **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.\n\nBoth 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.\n\n> [!WARNING]\n> Windows Authenticode signing needs an EV code-signing certificate, and ADR-0002 records that one is not provisioned yet: \"until an EV cert is provisioned, `install.ps1 -SkipSignatureCheck` exists for dev/test only ... This is the one open supply-chain gap, tracked for cutover.\" Until that cutover, the release pipeline warns and ships an unsigned Windows binary rather than silently skipping the step - check the release notes for the current state before you rely on `install.ps1` without `-SkipSignatureCheck`.\n\n## Before you move on\n\nHave these ready, whichever OS you're installing on:\n\n- [ ] A Linux machine with systemd, or a Windows machine - not a Mac.\n- [ ] Root (Linux) or an Administrator shell (Windows). Both installers refuse to run without it, because registering a service requires it.\n- [ ] The broker URL for your Diyar-connected environment.\n- [ ] The per-device token issued at enrollment for *this* device - tokens are per-device, not shared across a fleet.\n- [ ] `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.\n\nNext: install on Linux, or install on Windows, whichever matches the device in front of you.\n",
  "partOf": "cogitave.learn.install-the-massar-agent",
  "durationInMinutes": 5,
  "quiz": null
}