# Deploy to a team's Macs

> Install Cloak Proxy on a team's Macs with the signed, notarized installer package, pre-approve its network extension and Safari extension with a configuration profile, lock update checks, and decide how the team trusts Cloak Proxy's certificate.

Source: https://docs.subcloak.com/cloak-proxy/getting-started/deploy-to-a-team/

Added in Cloak Proxy 0.5.0.

If you look after a team's Macs with a device management service (MDM), you can install Cloak Proxy on all of them at once. Cloak Proxy comes as an installer package for this, `Cloak-Proxy.pkg`, next to the usual disk image. A sample configuration profile pre-approves the parts of Cloak Proxy that macOS otherwise asks each person about.

What stays with each person: trusting the certificate, choosing what to capture, and their captured traffic, rules and settings. The package installs the app and nothing else.

## The installer package

| | |
|---|---|
| File | `Cloak-Proxy.pkg`, on the [Cloak Proxy download page](https://subcloak.com/apps/cloak-proxy) under the Mac download (**Installer package for teams (.pkg)**) |
| Installs | `/Applications/Cloak Proxy.app` on the startup disk (or the disk `installer -target` names), replacing the copy that's there. It's not relocatable: Installer doesn't go looking for a copy of the app in another folder. |
| Signed | With Subcloak's Developer ID Installer certificate (team `8JJX52F3NV`), notarized by Apple and stapled |
| Requires | macOS 14 or later, Apple silicon or Intel (the app is universal) |
| Scripts | None. It doesn't change any settings, start anything or add login items. It installs as root (an admin password, or your MDM). |
| Receipt | `com.subcloak.cloakproxy` (`pkgutil --pkg-info com.subcloak.cloakproxy`) |

Check a downloaded package before you upload it to your MDM. The signature should be a Developer ID Installer certificate with the team ID `8JJX52F3NV`, notarized by Apple:

```bash title="Terminal"
pkgutil --check-signature Cloak-Proxy.pkg
#   Status: signed by a developer certificate issued by Apple for distribution
#   Notarization: trusted by the Apple notary service
#   Signed with a trusted timestamp on: …
#   Certificate Chain:
#    1. Developer ID Installer: … (8JJX52F3NV)
#    2. Developer ID Certification Authority
#    3. Apple Root CA
spctl -a -vv -t install Cloak-Proxy.pkg
#   Cloak-Proxy.pkg: accepted
#   source=Notarized Developer ID
```

## Install it

**With an MDM**

Upload `Cloak-Proxy.pkg` as a package (some services call it a custom app or a macOS LOB app) and assign it to the Macs or groups that need it. The MDM installs it in the background. People don't need to be admins.

**From Terminal**

```bash title="Terminal"
sudo installer -pkg Cloak-Proxy.pkg -target /
```

Useful for a script or a single Mac. Double-clicking the package opens Installer, which does the same.

The app is owned by `root:wheel` after a package install, like other managed apps. People can still open and use it normally, but they can't replace it by dragging a newer copy from the disk image without an admin password. Deploy new versions with the new package instead.

## Update

Deploy the newer `Cloak-Proxy.pkg` the same way. Installer replaces the app in place and keeps everything people have in Cloak Proxy: their traffic, rules, collections and settings live in their home folder, not in the app.

If Cloak Proxy is open during the update, it keeps running the old version until it's quit. Ask people to quit and reopen it, or schedule the install for when Macs are idle. The package checks the app's version, so Installer doesn't replace a newer copy of the app with an older one.

## The configuration profile

The sample profile [`CloakProxy.mobileconfig`](https://docs.subcloak.com/cloak-proxy/mdm/CloakProxy.mobileconfig) has two payloads. Upload it to your MDM, which signs it and installs it on the Macs. macOS only applies the system extension payload when an MDM installs the profile, not when someone opens the file.

### Pre-approve the network extension

[App Capture](https://docs.subcloak.com/cloak-proxy/capture/capture-apps-that-ignore-the-proxy/) sends apps that ignore the macOS proxy through Cloak Proxy with a network extension. The first time someone installs it, macOS asks them to allow the extension in **System Settings › General › Login Items & Extensions** (macOS 15 and later) or **Privacy & Security** (macOS 14). The profile's system extension policy allows it in advance:

| Key | Value |
|---|---|
| Payload type | `com.apple.system-extension-policy` |
| `AllowedSystemExtensions` | `8JJX52F3NV`: `com.subcloak.cloakproxy.transparent-proxy` |
| `AllowUserOverrides` | `true`, so people can still approve other extensions themselves |

App Capture stays off until someone picks apps and turns it on in Cloak Proxy. When they do for the first time, macOS still asks once whether Cloak Proxy may add proxy configurations. A profile can't answer that question for a configuration the app creates itself.

### Managed preferences

The profile's second payload sets Cloak Proxy's preferences (domain `com.subcloak.cloakproxy`). **Settings › General › Updates** shows these switches locked, with **Your organization manages these settings.**

| Key | Type | Sample value | What it does |
|---|---|---|---|
| `autoCheckForUpdates` | Boolean | `false` | Checking download.subcloak.com for a new version once a day. Off by default. Lock it off when you deploy updates yourself. |
| `countActiveInstalls` | Boolean | `false` | Adding the version and platform to update checks for Subcloak's anonymous install count. Off by default. |

Leave out this payload if people may choose for themselves. Cloak Proxy has no other managed preferences yet.

### Turn on the Safari extension

The [Safari extension](https://docs.subcloak.com/cloak-proxy/devices/browser-extension/#safari) comes inside the app, but Safari keeps it off until someone turns it on. On supervised Macs with macOS 15 or later, an MDM that supports declarative device management can turn it on for everyone with a Safari extension settings declaration. [`safari-extension-settings.json`](https://docs.subcloak.com/cloak-proxy/mdm/safari-extension-settings.json) is a sample:

```json title="safari-extension-settings.json"
{
    "Type": "com.apple.configuration.safari.extensions.settings",
    "Identifier": "6F0B7C2E-3A5D-4E8B-9C1F-2D4A6B8E0C13",
    "Payload": {
        "ManagedExtensions": {
            "com.subcloak.cloakproxy.safari-extension (8JJX52F3NV)": {
                "State": "AlwaysOn",
                "AllowedDomains": ["*"]
            }
        }
    }
}
```

`AllowedDomains: ["*"]` lets the extension report requests from every website, which tagging needs. People still [pair the extension](https://docs.subcloak.com/cloak-proxy/devices/browser-extension/#pair-it-with-cloak-proxy) with their own Cloak Proxy: each pairing has its own key.

## Certificate trust

Cloak Proxy creates its own root certificate on each Mac the first time it opens, so every person's is different and nobody can decrypt anyone else's traffic. Trusting it takes the person's confirmation (their login password, or an admin password to trust it for the whole Mac), so a profile can't trust it in advance: you can't know the certificate before the app makes it. For most teams, let people trust their own certificate from the app's first-run setup.

If your team needs the Macs to trust Cloak Proxy without anyone confirming, use a team certificate authority instead:

1. Create a certificate authority only for debugging, with an ECDSA P-256 key. Cloak Proxy doesn't support RSA keys. Never use your organization's real root.
2. Deploy its certificate (not the key) with a Certificate payload (`com.apple.security.root`), so the Macs trust it.
3. Give each person the certificate and key to load in **Settings › Certificate › Use My Own CA…**. See [Use your own CA](https://docs.subcloak.com/cloak-proxy/capture/certificate/#use-your-own-ca). Or have your MDM place them in `~/Library/Application Support/CloakProxy/` as `cloak-proxy-ca.pem` and `cloak-proxy-ca-key.pem` (readable only by the user) before Cloak Proxy first opens; it uses them instead of making its own.

> **A shared key is a shared risk:**
> Everyone who has the team CA's private key can make certificates that every one of those Macs accepts for any website, and read traffic on them. Keep the CA for debugging only, give the key to the people who need it, and replace it (and the certificate payload) when someone leaves.

## Remove Cloak Proxy

Remove App Capture's network extension first, if it was installed. Deleting the app doesn't remove it: only the app that contains a system extension can ask macOS to remove it. Either have people click **Remove Extension…** on the App Capture page, or run this in Terminal on each Mac before you delete the app:

```bash title="Terminal"
"/Applications/Cloak Proxy.app/Contents/MacOS/CloakProxy" --remove-network-extension
```

It removes the proxy configuration and the extension without opening a window or starting the proxy, and exits with 0 when the extension is gone or wasn't installed. macOS may finish the removal at the next restart. See [Remove App Capture](https://docs.subcloak.com/cloak-proxy/capture/capture-apps-that-ignore-the-proxy/#remove-app-capture).

Then remove the app and forget the receipt:

```bash title="Terminal"
sudo rm -rf "/Applications/Cloak Proxy.app"
sudo pkgutil --forget com.subcloak.cloakproxy
```

Each person's own files and certificate stay until they remove them: see [Uninstall](https://docs.subcloak.com/cloak-proxy/getting-started/install/#uninstall-cloak-proxy-completely).

## Related

  - [Install on macOS](https://docs.subcloak.com/cloak-proxy/getting-started/install/): Download the disk image and install Cloak Proxy yourself.
  - [Root certificate](https://docs.subcloak.com/cloak-proxy/capture/certificate/): Trust, replace or bring your own certificate authority.
  - [Capture apps that ignore the proxy](https://docs.subcloak.com/cloak-proxy/capture/capture-apps-that-ignore-the-proxy/): App Capture and the network extension the profile pre-approves.
  - [Browser extension](https://docs.subcloak.com/cloak-proxy/devices/browser-extension/): Tag requests with their tab in Safari, Chrome, Edge, Brave and Firefox.