Build-time branding parameters for MSPs running their own branded service (Phase 1: MSI Manufacturer + service display names; Phase 2: OS-language i18n + Helper titles and windows)

[fabicarvano]

Category: Ideas

Context

Many MSPs want to operate a managed service under their own brand on top of Breeze, while maintaining their own operations, support, and customer relationship. Self-hosting together with selfhost-signing-template already covers an important part of this: the MSP signs official builds with its own identity and distributes updates from its own release source. The documentation currently describes a full rebrand as a fork-based path.

There is, however, a middle ground that does not require maintaining a fork. Some user-visible strings and visual elements are hardcoded in places where the repository already parameterizes similar values.

Today, showing the MSP's identity in package metadata, executable properties, services.msc, and Helper/Viewer visual assets requires modifying source code or assets on every release, which most MSPs are not equipped to maintain.

A second motivation is branding persistence across updates. If branding is expressed as build parameters and build assets rather than manual source patches, the same identity can be reproduced for every new upstream Breeze release.

An MSP could therefore build version N and version N+1 with the same branding profile and use the existing update mechanism between them, without having to re-apply local changes after every release.

The intent is not to introduce per-organization branding at runtime. Branding would belong to the self-hosted distribution/instance, so every organization managed by that instance would receive the same agent identity.

Prior art in the repository

• build-msi.ps1 -Edition already passes ProductName, UpgradeCode, and OtherUpgradeCode to WiX through -d.
• hostpolicy.allowedHosts is already injected through ldflags.
• go-winres simply is already centralized in agent/Makefile and release.yml.

Phase 1 — deliberately small

Add optional build parameters and assets whose defaults reproduce the current behavior exactly.

1. Manufacturer in breeze.wxs, currently hardcoded as "Breeze RMM", and the package Description, exposed through build-msi.ps1.
2. The service DisplayName and Description in breeze.wxs, for both the agent and watchdog.
3. Use the same values as go-winres parameters so the .exe file properties remain consistent with the rest of the branding.
4. Helper and Viewer icons: allow the visual assets used during the build to be optionally replaced with assets supplied by the self-hosted operator, while keeping the current Breeze icons as the default when no customization is provided.

These values and assets would become part of the generated artifact.

This would allow a self-hosted build/signing pipeline to apply the same visual identity whenever a new Breeze version is consumed, instead of modifying the installed agent or maintaining local patches.

The branding configuration could be supplied to the pipeline through build parameters, environment variables, or a configuration file, depending on the approach preferred by the maintainers.

Conceptually:

Breeze upstream
        ↓
MSP branding configuration
        ↓
build
        ↓
artifacts with MSP identity

When no custom branding configuration is provided, the output should remain the current Breeze output.

Phase 2 — only if Phase 1 is welcome

1. OS-language i18n: adopt the project's internationalization pattern for user-facing Helper strings, detecting the operating system language and using English as the fallback.

   This would allow end users to see the Helper in their own language without requiring MSPs to maintain translation patches in source code.

2. Helper titles and windows: make the display name used in Helper titles and windows configurable at build time. Today this includes literals such as "Breeze Helper" and "Welcome to Breeze Helper" in App.tsx and AppShell.tsx. The same build-time identity introduced in Phase 1 could be reused.

Out of scope for the initial phases

Anything that the agent, API, or updater uses as an identifier would remain unchanged in the initial phases:

• internal service names such as BreezeAgent;
• binary names;
• technical asset names;
• installation paths;
• IPC names;
• com.breeze.* labels;
• MSI ProductName;
• the Helper Tauri productName.

Some of these values cannot currently be changed independently without affecting other components.

For example, ProductName participates in agent self-inventory normalization through isBreezeAgentProductName, and the agent locates the Helper using helperDisplayName and its installation path.

For this reason, the initial phases would change only visual identity, metadata, and user-facing text, without changing identifiers that participate in operational behavior.

There would be no API, route, or protocol changes, so existing fleets would remain unaffected.

