Skip to main content
Barndoor Bridge is in Early Access. These pages are not listed in the navigation. Overview: /how-tos/barndoor-bridge/overview · Using Bridge: /how-tos/barndoor-bridge/using-bridge · Install with MDM: /how-tos/barndoor-bridge/install-with-mdm · Client settings: /how-tos/barndoor-bridge/client-settings · Publish a local MCP: /how-tos/barndoor-bridge/publish-local-mcp · Release notes: /how-tos/barndoor-bridge/release-notes
This page describes stable release v0.1.218, which needs macOS 15 Sequoia or later. Upgrading an existing fleet? Read Before you roll it out first, and paste the current install-latest.sh into your MDM.

What you deploy

The fleet install is a signed .pkg plus a handful of configuration profiles, pushed by Iru or Rippling. Any Apple MDM that accepts custom .mobileconfig profiles and a recurring root script works the same way. Everything you need is in the MDM kit, a small tarball with the profile templates, the render script, and the updater script: The updater script on its own is at https://downloads.barndoor.ai/barndoor-gui/mdm/install-latest.sh. You do not upload a new .pkg for every release. The updater script pulls the current stable package from Barndoor’s download host. The .pkg also installs a LaunchAgent (ai.barndoor.gui) that starts the app at login without stealing focus. Post-install bootstraps that agent for the current console user so the menu-bar icon appears without waiting for the next login.

What lands on the Mac

Prerequisites

  • Macs on macOS 15 Sequoia or later. Barndoor.app does not open on earlier releases.
  • Macs enrolled in Iru or Rippling. Supervision (Apple Business Manager with Automated Device Enrollment) is required for the login-item lock and the silent Full Disk Access grant. On a user-enrolled or BYOD Mac the package and managed settings still work, but the user sees a permission prompt on first workspace access and can turn the login item off.
  • Barndoor’s Apple Team ID, 547SWHX99F. This is Barndoor’s Developer ID team, not your own company’s, because the profiles use it to identify Barndoor’s signed app to macOS. You do not need an Apple Developer account. The updater separately verifies the installer identity Developer ID Installer: Barndoor AI, Inc.
  • Claude Desktop 2.2553.0 or later, and the ChatGPT desktop app if developers use Codex Desktop, on the same Macs from your existing software catalog. Bridge launches them; it does not install them, and it refuses an older Claude Desktop.
  • (Optional, for provider lockdown) a NextDNS or Cloudflare Gateway resolver, or a secure web gateway that already blocks LLM provider APIs.

1. Render the profiles

Unpack the MDM kit on a Mac. The profile templates in profiles/ contain placeholders for your organization’s values. Render them once and keep the output. Rendering again mints new profile UUIDs, and MDM treats those as new profiles.
Typical output:
  • managed-prefs.mobileconfig
  • login-item.mobileconfig
  • pppc.mobileconfig
  • dns-inference-block.mobileconfig, only with --dns
  • codex-desktop-updates.mobileconfig, only with --hold-codex-desktop-updates
  • claude-desktop.mobileconfig, only with --claude-desktop-managed
