Eve library

MDM-Friendly and Offline / Private-Studio Install & Update (180.C.26.13)

Guide

Revision 1

On this page

Status: 180.C.26.13 implementation.

This document specifies two deployment paths for the Bellona Remote Host that do not assume a public app store or a cloud update endpoint:

  1. MDM-managed install — pre-grant the macOS TCC permissions via a Privacy Preferences Policy Control (PPPC) configuration profile, and pre-configure the gateway connection via a managed defaults profile, so a fleet of studio Macs onboards with zero per-machine clicking.
  2. Offline / private-studio install + no-cloud updates — install from a locally-hosted signed package and update from a local update repository using the existing signed update-manifest contract, with no call to any Bellona or third-party cloud service.

It builds on:

  • macos-hardened-runtime.md — the entitlements, not-sandboxed rationale, and the TCC services the PPPC profile pre-grants.
  • macos-packaging-and-notarization-plan.md — the signed BellonaRemoteHost.pkg the MDM/offline install deploys.
  • The signed update-manifest contract in apps/bellona/remote-host/src/update-manifest.ts (RemoteHostSignedUpdateManifest, verifyRemoteHostSignedUpdateManifest, RemoteHostTrustedUpdateSigningKey, 180.C.16.03 / 26.07).
  • The Tailscale/WireGuard private-network mode in tailscale-wireguard-private-network.md for the LAN/VPN the offline gateway lives on.

The host runtime identifiers these profiles target are the real ones: bundle id com.oshun.bellona.remote-host, LaunchAgent label com.oshun.bellona.remote-host (apps/bellona/remote-host/src/macos-packaging-plan.ts), and the config env keys parsed in apps/bellona/remote-host/src/config.ts (BELLONA_REMOTE_HOST_GATEWAY_URL, BELLONA_REMOTE_HOST_HEALTH_HOST/PORT, BELLONA_REMOTE_HOST_IDENTITY_FILE).

1. Why MDM (and why not the App Store)#

The host ships not sandboxed (see macos-hardened-runtime.md §3), which makes it ineligible for the Mac App Store and means TCC grants would otherwise require a human to click through every prompt on every machine. In a studio with many identical Macs, that is both error-prone and unauditable. MDM solves both:

  • A PPPC configuration profile delivered by MDM can pre-grant the Accessibility and Apple Events (Automation) TCC services for a known, code-signed app — no per-machine clicking, and the grant is centrally auditable.
  • Screen Recording is the deliberate exception. Apple does not allow MDM to silently pre-grant kTCCServiceScreenCapture; a PPPC profile can only set it to Allow Standard User to Set System Service (the user still confirms once). The host's first-run flow (diagnoseMissingPermissions, 180.C.26.03) surfaces exactly that one remaining grant with its precise remediation string, so the managed-but-one-click reality is honest, not hidden.

2. PPPC configuration profile (TCC pre-grant)#

A configuration profile is a .mobileconfig plist containing one or more payloads. For TCC pre-grant we use a com.apple.TCC.configuration-profile-policy payload. The app is identified by its code requirement (a designated requirement string), which binds the grant to Bellona's exact signing identity and bundle id — a different binary cannot inherit the grant.

Generate the code requirement from the signed app on a build machine:

bash
codesign --display --requirements - \
  "/Applications/Bellona Remote Host.app" 2>&1 | sed -n 's/^designated => //p'
# => identifier "com.oshun.bellona.remote-host" and anchor apple generic and
#    certificate leaf[subject.OU] = "<BELLONA_TEAM_ID>"

Then author the profile (real, valid PPPC structure):

xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTD/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>PayloadType</key>
  <string>Configuration</string>
  <key>PayloadVersion</key>
  <integer>1</integer>
  <key>PayloadIdentifier</key>
  <string>com.oshun.bellona.remote-host.pppc</string>
  <key>PayloadUUID</key>
  <string>0F1E2D3C-4B5A-6978-8796-A5B4C3D2E1F0</string>
  <key>PayloadDisplayName</key>
  <string>Bellona Remote Host — Privacy Preferences</string>
  <key>PayloadScope</key>
  <string>System</string>
  <key>PayloadContent</key>
  <array>
    <dict>
      <key>PayloadType</key>
      <string>com.apple.TCC.configuration-profile-policy</string>
      <key>PayloadIdentifier</key>
      <string>com.oshun.bellona.remote-host.pppc.policy</string>
      <key>PayloadUUID</key>
      <string>1A2B3C4D-5E6F-7081-9203-B4C5D6E7F809</string>
      <key>PayloadVersion</key>
      <integer>1</integer>
      <key>Services</key>
      <dict>
        <!-- Accessibility: pre-granted (synthetic input via AXIsProcessTrusted). -->
        <key>Accessibility</key>
        <array>
          <dict>
            <key>Identifier</key>
            <string>com.oshun.bellona.remote-host</string>
            <key>IdentifierType</key>
            <string>bundleID</string>
            <key>CodeRequirement</key>
            <string>identifier "com.oshun.bellona.remote-host" and anchor apple generic and certificate leaf[subject.OU] = "BELLONA_TEAM_ID"</string>
            <key>Allowed</key>
            <true/>
          </dict>
        </array>
        <!-- Apple Events: pre-grant the host -> Blender/Unreal automation pairs.
             AEReceiverIdentifier names the controlled app. -->
        <key>AppleEvents</key>
        <array>
          <dict>
            <key>Identifier</key>
            <string>com.oshun.bellona.remote-host</string>
            <key>IdentifierType</key>
            <string>bundleID</string>
            <key>CodeRequirement</key>
            <string>identifier "com.oshun.bellona.remote-host" and anchor apple generic and certificate leaf[subject.OU] = "BELLONA_TEAM_ID"</string>
            <key>AEReceiverIdentifier</key>
            <string>org.blenderfoundation.blender</string>
            <key>AEReceiverIdentifierType</key>
            <string>bundleID</string>
            <key>AEReceiverCodeRequirement</key>
            <string>identifier "org.blenderfoundation.blender" and anchor apple generic</string>
            <key>Allowed</key>
            <true/>
          </dict>
        </array>
        <!-- Screen Recording CANNOT be silently pre-granted by MDM. The most a
             profile may do is permit a standard user to enable it themselves;
             the user confirms once and the 26.03 onboarding flow surfaces it. -->
        <key>ScreenCapture</key>
        <array>
          <dict>
            <key>Identifier</key>
            <string>com.oshun.bellona.remote-host</string>
            <key>IdentifierType</key>
            <string>bundleID</string>
            <key>CodeRequirement</key>
            <string>identifier "com.oshun.bellona.remote-host" and anchor apple generic and certificate leaf[subject.OU] = "BELLONA_TEAM_ID"</string>
            <key>Authorization</key>
            <string>AllowStandardUserToSetSystemService</string>
          </dict>
        </array>
      </dict>
    </dict>
  </array>
</dict>
</plist>

Notes:

  • Replace BELLONA_TEAM_ID with the real Apple Team ID; the literal must match the codesign --display --requirements output for the distributed app.
  • TCC profiles are only honored when delivered by an MDM-supervised device (user-approved MDM enrollment). A manually-installed PPPC profile is ignored by macOS — this is an Apple constraint, not a Bellona one.
  • Add an AppleEvents entry per controlled DCC (Unreal: com.epicgames.UnrealEditor).

3. Pre-configuring the gateway (managed defaults)#

The host reads its gateway URL and ports from the environment / config (loadRemoteHostConfig, apps/bellona/remote-host/src/config.ts). For a LaunchAgent-run host, the durable way to set those on managed machines is a managed app-defaults profile (com.apple.ManagedClient.preferences) writing the host's preference domain (com.oshun.bellona.remote-host), which the LaunchAgent surfaces to the process environment at launch:

xml
<dict>
  <key>PayloadType</key>
  <string>com.apple.ManagedClient.preferences</string>
  <key>PayloadIdentifier</key>
  <string>com.oshun.bellona.remote-host.managed-prefs</string>
  <key>PayloadUUID</key>
  <string>2B3C4D5E-6F70-8192-A3B4-C5D6E7F80912</string>
  <key>PayloadVersion</key>
  <integer>1</integer>
  <key>PayloadContent</key>
  <dict>
    <key>com.oshun.bellona.remote-host</key>
    <dict>
      <key>Forced</key>
      <array>
        <dict>
          <key>mcx_preference_settings</key>
          <dict>
            <!-- The private-studio gateway on the LAN / Tailscale tailnet. -->
            <key>BELLONA_REMOTE_HOST_GATEWAY_URL</key>
            <string>wss://gateway.studio.lan:4070/v1/hosts/connect</string>
            <key>BELLONA_REMOTE_HOST_HEALTH_HOST</key>
            <string>127.0.0.1</string>
            <key>BELLONA_REMOTE_HOST_HEALTH_PORT</key>
            <integer>4071</integer>
          </dict>
        </dict>
      </array>
    </dict>
  </dict>
</dict>

The LaunchAgent plist (packaging/macos/launch-agents/com.oshun.bellona.remote-host.plist) reads these managed values into EnvironmentVariables (or the host reads the managed domain directly) so a managed Mac connects to the studio gateway with no local edits. The gateway's TLS pin is handled by gateway-pinning.ts (apps/bellona/remote-host/src/gateway-pinning.ts); for a self-signed studio CA, ship the CA via a separate com.apple.security.root certificate payload in the same profile.

4. Offline / private-studio install path#

