> 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-for-claude-and-codex-ide/bluerock-connector-macos.md).

# BlueRock Connector - macOS

The BlueRock Connector application for macOS establishes a secure bridge between local AI IDEs ([Claude Code](https://claude.com/product/claude-code) or [Codex](https://openai.com/codex/)) and the remote BlueRock sandbox. The application natively handles SSO and SSH key authentication, local port forwarding, and container lifecycle management to enable a fully remote coding workspace.

Here is the complete documentation content tailored specifically for the macOS sub-page.

## Prerequisites

### Software and Client Applications

* I**DEs:**
  * [Claude Code IDE](https://claude.com/product/claude-code) 
  * [Codex](https://openai.com/codex/)
* **BlueRock Connector App**: \
  Contact [BlueRock support](https://www.bluerock.io/contact) to obtain the `BlueRock-Connector-notarized.zip` file.

### System Requirements

* **Operating System**: \
  macOS (macOS 13 Ventura or later recommended).

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

Install the application strictly in the user's context. Do not install the application system-wide or as the root user, because the Connector stores identity locally in the user profile.
{% endhint %}

### Network and Security

* **Virtual Private Network (VPN)**: \
  If the BlueRock instance resides on a private network, active VPN connectivity is required to reach the instance.
* **Endpoint Protection**: \
  On desktop clients running firewalls or security software, allow port `2259` for inbound connections. The BlueRock Connector application runs a listener service on port `2259` and the loopback interface. The traffic is internal and never leaves the device.

## Installation

1. Locate and unzip the `BlueRock-Connector-notarized.zip` file to extract the application.
2. Double-click the extracted application to run it.

{% hint style="info" icon="notes" %}
**Note:** 

When launching the application, macOS might display a warning indicating that the application was downloaded from the internet. Click **Open** to proceed.

<img src="https://1983702018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCNnVnPvaRpvlLmPT6IAN%2Fuploads%2FIcRIzxQKTUzaBaiyQpUw%2Fimage.png?alt=media&amp;token=601f8a01-71a2-467e-b7d2-7c9b79888b17" alt="" data-size="original">
{% endhint %}

Access the BlueRock Connector from the Menu Bar (Status Menus) as well.

<figure><img src="https://1983702018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCNnVnPvaRpvlLmPT6IAN%2Fuploads%2FOnoqWjqmnFyL9MFxzEnF%2Fimage.png?alt=media&amp;token=ecc4d296-f8f3-4e07-8d1a-5f587913d3bd" alt=""><figcaption></figcaption></figure>

## Authentication and Enrollment

1. Once the application opens, select the **Set Up Connector** button.
2. Select **Continue** on the welcome screen.

   <div align="left"><figure><img src="https://1983702018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCNnVnPvaRpvlLmPT6IAN%2Fuploads%2F5DMQ3h7tP76LKBXiAYpn%2FScreenshot%202026-08-25%20at%202.47.29%20PM.png?alt=media&amp;token=44096523-edfc-4adc-b127-031a96030cee" alt=""><figcaption></figcaption></figure></div>
3. Choose one of the following authentication methods:
   1. Sign in with BlueRock:

      <div align="left"><figure><img src="https://1983702018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCNnVnPvaRpvlLmPT6IAN%2Fuploads%2FG0FhpynUtPqTQvhea3wT%2FScreenshot%202026-08-25%20at%202.47.40%20PM.png?alt=media&amp;token=4cf9d547-fb40-47bd-8514-e8113e0e9c97" alt=""><figcaption></figcaption></figure></div>

      1. Select the Sign in with BlueRock option.
      2. Provide the bootstrap string URL in the **Enrollment URL** field and enter the public DNS of the BlueRock host in the **Dev host** field. Click **Sign in**.

         <div align="left"><figure><img src="https://1983702018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCNnVnPvaRpvlLmPT6IAN%2Fuploads%2Fmj5cpUl1TgJAVPKcHkce%2FScreenshot%202026-08-25%20at%202.52.08%20PM.png?alt=media&amp;token=878ed2fb-0fb7-4a18-8704-73b7890b55fc" alt=""><figcaption></figcaption></figure></div>
      3. Complete the sign-in flow in the web browser to authorize the application.
   2. SSH Key

      <figure><img src="https://1983702018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCNnVnPvaRpvlLmPT6IAN%2Fuploads%2FmwQhW1sPJWz7GHu45DWr%2Fimage.png?alt=media&amp;token=f0ba5435-1fce-46da-b331-fce5ab590429" alt=""><figcaption></figcaption></figure>

      1. Select the **SSH key** option.
      2. Run the following command on the local machine to obtain the fingerprint:

         ```shellscript
         $ ssh-keyscan -T 10 -t ed25519 <host-ip> | ssh-keygen -lf - 2>&1
         ```
      3. Enter the **Bootstrap string** in the application using the following format: `<host-ip>#fp=SHA256:<base64>` (For example: 10.101.01.101#fp=SHA256:0x0x...)
      4. Click **Browse**, select the required SSH private key, and click **Install Key**.&#x20;

         <div align="left"><figure><img src="https://1983702018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCNnVnPvaRpvlLmPT6IAN%2Fuploads%2FZeQF9vAzCMokIOctBsgb%2Fimage.png?alt=media&amp;token=1fb40774-7a9f-4293-9ad9-d77433981ebf" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" icon="notes" %}
**Note:**&#x20;

Ensure the same SSH public key is present in the `.ssh` folder of the instance's Bluedev profile. Run the following commands on the BlueRock instance to configure the key:

```shellscript
sudo su
sudo su bluedev
mkdir -p ~/.ssh
chmod 700 ~/.ssh
vi ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
```

{% endhint %}

4. Then click **Close and Continue to Connector** to proceed working with the connector app.

<div align="left"><figure><img src="https://1983702018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCNnVnPvaRpvlLmPT6IAN%2Fuploads%2FN5G5JvBjZSxfOemFmEHq%2FScreenshot%202026-08-25%20at%202.53.38%20PM.png?alt=media&amp;token=3873e141-fae3-400d-866f-91833b0058cf" alt=""><figcaption></figcaption></figure></div>

## Environment Lifecycle Management

### Create Sandbox&#x20;

Select the **Create sandbox** button to initialize the remote container.&#x20;

*(Insert macOS Create Sandbox screenshot here)*

### Stop Sandbox

Click **Stop Sandbox** to halt the running container.

*(Insert macOS Stop Sandbox screenshot here)*

### Destroy Environment

Click Destroy Sandbox to completely purge and delete the container instance from the host.

*(Insert macOS Destroy Sandbox screenshot here)*

## Connecting AI Tools and Workspace Integration

### Connecting to Claude Code IDE

1. Select the Connect Claude button in the Connector app. \
   \
   *(Insert macOS Connect Claude screenshots here)*
2. In the Claude IDE, click the Code menu option and select Local. \
   \
   *(Insert macOS Claude Local option screenshot here)*
3. Select Add SSH Host. \
   \
   *(Insert macOS Claude Add SSH screenshot here)*
4. Enter `cobalt-59` in the SSH Host field and click Add SSH Connection. \
   \
   *(Insert macOS Claude Add Connection sequence screenshots here)*

### Connecting to Codex

1. Select the Connect Codex button in the Connector app. \
   \
   *(Insert macOS Connect Codex screenshot here)*
2. Follow the on-screen dialog instructions and click the provided link to authenticate. \
   \
   *(Insert macOS Codex Auth sequence screenshots here)*
3. In Codex, navigate to Connections > select SSH > click Add. \
   \
   *(Insert macOS Codex Add SSH screenshot here)*
4. Select Remote and click Next. \
   \
   *(Insert macOS Codex Remote configuration screenshot here)*
5. Select `cobalt-59` and click Add. Add the connection as a project to the Codex workspace. \
   \
   *(Insert macOS Codex Add Project screenshot here)*

### Verifying Session Execution and Script Output

1. In the connected Claude IDE or Codex environment, provide a prompt to create a basic "Hello World" Python script to verify the session.\
   \
   *(Insert screenshot of Claude Code IDE of prompting to create the hello world in the IDE)*
2. Review and verify the script output directly within the IDE's terminal or shell. \
   \
   *(Insert screenshot of Claude/Codex terminal output here)*

### Browsing Remote Sandbox Files via System File Explorer

1. In the BlueRock Connector application, select the **Browse Files** option.\
   \
   *(Insert screenshot of Browse Files in the connector app)*
2. View and interact with the remote files directly within macOS Finder. The `bluedev` container mounts natively on the macOS file system under shared network locations. \
   \
   *(Insert macOS Finder screenshot here)*

## Maintenance and Troubleshooting

### Exporting Connector Logs

To troubleshoot issues, export the application logs directly from the Menu Bar. Click the **BlueRock Connector icon** in the Menu Bar and select **Export Logs...**. Save the generated log file to a preferred location.&#x20;

*(Insert macOS Menu Bar Export Logs screenshot here)*

### Resetting Connector Configuration

Select Reset in the Sandbox dialog box, then confirm the prompt to clear the current configuration.&#x20;

*(Insert macOS Reset screenshots here)*

### Handling Session Expiration

When a session expires, or after stopping or destroying containers and resetting the configuration, remote network locations automatically unmount from the macOS file system and Docker containers terminate. Complete the Authentication and Sandbox Creation steps again to establish a new session.&#x20;

*(Insert macOS Finder screenshots showing unmounted drives after stopping/destroying here)*


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.bluerock.io/bluedev-container/bluerock-connector-for-claude-and-codex-ide/bluerock-connector-macos.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.