Skip to content

Guardrails through MDM ​

Guardrails runs on each user's machine, so to cover an entire organization IT pushes it with a device management tool (MDM). This page covers the packages you can build, how to build them, where Guardrails writes files on each operating system, how to verify and how to uninstall. The Guardrails rules are a separate matter and live in the policy package on Tara. Rules apply in three tiers (platform, organization, project), and a lower tier can only tighten the tier above it.

An individual installs for their own machine with sudo ph guardrails install. The MDM packages run that same command for you, so the files written are identical.

What packages exist ​

Operating systemPackagePushed with
macOSPhillipCLI-Guardrails-<version>.pkgJamf, Kandji, Intune (the package must be signed), installer -pkg
Linux.deb and .rpmapt, dnf, Ansible, Satellite
WindowsPhillipCLI-Guardrails-<version>-windows.zip (PowerShell scripts, wrapped as a Win32 app) and Detect-Guardrails.ps1Intune, SCCM, a PowerShell window with Administrator rights

Each organization builds its own set of packages, because the Tara address, the Ryoma address and the public keys are written into the configuration inside the package:

bash
deploy/guardrails-mdm/build.sh all \
  --tara https://tara.phillipcli.cloud --ryoma https://ryoma.phillipcli.cloud --keys ed25519:...

The build parameters are these.

ParameterMeaning
--taraTara address, where the hook server downloads the policy
--keysed25519:... public key for verifying the policy signature. Get it from GET /v1/signing-keys on Tara
--ryomaRyoma address that receives block counts. Optional
--policyName of the platform policy package, default kit-policy-corporate
--orgUUID of the organization on Claude. Writes forceLoginOrgUUID so users can sign in only with organization accounts. Use it with the Team plan
--managed-hooks-onlyBlocks hooks declared by plugins and allows only hooks from managed settings. Off by default
--audit-uploadSends the masked audit to the central store. Turn it on only when the organization has decided to
--device-token-fileFile with the organization's device token, so machines get policy before anyone has signed in. See the next section
--selftestwarn (default), strict or skip: what happens when the install-time selftest fails
--node-mac, --node-linux, --node-winBundle Node.js. Without it the machine must already have Node 22 or newer

The packages are installed by Phillip itself: the install step on the machine calls ph guardrails install, so paths, permissions and the per-machine token all come from the same code. If the machine already has managed settings from another source, the old file is backed up before writing.

A package built without a device token needs each user to sign in to Tara once with ph tara login, because the hook server downloads the policy with that user's own token. Until then Claude Code blocks every prompt. A device token removes that step.

A new machine nobody has signed in to: the device token ​

A machine that MDM has just installed has no one who ran ph tara login, so the hook server has no token to download the platform policy and Guardrails blocks everything (fail-closed). A device token lets the machine receive the organization's policy as soon as it is installed.

An owner or admin creates the token, from a signed-in session (the Portal or ph tara login). It belongs to one organization and can do three things only: read the list of platform and organization policies in effect, download the policy packages in that list with their signatures, and read the revocation lists. Every other route answers 403, project-tier policies included. Tara stores only a hash, and creating and revoking are written to the audit log.

bash
ph org device-token create "Laptops (Jamf)" --out device-token.env
deploy/guardrails-mdm/build.sh all --tara https://tara.phillipcli.cloud --keys ed25519:... \
  --device-token-file device-token.env

The first command writes the token to a file with mode 600 and prints nothing to the screen. The Portal has the same function under Settings, Guardrails, "Device enrollment tokens". A file is used instead of an argument so the token stays out of shell history and the process list. A package built with the token carries it, so push it only through MDM or a private repository.

On the machine, ph guardrails install writes the token to a guardrails-device.json file next to the Phillip copy, and then the install script removes the token from the configuration inside the package. The token is not in the managed settings, the service file or the logs. Only an administrator can write the file, but every user on the machine can read it, because the hook server runs with the user's rights. The risk is limited on the Tara side: the token can only read policy.

When a user has signed in to Tara, the hook server uses that user's own token, so project-tier policy still applies. The device token is the fallback, used when nobody has signed in or when the sign-in token has expired. Two limits: without a sign-in there is no project-tier policy, and the counts sent to Ryoma and --audit-upload still need a sign-in (the audit on the machine is still written).