For an air-gapped or no-internet studio:

  1. Stage the signed package once, online. On a build machine with internet, build, sign, notarize, and staple BellonaRemoteHost.pkg (see the packaging plan). Stapling is what lets the package install on offline machines — Gatekeeper validates the stapled ticket without contacting Apple. An un-stapled package will fail Gatekeeper on a machine that cannot reach Apple.
  2. Distribute over the LAN. Host the stapled .pkg (and the profiles above) on an internal share / MDM distribution point. There is no Bellona cloud in this path.
  3. Install. MDM InstallApplication, or installer -pkg BellonaRemoteHost.pkg -target /, or a Munki/Jamf repo. The LaunchAgent registers the host (macos-packaging-plan.ts).
  4. Verify locally. Run the host once; createRemoteHostMacPermissionDetector().detect()
    • diagnoseMissingPermissions (180.C.26.03) reports any remaining grant (the one Screen Recording confirmation §1) with an exact remediation string.

The host's transport is loopback + the studio gateway only; with the managed gateway URL pointing at a LAN/Tailscale address, the host never needs egress to the public internet to operate.

5. No-cloud update option#

Updates use the same signed update-manifest contract as the cloud path — only the source changes from a cloud URL to a local update repository. There is no separate, weaker offline code path; the Ed25519 signature, channel, compatibility, and revocation gates in verifyRemoteHostSignedUpdateManifest (apps/bellona/remote-host/src/update-manifest.ts) all still apply.

5.1 Stand up a local update repository#

A local update repo is a directory served over HTTPS on the LAN (or a Tailscale host) containing:

  • manifest.json — a RemoteHostSignedUpdateManifest (payload + Ed25519 signature), produced by the release job exactly as for the cloud channel.
  • the artifacts referenced by manifest.payload.artifacts[].url, each with its sha256 recorded in the manifest.

Point the artifact URLs at the local repo. Because each RemoteHostUpdateArtifact carries its own url + sha256, the URL can be a LAN HTTPS path (or a file:// path for a mounted share) without changing verification — the integrity check is the hash + signature, not the origin:

jsonc
// manifest.json (RemoteHostSignedUpdateManifest), local-repo flavour
{
  "payload": {
    "schemaVersion": 1,
    "channel": "internal",
    "version": "0.2.0",
    "artifacts": [
      {
        "artifactId": "remote-host-installer-pkg",
        "kind": "remote-host-installer-pkg",
        "platform": "macos",
        "arch": "universal",
        "url": "https://updates.studio.lan/bellona/0.2.0/BellonaRemoteHost.pkg",
        "sha256": "<sha256-of-the-stapled-pkg>",
        "sizeBytes": 0,
        "signing": ["developer-id-installer", "notarized", "stapled"]
      }
    ]
    /* ...rollback, adapterCompatibility, releaseGate per the payload type... */
  },
  "signature": {
    "algorithm": "ed25519",
    "keyId": "bellona-internal-2026",
    "canonicalization": "json-stable-v1",
    "signatureBase64": "<base64-ed25519-signature>"
  }
}

5.2 The host verifies the local manifest exactly like a cloud one#

The studio configures the host's trusted signing keys (RemoteHostTrustedUpdateSigningKey[]) and the local repo URL, then verification is the unchanged call:

ts
import {
  verifyRemoteHostSignedUpdateManifest,
  type RemoteHostSignedUpdateManifest,
  type RemoteHostTrustedUpdateSigningKey,
  type RemoteHostUpdateVerificationState,
} from '@bellona/remote-host'; // apps/bellona/remote-host/src/update-manifest.ts

const result = verifyRemoteHostSignedUpdateManifest(
  manifestFetchedFromLocalRepo, // RemoteHostSignedUpdateManifest
  trustedKeys,                  // the studio's pinned internal signing keys
  verificationState,            // current version/channel/adapters/now/revocations
);
// result.ok === false unless the Ed25519 signature, channel eligibility,
// minimum-version, adapter compatibility, AND revocation checks all pass —
// identical guarantees to the cloud channel.

Because the manifest is signed by a studio-held internal key and the host pins that key, a malicious file dropped on the LAN repo cannot pass verification, and a revoked-but-signed build is still refused (isUpdateRevoked / RemoteHostUpdateVerificationState.revocations).

5.3 No-cloud guarantees#

  • No telemetry or update call leaves the studio network. The manifest and artifacts are fetched from the LAN repo; verification is purely local.
  • Integrity is origin-independent. The hash + Ed25519 signature gate the install, so a LAN/file:///mounted-share source is as safe as a cloud CDN.
  • Rollback works offline. The manifest's rollback (RemoteHostUpdateRollbackPlan) and the previous staged artifact stay in the local repo, so action: 'rollback' needs no internet either.

6. Two-logical-units note (180.C.26.17)#

Per stage-26-logical-units.md: the gateway pre-configuration and the first-run grant surfacing in this doc belong to 26.A; the signed-update delivery (local repo + verifyRemoteHostSignedUpdateManifest) and the package distribution belong to 26.B. MDM/offline install spans both — it configures the 26.A app shell and delivers the 26.B signed artifacts.