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:
- 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.
- 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 signedBellonaRemoteHost.pkgthe 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.mdfor 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 toAllow 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:
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 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_IDwith the real Apple Team ID; the literal must match thecodesign --display --requirementsoutput 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
AppleEventsentry 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:
<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:
- 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. - 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. - Install. MDM
InstallApplication, orinstaller -pkg BellonaRemoteHost.pkg -target /, or a Munki/Jamf repo. The LaunchAgent registers the host (macos-packaging-plan.ts). - 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— aRemoteHostSignedUpdateManifest(payload + Ed25519 signature), produced by the release job exactly as for the cloud channel.- the artifacts referenced by
manifest.payload.artifacts[].url, each with itssha256recorded 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:
// 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:
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, soaction: '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.