To rotate, create a new token, build and push new packages, then revoke the old token with ph org device-token revoke <id>. ph org device-token lists tokens with their expiry and last use. When a token expires or is revoked, a running hook server keeps the policy it has loaded, but after a restart that can't load, Claude Code blocks prompts until the machine has a valid token.

Where Guardrails writes files ​

Operating systemManaged settingsPhillip copyService
macOS/Library/Application Support/ClaudeCode//Library/Application Support/AI-Forge/phillipLaunchAgent that runs the hook server
Linux/etc/claude-code//opt/ai-forge/phillipsystemd user unit, enabled for all users
WindowsC:\Program Files\ClaudeCode\C:\Program Files\AI-Forge\phillipScheduled Task that runs at sign-in

The hook server restarts itself if it stops. After installation, restart any Claude Code session that was open earlier so it loads the hooks. Changing the policy doesn't require pushing the package again, because the hook server downloads the new policy from Tara on its own. Build and push again only when the Tara address, the Ryoma address, the keys or the device token change.

You can also push managed settings from the Claude admin console. In that case, keep the exact hooks block that the install command generates on each machine, because the token in it differs per machine. There is no .mobileconfig for Claude Code, because the documentation doesn't say Claude Code reads these settings from a profile.

Push with your tool ​

Jamf Pro. Upload the .pkg, then create a policy with the Enrollment Complete or Recurring Check-in trigger and the frequency Once per computer.

Kandji. Add a Custom App of type Package. To have Kandji reinstall when Guardrails goes missing, use an audit script that checks grep -q "127.0.0.1:7802/hook" "/Library/Application Support/ClaudeCode/managed-settings.json".

Intune, Windows. Wrap the script folder with IntuneWinAppUtil.exe (it runs on Windows), then create a Win32 app with these settings.

ItemValue
Install commandpowershell.exe -NoProfile -ExecutionPolicy Bypass -File .\Install-Guardrails.ps1
Uninstall commandpowershell.exe -NoProfile -ExecutionPolicy Bypass -File .\Uninstall-Guardrails.ps1
Install behaviorSystem
Detection ruleCustom script Detect-Guardrails.ps1

Linux. apt install ./phillip-guardrails_<version>_all.deb or dnf install ./phillip-guardrails-<version>-1.noarch.rpm, or put the package in an internal repository.

Verify after the push ​

At install time, the package runs the selftest on a throw-away hook server and writes every line to the install log (/var/log/phillip-guardrails.log on macOS and Linux, C:\ProgramData\AI-Forge\logs\guardrails-install.log on Windows). A package with a device token runs the selftest with that token and passes without anyone signing in. A package without one, or a Tara that can't be reached yet, can make the install-time selftest fail even though the install is correct. In warn mode the install is kept, and you run the selftest again after users sign in.

On a sample machine, run these three commands after MDM has installed Guardrails.

bash
ph guardrails status
ph forge doctor
ph guardrails selftest

status shows whether the hook server is running, which platform policy is in effect, whether the hook server is using the user's sign-in or the device token, and where the managed settings are. forge doctor includes one Guardrails line. selftest sends 16 acceptance scenarios to the running hook server without calling a model, and all of them must pass. Run selftest again after every policy change.

To try it with real Claude Code, open /status in a new session. The Setting sources line must include Managed settings.

The hook server runs with the user's rights, so a malicious process with the same rights can stop it. Guardrails has self-protection rules, the service restarts itself, and forge doctor and status report when the hook server isn't running. But Guardrails is a first layer, not a replacement for a firewall or proxy, and it doesn't stop someone with admin rights who deliberately bypasses it. That is the job of MDM and internal policy.

Uninstall and restore ​

Each operating system has its own way to uninstall, and all of them call ph guardrails uninstall underneath.

Operating systemUninstall
macOSsudo "/Library/Application Support/AI-Forge/installer/uninstall.sh"
Linuxapt remove phillip-guardrails or dnf remove phillip-guardrails
WindowsUninstall-Guardrails.ps1 in an Administrator window, or the Intune Uninstall command

The command removes the managed settings first (restoring the old file that was backed up at install time), then the service, the Phillip copy and the device token file. Claude Code then runs as it did before installation.

Further reading ​