These identifiers are deliberately excluded from the initial phases because some of them participate directly in upgrade behavior, inventory normalization, Helper discovery, or operating-system lifecycle behavior.

If there is interest later, a deeper distribution identity could be discussed separately.

Development and signing

Branding and platform signing are separate concerns.

Branding parameters and assets should be usable during development even before an MSP has Windows Code Signing or Apple Developer certificates.

This would make it possible to validate the generated identity and, most importantly, test an upgrade flow such as:

MSP-branded N
        ↓
update
        ↓
MSP-branded N+1

before production certificates are available.

For development and test environments, one possible approach would be an explicit opt-in such as:

ALLOW_UNSIGNED_BRANDED_AGENT=true

This option would only allow unsigned platform artifacts during testing of branded builds.

It should not disable:

• release-manifest verification;
• hash validation;
• enrollment controls;
• authentication;
• release-source validation;
• or any other updater trust mechanisms.

Ideally, this option would only be allowed in development/test environments and should fail closed in production.

For example:

ALLOW_UNSIGNED_BRANDED_AGENT=true
NODE_ENV=development
→ allowed for testing

While:

ALLOW_UNSIGNED_BRANDED_AGENT=true
NODE_ENV=production
→ configuration error / service refuses to start

The release-manifest trust chain would remain enforced.

Once certificates are available, the same branding pipeline would produce the same artifacts, while the existing selfhost-signing-template flow would add the platform signatures for Windows and macOS.

Conceptually:

Breeze upstream release
        ↓
MSP branding parameters + assets
        ↓
branded build
        ↓
┌──────────────────────────────┐
│ Development                  │
│                              │
│ unsigned platform artifact   │
│ +                            │
│ signed release manifest      │
└──────────────────────────────┘
        ↓
testing

And later:

Breeze upstream release
        ↓
same MSP branding
        ↓
branded build
        ↓
platform signing
        ↓
signed release manifest
        ↓
MSP release source
        ↓
production

This keeps the branding implementation independent from the immediate availability of production certificates.

Update invariant

For any branding value or asset supported by a phase, the expected invariant should be:

A branded build upgraded to a newer branded build using the same branding configuration must preserve the same user-visible identity.

For example:

Version N

Manufacturer: Example MSP
Service DisplayName: Example MSP Agent
Icon: Example MSP

        ↓ update

Version N+1

Manufacturer: Example MSP
Service DisplayName: Example MSP Agent
Icon: Example MSP

This is one of the main advantages over maintaining local patches.

New upstream releases could simply be rebuilt with the same branding configuration instead of restoring the default Breeze values and requiring manual rework.

Possible later phases

If the initial phases are well received, later phases could gradually expand the distribution identity.

These could include:

• strings in toasts;
• PAM dialogs;
• macOS permission prompts;
• other user-facing text;
• deeper MSI identity;
• binary names;
• installation paths;
• internal service identifiers;
• com.breeze.* labels;
• full agent identity on macOS;
• full agent identity on Linux.

These changes should be handled separately because some of these values participate in runtime behavior, update behavior, or operating-system integration.

The longer-term goal could be to support a more complete cross-platform distribution identity across Windows, macOS, and Linux while preserving the existing API, enrollment, and updater protocols.

Offer

I'm happy to implement Phase 1 as a PR following the project's conventions, including tests that ensure that when no branding parameters or assets are provided, the default behavior and output remain unchanged.

Before I do:

• Is supporting MSP-branded agent builds something you'd want upstream, or would you rather keep it exclusively as a fork use case?
• If supported, are build-time parameters the right mechanism, or would you prefer another approach such as environment variables or a configuration file?
• Would optional replacement of the Helper and Viewer icons as build assets be acceptable within Phase 1?
• For Phase 2, is there an i18n pattern you'd prefer for the Helper and agent?
• Are there strings, icons, or other identity elements you'd want excluded for licensing or trademark reasons?
• Would a development-only mechanism for testing branded but unsigned platform artifacts be acceptable, provided manifest/hash verification remains enforced and production fails closed?
• If the initial visual-branding phases are successful, would you be open to discussing deeper distribution identity separately for ProductName, binary names, installation paths, and service/bundle identifiers?

