> For the complete documentation index, see [llms.txt](https://docs.bluerock.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bluerock.io/bluedev-container/bluerock-connector-mdm-deployment.md).

# BlueRock Connector – MDM Deployment

The Mobile Device Management (MDM) deployment package provides the scripts required to install, configure, and enroll the BlueRock Connector Client application on Windows and macOS desktops from the MDM console. This package enables IT administrators to distribute the application seamlessly. Consequently, end users can access the BlueRock Sandbox directly from their coding agent IDEs without requiring manual configuration.

## Deployment Components

The deployment package contains four core files categorised by platform:

{% tabs %}
{% tab title="Windows" %}
The following components are deployed to Windows devices:

| **File**                        | **Purpose**                                                                                                                                              | **Execution Context**  |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| `windows\enroll_bluerock.ps1`   | Downloads the connector executable, runs the certificate enrollment with the bootstrap URL, configures the SSH host block, and launches the application. | Logged-on user         |
| `windows\managed-settings.json` | Configures managed settings, disables local desktop sessions, and pre-configures the SSH target.                                                         | System / Administrator |
| {% endtab %}                    |                                                                                                                                                          |                        |

{% tab title="macOS" %}
The following components are deployed to macOS devices:

| **File**                      | **Purpose**                                                                                                                  | **Execution Context**        |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| `macos\enroll_bluerock.sh`    | Downloads the macOS application, completes enrollment, updates the SSH configuration, and launches the menu bar application. | Logged-on user (GUI session) |
| `macos\managed-settings.json` | Configures managed settings for the macOS environment.                                                                       | Root / Administrator         |
| {% endtab %}                  |                                                                                                                              |                              |
| {% endtabs %}                 |                                                                                                                              |                              |

{% hint style="success" icon="lightbulb-exclamation-on" %}
**Important**:&#x20;

Run the enrollment scripts (`enroll_bluerock.ps1` and `enroll_bluerock.sh`) in the logged-on user's context. Running these scripts as SYSTEM or root binds the enrollment to the incorrect identity and places configuration files in the wrong user profile.
{% endhint %}

## Prerequisites

Ensure the following requirements are met before initiating the deployment:

{% tabs %}
{% tab title="Windows" %}

* **Operating System Version:**\
  Windows 10 1803+ or Windows 11 (requires `curl.exe` and Windows PowerShell 5.1).
* **Enrollment State:**\
  Devices must be MDM-enrolled and Entra ID joined or registered. A user must be signed into the device during the script execution.
* **Network Egress:**\
  The network firewall or proxy must allow access to the following hosts:
  * `bluerock-public.s3.us-east-1.amazonaws.com` (Connector download)
  * `identity.<your-environment>.bluerockenv.io` (Enrollment / Bootstrap URL)
  * `sandbox.bluerock.io` (SSH target)
* **OpenSSH Client:** \
  The system must have the OpenSSH client installed (an optional feature enabled by default on current Windows 11 systems).
  {% endtab %}

{% tab title="macOS" %}

* **Operating System Version:**\
  macOS (macOS 13 Ventura or later recommended).
* **Enrollment State:**\
  Devices must be MDM-enrolled and Entra ID registered. A user must be signed into the device during the script execution.
* **Network Egress**:\
  The network firewall or proxy must allow access to the following hosts:
  * `bluerock-public.s3.us-east-1.amazonaws.com` (Connector download)
  * `identity.<your-environment>.bluerockenv.io` (Enrollment / Bootstrap URL)
  * `sandbox.bluerock.io` (SSH target)
* **OpenSSH Client:**\
  The system must have the OpenSSH client installed (pre-installed by default on macOS).
  {% endtab %}
  {% endtabs %}

### Script Preparation

Both enrollment scripts contain a default `$bootstrapUrl` or `bootstrap_url` variable. Update this variable with the specific URL and fingerprint (`#fp=...`) for the target environment before uploading the script to the MDM platform.

## Deployment Guidelines

Deploy the components in two distinct phases: deploy the managed settings file first, followed by the enrollment script.

### Deploying Managed Settings

Deploy the `managed-settings.json` file to the target machines. This file must reside in a system-wide directory, requiring the deployment task to execute with administrative or root privileges.

{% tabs %}
{% tab title="Windows" %}
Configure the MDM platform to copy or generate the settings file at `C:\Program Files\ClaudeCode\managed-settings.json`. The script or package must run in the SYSTEM context.&#x20;

Use the following managed settings payload for Windows:

{% code title="managed-settings.json" lineNumbers="true" %}

```json
{
  "disableDesktopLocalSessions": true,
  "sshHostAllowlist": [
    "sandbox.bluerock.io"
  ],
  "sshTransport": "system-openssh",
  "sshConfigs": [
    {
      "id": "bluerock managed sandbox",
      "name": "Bluerock Managed Sandbox",
      "sshHost": "bluerock-sandbox",
      "sshIdentityFile": "%USERPROFILE%\\.config\\bluerock\\cobalt\\bridge\\client_ed25519"
    }
  ]
}
```

{% endcode %}
{% endtab %}

{% tab title="macOS" %}
Configure the MDM platform to place the settings file at `/Library/Application Support/ClaudeCode/managed-settings.json`. The script or package must run as root.&#x20;

Use the following managed settings payload for macOS:

{% code title="managed-settings.json" lineNumbers="true" %}

```json
{
  "disableDesktopLocalSessions": true,
  "sshHostAllowlist": [
    "sandbox.bluerock.io"
  ],
  "sshTransport": "system-openssh",
  "sshConfigs": [
    {
      "id": "bluerock managed sandbox",
      "name": "Bluerock Managed Sandbox",
      "sshHost": "bluerock-sandbox",
      "sshIdentityFile": "~/.config/bluerock/cobalt/bridge/client_ed25519"
    }
  ]
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

#### `managed-settings.json` Script's Parameters

<table data-header-hidden data-search="false"><thead><tr><th></th><th></th><th></th></tr></thead><tbody><tr><td><strong>Parameter</strong></td><td><strong>Type</strong></td><td><strong>Description</strong></td></tr><tr><td><code>disableDesktopLocalSessions</code></td><td>Boolean</td><td>Disables local desktop sessions within the Claude Code IDE.</td></tr><tr><td><code>sshHostAllowlist</code></td><td>Array</td><td>Specifies the list of permitted SSH hosts (e.g., <code>sandbox.bluerock.io</code>).</td></tr><tr><td><code>sshTransport</code></td><td>String</td><td>Defines the SSH transport mechanism to use (e.g., <code>system-openssh</code>).</td></tr><tr><td><code>sshConfigs</code></td><td>Array</td><td>Contains the pre-configured SSH connection details.</td></tr><tr><td><code>sshConfigs[].id</code></td><td>String</td><td>Unique internal identifier for the SSH configuration block.</td></tr><tr><td><code>sshConfigs[].name</code></td><td>String</td><td>Display name of the SSH target in the IDE interface.</td></tr><tr><td><code>sshConfigs[].sshHost</code></td><td>String</td><td>The SSH host alias that matches the system's SSH configuration block (<code>bluerock-sandbox</code>).</td></tr><tr><td><code>sshConfigs[].sshIdentityFile</code></td><td>String</td><td><p>The file path to the client identity key used for authentication.</p><ul><li>Windows: <code>%USERPROFILE%\.config\bluerock\cobalt\bridge\client_ed25519</code></li><li>macOS: <code>~/.config/bluerock/cobalt/bridge/client_ed25519</code></li></ul></td></tr></tbody></table>

### Deploying Enrollment Scripts

Configure the MDM platform to execute the enrollment scripts for the target devices. The script must execute in the context of the logged-on user.

{% tabs %}
{% tab title="Windows" %}
Deploy `enroll_bluerock.ps1` as a user-context script.

Reference Intune Settings:

* Run this script using the logged on credentials: Yes
* Enforce script signature check: No
* Run script in 64-bit PowerShell Host: Yes
  {% endtab %}

{% tab title="macOS" %}
Deploy `enroll_bluerock.sh` as a user-context script. For MDM platforms that enforce root execution by default (such as Jamf Pro), prepend a script wrapper to execute the commands within the console user's GUI session.

Reference Intune Settings:

* Run script as signed-in user: Yes
* Hide script notifications: Yes
  {% endtab %}
  {% endtabs %}

## Deployment Validation

After deployment, verify the installation on a pilot device to ensure successful enrollment.

1. **Launch and Sign In:** \
   Once the enrollment script runs successfully, the BlueRock Connector launches automatically. Follow the prompts to sign in to the connector.

   <div align="left"><figure><img src="https://1983702018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCNnVnPvaRpvlLmPT6IAN%2Fuploads%2FZMNpmNxz9W8k1zGjRMmY%2Fimage.png?alt=media&amp;token=301ec6fe-6d03-4eb0-8c31-bbddfb6b1449" alt="" width="507"><figcaption></figcaption></figure></div>
2. **Verify Sandbox Connection:** \
   After successful authentication, the connector interface displays your assigned BlueRock sandbox.

   <div align="left"><figure><img src="https://1983702018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCNnVnPvaRpvlLmPT6IAN%2Fuploads%2Ffsbwd7cy1Ofo2EqcO0VM%2Fimage.png?alt=media&amp;token=fadeed79-3d86-4c37-9c4e-c859107582be" alt="" width="486"><figcaption></figcaption></figure></div>
3. **Validate IDE Integration:** \
   Open the Claude Code IDE. Confirm that the application automatically connects to the sandbox and that all local sessions are disabled, reflecting the applied managed settings.<br>

   <div align="left"><figure><img src="https://1983702018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCNnVnPvaRpvlLmPT6IAN%2Fuploads%2FNbNq8z3q3Rs1wBgbHPNU%2Fimage.png?alt=media&amp;token=763aaca8-44f2-4a43-919b-f830086743de" alt="" width="563"><figcaption></figcaption></figure></div>

## Script Reference and Usage

This section provides additional details on script execution, available options, and internal operations for administrators.

### Default Commands

{% tabs %}
{% tab title="Windows" %}
Run the following command in Windows Powershell

```bash
powershell -ExecutionPolicy Bypass -File .\enroll_bluerock.ps1
```

{% endtab %}

{% tab title="macOS" %}
Run the following command in macOS bash

```bash
bash enroll_bluerock.sh
```

{% endtab %}
{% endtabs %}

### Script Options

The following options are accepted by both scripts:

| **Option**         | **Description**                                                                                                                                                          |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `-BootstrapUrl`    | Bootstrap URL used for enrollment. Optional: if omitted, the URL set at the top of the script is used. Must be quoted on the command line.                               |
| `-ConnectorDir`    | Folder the connector is downloaded into and run from. Optional; created if it does not exist. Default: `~\bluerock_connector` (Windows), `~/bluerock_connector` (macOS). |
| `-SkipDownload`    | Do not download the connector; use the one already in the connector folder. Optional, and only valid together with `-ConnectorDir`.                                      |
| `-QuitClaude`      | Quit the Claude desktop app just before the connector is launched, so it picks up the new settings on its next start.                                                    |
| `-Help` / `--help` | Show the built-in help and exit with code 0, without changing anything.                                                                                                  |

### What the Scripts Do <a href="#p-rc_717079fa61ab03a1-415" id="p-rc_717079fa61ab03a1-415"></a>

Both scripts perform the following sequence of operations:

1. Picks the bootstrap URL (the `-BootstrapUrl` argument, otherwise the value set in the script) and shows which was used.
2. Downloads the latest connector into the connector folder, replacing the existing one. If the download fails and a valid connector is already present, it falls back to the existing one with a warning.
3. Stops any running connector, removes the cobalt configuration folder, and runs the connector with `enroll-cert <bootstrap_url>`.
4. Adds or replaces the `Host bluerock-sandbox` block in the SSH config file.
5. Launches the connector in the background (closing the Claude desktop app first if `-QuitClaude` is specified).
6. Adds the bluerock sandbox entry to `sshConfigs` in the Claude settings file, unless managed settings are already applying it.

{% hint style="success" icon="lightbulb-exclamation-on" %}

#### Important: <a href="#p-rc_717079fa61ab03a1-420" id="p-rc_717079fa61ab03a1-420"></a>

* Run the script as the signed-in user, not as SYSTEM or root: it writes to the user’s profile and the connector is a tray / menu bar app that needs the user’s desktop session.
* Options can be given in any order. An unknown option stops the script with a message.
* The scripts exit 0 on success and a non-zero code on failure.
* Re-running is safe: the connector is replaced, the cobalt configuration is re-created, and the ssh and Claude entries are never duplicated.
* Option names have the same capitalization on both platforms. On macOS run the script with bash, as shown.
  {% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.bluerock.io/bluedev-container/bluerock-connector-mdm-deployment.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