--backend-url is the Barndoor API base for your environment (production is https://app.barndoor.ai/api). Only --team-id is required. --org-hint is your organization slug and renders as an empty string when omitted, which the CLI treats as unset. Before you install says where to find it.
Do not pass --default-profile. It pinned a launch profile, and launch profiles have been replaced by client settings, which apply to every launch. Bridge ignores the default_profile key and prints a notice on every barndoor run while it is present, so when you next re-render, leave the flag out and the key is dropped. render.sh refuses a client name such as claude or codex as the value.
Do not re-render over a profile that is already deployed without checking what changes. A fresh render writes every managed setting, including update_channel set to stable, dns_control_source set to none, and claude_desktop_managed set to false. Deployed in place of an older profile that lacked those keys, it can move an edge pilot group back to stable or turn provider lockdown off. Compare the two files first, and see Replacing a profile for how to swap it.

Provider lockdown (optional)

Provider lockdown is one switch, off by default. With it on:
  • Direct LLM provider APIs are blocked on the Mac, so traffic cannot skip the gateway: api.anthropic.com, api.openai.com, Gemini, Vertex AI, Bedrock runtime, Azure OpenAI and AI Services, Mistral, Groq, Together, OpenRouter, DeepSeek, xAI, Cohere, Perplexity, Hugging Face inference, Fireworks, Cerebras, and Replicate, plus the public DNS-over-HTTPS resolvers that would get around the block. The providers’ sign-in hosts (claude.ai, console.anthropic.com, auth.openai.com), Barndoor’s hosts, and your gateway stay reachable.
  • Claude refuses to run outside Barndoor. A claude started from a terminal has every prompt refused with a message pointing at barndoor run claude and the Bridge app, and Claude Desktop opened directly shows a profile that cannot reach Claude. Developers cannot use a personal Claude subscription directly on these Macs.
Codex is not part of the switch: the Codex policy is installed on every managed Mac, lockdown or not. Pick one of two ways to block the provider APIs: Either way, the next run of install-latest.sh on each Mac installs the Claude policy (Claude Code managed settings plus a fallback Claude Desktop profile), and keeps it current on every run after that. Re-render without lockdown (dns_control_source is none) and the next run removes it, along with nothing it did not write. A managed settings profile rendered before provider lockdown existed has no dns_control_source at all. The updater then leaves the Claude policy as it is and says so in its output:
If the Mac already has a /Library/Application Support/ClaudeCode/managed-settings.json of your own, the updater does not overwrite it and reports a failure instead. Merge the output of barndoor claude-policy print into your file.
Lockdown does not stop the providers’ websites, such as chatgpt.com and gemini.google.com, in a browser: DNS cannot tell those apart from the sign-in flows Bridge needs.

Codex policy

The Codex policy is Codex’s system requirements file, /etc/codex/requirements.toml. install-latest.sh installs it on every Mac it runs on, whether or not provider lockdown is on, and keeps it current on every run. Since v0.1.218 this is the default; earlier updater scripts installed it only with lockdown on. With the policy on a Mac:
  • Launch Codex Desktop appears in Bridge when Codex Desktop is installed at /Applications/ChatGPT.app. Without the policy, Bridge shows no button.
  • codex in a terminal, and Codex in the ChatGPT app opened directly, refuse to run outside Barndoor. barndoor run codex and Launch Codex Desktop work. Tell people before you roll it out.
Things to know:
  • It replaces a requirements file of your own on every run. If your fleet ships its own Codex requirements, opt out.
  • Don’t ship a copy of the file through your MDM. A Bridge release can change the policy, and launches refuse an out-of-date one. Let the updater install it.
  • The behaviour is in the script. MDM consoles run the script text you pasted, so a fleet gets the always-on Codex policy only after you paste the current install-latest.sh.
  • If one policy fails to install, the updater still installs the others, then exits non-zero so your MDM reports it.
To opt a fleet out, run the updater with --no-codex-desktop-policy, or set BARNDOOR_MDM_CODEX_DESKTOP_POLICY=0 in its environment. That removes only a file Barndoor wrote, and Launch Codex Desktop is no longer offered. On a Mac without the policy, barndoor codex-desktop-policy verify says what is missing:
Terminal output. barndoor codex-desktop-policy builds: Codex Desktop 26.903.71938 (build 8576), bundled codex-cli 0.153.4, Status: supported, and the list of supported bundled CLIs. barndoor codex-desktop-policy verify: Error: the Codex requirements file /etc/codex/requirements.toml is missing; your organization's device management installs it (the Barndoor MDM kit installs it on every managed device), and an administrator can install it by hand with barndoor codex-desktop-policy install with sudo
On a single Mac outside MDM, install it with sudo barndoor codex-desktop-policy install, and remove it with sudo barndoor codex-desktop-policy remove. Removal deletes only a file Barndoor wrote.

Hold Codex Desktop updates (optional)

Codex Desktop updates itself, on each Mac independently. Barndoor supports the Codex Desktop versions it has reviewed, normally the current one and a few before it, and adds new ones in later Bridge releases. Until then, a Mac that updated early fails to launch with “newer than this Barndoor supports”. To hold Codex Desktop at the version you deploy, render with --hold-codex-desktop-updates and deploy codex-desktop-updates.mobileconfig like the other profiles. It turns off Codex Desktop’s automatic update checks and downloads. It works with or without provider lockdown.
  • It must be a managed profile. Codex Desktop rewrites its own update settings at launch, so defaults write does not stick.
  • Check for Updates… in the ChatGPT menu still works. Where people do not have administrator rights and the app is owned by root, macOS asks for an administrator password.
  • Homebrew can still replace the app. brew upgrade --greedy, or brew upgrade --cask chatgpt, installs a new ChatGPT.app regardless. Leave chatgpt out of any greedy upgrade on these Macs.
To release a new version, install it on one test Mac and run barndoor codex-desktop-policy builds. Once it reports Status: supported, deploy that version to the fleet. The command exits non-zero only when a launch would refuse the installed version, so it also works as an MDM audit script. To stop holding updates, remove the profile.

Claude Desktop managed profile (optional)

With the Claude policy, Claude Desktop opened directly gets a fallback profile that cannot reach a model. That profile is a file people can edit or delete; the next updater run puts it back. To make it tamper-proof, deploy Claude Desktop’s Barndoor configuration as a managed profile instead. People then cannot change where Claude Desktop sends requests, which MCP servers it has, or switch it to a personal claude.ai account.
  1. Render with --claude-desktop-managed <capabilities.json>, a file with the capabilities Claude Desktop gets on every Mac in the group. render.sh uses the Barndoor CLI installed on the rendering Mac to produce claude-desktop.mobileconfig, and sets claude_desktop_managed in the managed settings profile.
  2. Deploy both claude-desktop.mobileconfig and the new managed settings profile to the same devices, at device scope.
  3. On a Mac, barndoor doctor reports Claude Desktop managed profile: ok.
Things to know:
  • Deploy and remove the two profiles together. If a Mac has only one of them, Bridge refuses to launch Claude Desktop, and barndoor doctor reports a DISAGREEMENT: or missing line.
  • The profile is a ceiling. If a person’s client settings allow more than the profile, the launch runs limited by the profile. If their client settings are stricter than the profile, the launch is refused, because Claude Desktop’s chat and Cowork cannot be narrowed per session.
  • One governed Claude Desktop per Mac, on a fixed local port (47566 unless you render with --claude-desktop-port).
  • Claude Desktop applies a changed profile when it relaunches, which it forces within 24 hours.
  • It has not yet been tested across a full range of real devices. Pilot it on a small group first.
The kit’s README has the full flag list, including the allowed folders and network hosts for Cowork.

Santa rules (optional)

The kit also includes optional Santa rules in santa/ that block unapproved AI desktop apps such as Cursor and the ChatGPT chat app while allowing Barndoor, Claude, and Codex. Deploy the monitor rules first, then switch to the deny rules once you have seen what they would block. Delivery depends on your MDM; the kit’s guides/ folder covers Iru and Rippling.

2. Deploy in Iru

Scope everything to a pilot device group first.
1

Configuration profiles

Upload each rendered .mobileconfig as a custom profile and assign it to the group. Deliver managed settings and PPPC before or with the app so the first launch is already configured.
2

Updater script

Add one Custom Script library item to the same group, set to run every 15 minutes or daily. Iru runs the Remediation Script only when the Audit Script exits non-zero.
  • Audit Script: paste the script below. It exits 1 when Bridge is missing or older than the stable release, and 0 when it is current, newer, or the Mac cannot reach the release manifest.
  • Remediation Script: paste install-latest.sh.
For a pilot group on edge, change the manifest URL to https://downloads.barndoor.ai/barndoor-gui/mdm/edge/latest.json in that group’s copy, alongside the channel edit in its install-latest.sh (see How updates work).
3

Optional DNS profile

For provider lockdown with --dns, load the resolver policy into your resolver first, then deploy the profile.
Do not use /Applications/Barndoor.app/Contents/MacOS/Barndoor --version as the audit. It prints the version and exits 0 on every Mac that has Bridge, so Iru never runs the remediation and the fleet stays on the version it first installed. Earlier versions of this page suggested it; if your Iru item uses it, replace it with the script above.
You do not upload each Barndoor-<version>.pkg into Iru. The script fetches the current notarized package from downloads.barndoor.ai. No custom Network Extension or restricted entitlement is required.

3. Deploy in Rippling

Rippling is a full Apple MDM and takes the same artifacts. Rippling-specific rules:
  • Upload .mobileconfig files from a Mac. Rippling silently fails those uploads from Windows or Linux.
  • Upload from a visible folder. The file picker does not show folders whose names start with a dot, such as ~/.claude. Copy the rendered files to ~/Downloads or another ordinary folder first.
  • Give every Barndoor piece the same targets. The managed settings, login item, and PPPC profiles and the updater script should all reach the same Macs. A Mac with managed settings but no PPPC profile shows macOS permission prompts, and a Mac outside the script’s targets never updates.
1

Profiles first

IT → Devices → Policies tab. In the left rail under Library, open macOS library, then Upload ▾ → Custom configuration profile. Name the policy after the payload with a version number (for example “Barndoor CLI — Managed Settings v1”), pick the rendered file, and choose who gets it. Repeat for each rendered .mobileconfig.
Rippling Devices → Policies, macOS library selected in the left rail, with the Upload menu open showing Custom configuration profile (deploy a .mobileconfig file) and Apple DDM declaration
Choosing who gets it. Deploy policy starts at Applies to: Specific devices, filtered to OS type is: macOS, which is every Mac in the company. To reach only some teams, choose Applies to: Specific people → Membership rules, and add a rule on Department, for example Department equals Engineering. Preview people shows who matches, and people who join those departments later get it automatically. If department options under Specific devices are greyed out with “You don’t have permission to use this field”, your Rippling role cannot filter devices by department; Specific people works instead.Deployed custom profiles then appear under My policies → Everything else, which is where you retarget or remove one.
2

Then the updater

IT → Devices → Scripts tab: add install-latest.sh as a root-level recurring macOS script on those devices. It reads the release manifest; you do not upload a .pkg per release.
3

Optional DNS profile

For provider lockdown with --dns, load the resolver policy into your resolver first, then deploy the profile.
Order matters more on Rippling than on Iru: profiles before the script, so permissions and the backend pin exist at first launch. Changing the updater script in Rippling warns “Any change will clear pending scripts and rerun on all machines”. That is safe for install-latest.sh, which does nothing on a Mac that is already current.

Replacing a profile

An uploaded policy cannot be edited, and a policy goes to every Mac it targets. Changing a setting, such as adding a publisher key or turning on provider lockdown, therefore means replacing the profile on every Mac that has it, not just yours.
  1. Upload the changed file as a new policy with the next version number, for example “Barndoor CLI — Managed Settings v4” to replace v3.
  2. Deploy it to the Macs that should have it.
  3. Once the new policy shows as installed, remove the old one, or clear its targets.
Two deployed copies of the same payload leave a Mac with whichever one the MDM applied last, so do not leave both in place. While the swap happens, /Library/Managed Preferences/ai.barndoor.cli.plist can briefly disappear from a Mac before the new version lands a few seconds later. If the new version targets fewer Macs than the old one, the Macs you leave out lose their managed settings when you remove the old policy. On those Macs Bridge is no longer pinned to your organization and updates itself from the stable channel. Do not also add Barndoor under the Software tab. That catalog pushes one fixed .pkg and has no downgrade guard, so a later manual push can roll a Mac back to an older Bridge, and the updater script will then refuse to move it forward. The script is the only update path. The script’s result in Rippling may show accepted source=Notarized Developer ID under Error. That is the macOS notarization check reporting success on stderr, not a failure; the Output column carries the real result (barndoor-mdm-update: installed <version>).

4. How updates work

Bridge has two release channels. Stable is the default and is what customer fleets follow; it moves only when Barndoor promotes a release. Edge receives every Bridge build and is meant for a small pilot group that wants to see changes before stable. The updater script follows stable unless you pass --channel edge or set BARNDOOR_MDM_CHANNEL=edge in its environment. Most MDM consoles run the script body you paste and do not pass arguments, so to put a pilot device group on edge, deploy a second copy of the script to that group with this line near the top changed:
Give that group’s managed settings profile the same channel: in its rendered managed-prefs.mobileconfig, change the update_channel value from stable to edge. Bridge compares its version against that channel, so a mismatch makes correctly updated Macs look out of date. To move a single Mac to edge from a terminal:
A Mac that has installed an edge build stays on it until stable catches up; the script never downgrades. The script reports the channel in its output, for example barndoor-mdm-update: already at v0.1.210 (edge channel). The script updates Bridge, not itself. Your MDM keeps running the script text you pasted, so when a release changes the script, as v0.1.218 did for the Codex policy, paste the current install-latest.sh into each copy, keeping any channel edit. In Rippling, saving a changed script reruns it on every targeted Mac. A stable release is published on downloads.barndoor.ai only after the matching signed, notarized .pkg is available. The updater script:
  • accepts only that host
  • checks SHA-256, package signature, and Gatekeeper (Barndoor Developer ID Installer)
  • refuses to downgrade
  • lets the package post-install restart the menu-bar agent
Once the managed settings profile has landed, barndoor update and barndoor update-gui refuse with “updates are managed by your organization’s MDM”. That lockout is intended: IT owns the version. Without the profile there is no lockout, so deploy the profile before or with the app. Note that barndoor update never modifies /Applications/Barndoor.app; it installs a separate per-user CLI, which is exactly what the lockout prevents on a managed Mac.

5. Verify a Mac

On an enrolled laptop, after the user has logged into macOS, start with barndoor doctor. It shows where the configuration comes from, which managed settings arrived, whether direct access to provider APIs is blocked, and the state of the Claude policy.
barndoor doctor output on v0.1.210: Launch settings: organization client settings (launch profiles are replaced); Managed preferences Present: yes, Keys set: updates_managed, org_hint, publisher_keys, Updates managed: true; a tenant publisher key; Direct inference egress Result: not blocked: no DNS control is configured on this Mac and provider hosts are reachable; Claude policy sections
This Mac has no provider lockdown, so the egress result is not blocked and the Claude Code managed settings are missing, as expected. Use plain barndoor: the package links it at /usr/local/bin/barndoor. If which -a barndoor lists an older standalone copy first, for example in ~/.local/bin, remove it; it cannot read the configuration Bridge writes.
barndoor doctor also shows Launch settings: organization client settings. If it adds MDM default_profile is deprecated and ignored, the Mac still has a profile rendered with --default-profile; re-render without it when convenient. With lockdown on, a Result of present but NOT blocked means the MDM says lockdown is on but a provider host is still reachable: check the resolver policy or your secure web gateway’s rules. Then in the app: sign in, confirm Connected, and click Launch Claude Desktop and Launch Codex Desktop. The Servers tab lists each server’s status. If barndoor doctor shows Present: no, the managed settings profile did not land. Check that the payload domain is exactly ai.barndoor.cli and that the device is in the assigned group. If barndoor version shows an old version on managed Macs, your audit always passes, so the MDM never runs install-latest.sh. In Iru, check that the item’s Audit Script is the version comparison above, not Barndoor --version. Run the audit on an affected Mac: it should print the installed and stable versions and exit 1 until the Mac updates. In Rippling, check that the recurring script is assigned to the device and look at its last run’s output.

Unmanaged or lab install

For a single Mac that is not in MDM:
  1. Download and install the current stable package: https://downloads.barndoor.ai/barndoor-gui/latest/Barndoor.pkg. The matching checksum is at the same path with .sha256 appended.
  2. Open Barndoor from Applications and sign in.
  3. To keep it running at login without MDM, add it under System Settings → General → Login Items. The user can still disable that.
barndoor update-gui can install or upgrade the menu-bar app for developers who already have the CLI. It is not the fleet path, and it is locked out once updates_managed is set.