[ToddHebebrand]

Thanks @fabicarvano. The identifiers you chose to leave alone are the right ones, and I'd take Phase 1 as a spec, with a few corrections first.

Verified: Manufacturer="Breeze RMM" and the package description are hardcoded (agent/installer/breeze.wxs:58,65), as are the service display names (breeze.wxs:449-451,484-486). build-msi.ps1 -Edition already passes WiX variables, and allowedHosts already goes in through ldflags (agent/scripts/build-edition.sh), so there's precedent for both mechanisms.

Corrections:

• Display names also live in Go. agent service install registers "Breeze RMM Agent" (agent/internal/agentapp/service_cmd_windows.go:83), while the MSI says "Breeze Agent". The watchdog has its own copy (breeze-watchdog/service_cmd_windows.go:64). Both paths need the parameter, and they should agree with each other.
• The signing template can't sign a branded build. selfhost-signing-template downloads the official unsigned outputs and checks each SHA-256 against the official manifest and sourceCommit before signing. A rebuilt binary fails that check by design. A branded build needs the operator's own build-and-sign pipeline and manifest key.
• ALLOW_UNSIGNED_BRANDED_AGENT isn't needed. The API already serves unsigned self-host assets after the manifest verifies (releaseArtifactManifest.ts), with a warning.

Constraints the spec should state:

1. Only display strings change. BreezeAgent/BreezeWatchdog, event-log sources, UpgradeCode, ProductName and com.breeze.* stay fixed, because MSI upgrade, the updater and self-inventory key on them.
2. A branded fleet must update from the operator's own release source (BINARY_GITHUB_REPOSITORY plus their manifest key). Pointed at official releases, the next auto-update silently restores the Breeze branding.
3. Upstream carries the parameters with defaults that produce byte-identical official output, and CI proves that. Upstream doesn't ship or run branded release infrastructure.
4. Phase 2 Helper titles: we already decided on Branding Breeze Dektop agent #6365 to white-label the Helper's welcome text and colours at runtime through the Helper config policy (partner default, org override). Helper titles should ride that, not a second build-time mechanism. Icons were deferred there to their own spec, so leave them out of Phase 1.

With those folded in, a Phase 1 spec PR is welcome.

[fabicarvano]

Hi Todd — before continuing the Phase 2 implementation, I did a fresh review comparing the approved #8277 spec with the current state of main.

Phase 1 (#7841 / #8061) still looks valid and I don't think it needs to change. Likewise, native icons/resources remain outside Phase 2 and can stay as a separate future piece of work, as already defined.

The question is specifically about how we should continue Phase 2 — Agent localization + Helper runtime branding.

The product decisions in #8277 still look valid, including OD1–OD5, but the technical baseline has changed substantially since the spec was approved. main now includes, among other changes, devicePolicySet, heartbeat retain-state, Identity Sync, removal of showTrayIcon, Caller Verification, Endpoint Messaging, Tauri message-window isolation, and the migration to serde_norway.

There is also an older uncommitted Phase 2 implementation, but it is currently 282 commits behind main, so I don't think it would be safe to simply continue from it or attempt a direct rebase.

Before preparing the updated Phase 2 development plan, which approach would you prefer?

1. Keep docs(spec): Agent localization and Helper runtime branding Phase 2 #8277 as the historically approved Phase 2 design, mark it as superseded/non-dispatchable for implementation, and create a replacement Phase 2 spec reconciled with the current main architecture; or
2. Keep docs(spec): Agent localization and Helper runtime branding Phase 2 #8277 as the active Phase 2 spec and create only a new implementation plan/addendum describing how the already-approved decisions map onto the current architecture.

My preference would be option 1, because it preserves all of the previously approved decisions without changing Phase 1 or pulling the future native icons/resources work into scope, while making it explicit that some of the older implementation assumptions should no longer be dispatched directly.

I would keep #6365 closed as completed and use the new document only to organize the continuation of Phase 2.

[ToddHebebrand]

Option 2, with one adjustment. #8277 stays the approved Phase 2 spec; OD1–OD5 are product decisions and nothing on main changes them. What moved is the implementation surface, and that belongs in a plan, not a second spec. Write one plan under docs/superpowers/plans/ that maps each decision onto current main (devicePolicySet, retain-state, Identity Sync, no showTrayIcon, Tauri message-window isolation, serde_norway), with a short "deltas since the spec" section at the top so a reader of #8277 knows what changed. Drop the old branch rather than rebase it; 282 commits is a rewrite either way. I'll register the lifecycle issue once the plan is in.

To close the loop on §13 of the spec, so the plan can start from recorded decisions:

Owner decision (2026-10-15):
OD1 approved — Helper locale from the user's session, kept in the per-session helper_config.yaml.
OD2 approved — read the display name from Properties[0] and map through CanonicalServiceName; include in Phase 2.
OD3 approved — last-known branding persists in the per-session helper_config.yaml, never only in memory.
OD4 approved — constrained semantic colour model, no per-component CSS.
OD5 approved — validate colours and enforce contrast on branded surfaces.

Icons and native assets stay deferred, as you have it.

[fabicarvano]

Thanks Todd. I followed Option 2 and the adjustment you outlined.

What was requested

• Keep docs(spec): Agent localization and Helper runtime branding Phase 2 #8277 as the approved Phase 2 spec; do not create a replacement spec.
• Treat OD1–OD5 as settled product decisions.
• Create one implementation plan under docs/superpowers/plans/ that maps those decisions onto current main.
• Start the plan with a short “Deltas since the spec” section covering the implementation-surface changes now present on main: devicePolicySet, retain-state, Identity Sync, removal of showTrayIcon, Tauri message-* isolation, and serde_norway.
• Drop the old Phase 2 branch instead of rebasing it.
• Keep icons/native assets deferred.

What was done

• Dropped the old docs(spec): Agent localization and Helper runtime branding Phase 2 #8277 implementation branch rather than rebasing it.
• Started from the current upstream/main and created a clean documentation branch.
• Added a single implementation plan at:
  docs/superpowers/plans/agent/2026-10-15-agent-localization-helper-runtime-branding.md
• The plan begins with “Deltas since the spec” and explicitly maps the approved design to the current implementations of devicePolicySet, heartbeat retain-state, Identity Sync, the absence of showTrayIcon, Tauri message-* capability isolation, and serde_norway.
• OD1–OD5 are carried forward as approved decisions rather than reopened as design questions.
• The plan keeps Helper branding in the existing runtime Configuration Policy path and does not introduce a second build-time branding mechanism.
• Icons/native assets remain out of scope.
• The plan also preserves the current security and compatibility boundaries: no new branding table/migration/control endpoint, no technical identifier renames, and no widening of the message-* capability.
• Current-main additions such as Caller Verification and Endpoint Messaging are handled only where they affect the Phase 2 implementation surface; they do not change the approved product decisions.

The plan is committed as fba1a002c (docs(agent): plan Phase 2 localization and runtime branding) on branch docs/helper-branding-phase2-current-main and is ready for review.

[ToddHebebrand]

@fabicarvano Thanks, that's the shape I asked for. One step left: the plan is only on your fork branch, so there's nothing to review against yet.

Next: open a PR from docs/helper-branding-phase2-current-main (commit fba1a002c) against main, with Refs #8277 in the body, so review threads can sit on the plan's lines. I'll review it there and register the lifecycle issue once it lands.

Status: waiting on the PR.

[fabicarvano]

Thanks Todd. The PR is now open against main as #8861, with Refs #8277 in the body, as requested:

#8861

The plan is ready for line-by-line review there. I’ll keep any follow-up changes scoped to the approved #8277 decisions and the current-main implementation mapping.