> 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/bluerock-documentation-2.7.0-beta/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 container. 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. ## Setup and Configuration Workflow Follow the complete deployment path below, or jump directly to the required phase: 1. [Prerequisites](#prerequisites) 1. [Software and Client Applications](#software-and-client-applications) 2. [System Requirements](#system-requirements) 3. [Network and Security](#network-and-security) 2. [Installation](#installation) 3. [Authentication and Enrollment](#authentication-and-enrollment) 4. [Evironment Lifecycle Management](#environment-lifecycle-management) 1. [Create Sandbox](#create-sandbox) 2. [Stop Sandbox](#stop-sandbox) 3. [Destroy Environment](#destroy-environment) 5. [Connecting AI Tools and Workspace Integration](#connecting-ai-tools-and-workspace-integration) 1. [Connecting to Claude Code IDE](#connecting-to-claude-code-ide) 2. [Connecting to Codex](#connecting-to-codex) 3. [Verifying Session Execution and Script Output](#verifying-session-execution-and-script-output) 4. [Browsing Remote Sandbox Files via Systems File Explorer](#browsing-remote-sandbox-files-via-system-file-explorer) 6. [BlueRock Connector Command-Line Interface Features](#bluerock-connector-command-line-interface-features) 1. [Remote Shares](#remote-shares) 2. [Port Forwarding](#port-forwarding) 7. [OTEL Events](#otel-events) 8. [Maintenance and Troubleshooting](#maintenance-and-troubleshooting) 1. [Exporting Connector Logs](#exporting-connector-logs) 2. [Session Expiration](#session-expiration) 3. [Network and SSH Disconnection](#network-and-ssh-disconnection) 4. [Resetting Connector Configuration](#resetting-connector-configuration) ## 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. {% endhint %} Access the BlueRock Connector from the Menu Bar (Status Menus) as well.
## Authentication and Enrollment 1. Once the application opens, select the **Set Up Connector** button. 2. Select **Continue** on the welcome screen.
3. Choose one of the following authentication methods: 1. Sign in with BlueRock:
1. Select the Sign in with BlueRock option. 2. Provide CA server enrollment URL in the **Enrollment URL** field, and enter the public DNS or IP address of the BlueRock host in the **Dev host** field. Click **Sign in**.
3. Complete the sign-in flow in the web browser to authorize the application. 2. Sign in with SSH Key
1. Select the **SSH key** option.

Important:

Ensure the associated SSH public key is present in the ~/.ssh/authorized_keys file of the bluedev user profile on the BlueRock VM/host. If the .ssh folder does not exist, create the folder and add the authorized_keys file with the required entry. Run the following commands on the remote BlueRock VM/host to configure the key:

sudo su
         sudo su bluedev
         mkdir -p ~/.ssh
         chmod 700 ~/.ssh
         vi ~/.ssh/authorized_keys
         chmod 600 ~/.ssh/authorized_keys
2. Run the following command on the local client machine to obtain the fingerprint: ```shellscript $ ssh-keyscan -T 10 -t ed25519 | ssh-keygen -lf - 2>&1 ``` 3. Enter the **Bootstrap string** in the application using the following format: `#fp=SHA256:` (For example: 10.101.01.101#fp=SHA256:0x0x...) 4. Click **Browse**, select the required SSH private key, and click **Install Key**.
4. Then click **Close and Continue to Connector** to proceed working with the connector app.
## Environment Lifecycle Management ### Create Sandbox Select the **Create sandbox** button to initialize the remote sandbox container.
### Stop Sandbox Select **Stop Sandbox** to halt the running sandbox container. The sandbox container enters a stopped state and can be restarted later with the workspace intact.
### Destroy Environment Select **Destroy Sandbox** to terminate the remote sandbox container instance from the BlueRock host and unmount the remote files.
Then the system prompts for confirmation, select **Destroy Sandbox - confirm** to complete the termination.
## Connecting AI Tools and Workspace Integration ### Connecting to remote BlueDev Sandbox container from Claude Code IDE 1. Select the **Connect Claude** button in the Connector app.
2. Select **Open Claude Desktop** and follow the instructions given on the screen.
3. In the Claude IDE, click the **Code** menu option and select **Local** > **SSH** > **Add SSH connection...**
4. Enter `cobalt-59` in the **SSH Host** field and click **Add SSH Connection**.
Then Claude Code will SSH into the remote Sandbox container. The remote sandbox container executes all tasks assigned to the coding agent in the Claude IDE chat window, bypassing the local workspace entirely.
### Connecting to remote BlueDev Sandbox container from Codex IDE 1. Select the Connect Codex button in the Connector app.
2. Follow the on-screen dialog instructions and click the provided link to authenticate.
3. Authenticate with the OpenAI/ChatGPT account in the default browser.
4. Enter the one-time code and select **Continue**.
5. Upon completion of OpenAI account setup, the BlueRock Connector app gives a new prompt to **Open Codex Settings**.
6. In Codex, navigate to **Connections** > select **SSH** > click **Add**.
7. Select **Remote** and click **Next**.
8. Select `cobalt-59` and click **Add**. Add the connection as a project to the Codex workspace.
9. In the New Remote Project pane, select **cobalt-59** from the Remote dropdown and select **Add Project**.
Once the project connects successfully, it will be added in the SSH section.
Then use it as a project in the Codex workspace.
### 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.
2. Review and verify the script output directly within the IDE's terminal or shell.
### Browsing Remote Sandbox Files via System File Explorer 1. In the BlueRock Connector application, select the **Browse Files** option.
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.
## BlueRock Connector Command-Line Interface Features The BlueRock Connector provides a Command-Line Interface (CLI) for advanced configurations on macOS. Developers must use the CLI to configure remote shares and manage manual port forwarding, as the graphical menu bar application does not include interfaces for these features. ### Remote Shares Remote shares mount external network storage directly into the sandbox. {% hint style="success" icon="lightbulb-exclamation-on" %} **Important:** The system refuses the `cobalt up --share` command on an existing sandbox. Shares require container recreation. Destroy the existing sandbox using the `cobalt destroy` command before creating a new sandbox with shares. {% endhint %} #### Creating a Sandbox with a Share 1. Define the share parameters using the `--share` flag with the `cobalt up` command. 2. Add an additional `--share` flag for each required mount. 3. Execute the `ls` command inside the sandbox to verify the mount target. **Network File System (NFS) Example for Amazon Web Services (AWS) Elastic File System (EFS):** ```bash cobalt up --share 'type=nfs,server=fs-0123.efs.us-east-1.amazonaws.com,export=/,target=/home/ubuntu/efs' ``` **Server Message Block (SMB) Example for Azure Files:** {% hint style="success" icon="lightbulb-exclamation-on" %} **Important:** Exposing credentials causes security vulnerabilities. Never type the Server Message Block (SMB) password directly in the command line. Store the password in an environment variable. {% endhint %} ```shellscript export AZ_KEY='' cobalt up --share 'type=cifs,server=acct.file.core.windows.net,export=data,target=/mnt/data,user=acct,password-env=AZ_KEY' ``` #### Share Configuration Parameters The `--share` flag accepts a comma-separated list of key-value pairs.
KeyMeaning
type=nfs or type=cifsRequired. The storage type. The system accepts smb as an alias for cifs.
server=Required. The hostname or Internet Protocol (IP) address of the file server.
export=Required. The NFS export path (must start with /) or the SMB share name.
target=Required. The absolute path inside the sandbox.
roMounts the storage as read-only.
user=The SMB username.
password-env=VARThe SMB password, read from the specified environment variable.
opt=key=valueAn extra mount option. This key is repeatable.
### Port Forwarding The BlueRock Connector relays a TCP server running inside the sandbox to the local machine. {% hint style="info" icon="notes-sticky" %} **Note:** The BlueRock Connector menu bar application does not display forwarded ports. Execute the `cobalt bridge` command in a local terminal to view active forwards. {% endhint %} #### Automating Forwards with Claude Code The Claude Code agent handles port forwarding automatically for development servers. 1. Ensure the sandbox is running. The BlueRock Connector menu bar application maintains the bridge connection automatically. 2. Select Connect Claude in the BlueRock Connector menu bar to initiate the agent. 3. Instruct the agent to build and start a web server. 4. The agent writes the code, starts the server inside the sandbox, and publishes the port. 5. Open the provided local address (e.g., `http://127.0.0.1:3000`) in a web browser. #### Manual Port Forwarding To publish a server manually, use the `.bluedev-relay` command directly inside the sandbox terminal: ```shellscript # Start a server listening on 127.0.0.1 python3 -m http.server 3000 --bind 127.0.0.1 & # Publish the port to the local machine. The system prints the local address. /.bluedev-relay expose 3000 ``` #### Specifying a Local Port To pin a specific local port to a sandbox port, execute the `cobalt bridge` command with the `-L` flag on the local machine: ```shellscript # Map local port 8080 to sandbox port 3000 cobalt bridge -L 8080:3000 ``` The `-L` flag is repeatable. The system does not count these manual forwards toward the 16-forward limit. #### Sandbox Terminal Commands The following commands manage port forwards from within the sandbox terminal: * `/.bluedev-relay expose 3000` publishes sandbox port 3000. * `/.bluedev-relay expose 8080 3000` requests mapping local port 8080 to sandbox port 3000. * `/.bluedev-relay list` displays all current forwards. * `/.bluedev-relay unexpose 3000` terminates the forward for sandbox port 3000. ## OTEL Events The BlueRock Connector application enables developers to launch a remote sandbox container and execute coding agents within a secure workspace. Executing the coding agent inside the BlueDev Sandbox container on the BlueRock host provides visibility into agent activities and enforces security policies at runtime. To provide this visibility, the system generates OTEL events from two primary sources and forwards both event streams to the external OTEL collector target configured in the `bluerockd.toml` file: * **BlueRock Sensor Events:** \ The BlueRock Sensor module generates OTEL events for actions occurring within the remote sandbox container, including process creation, file access, tool calls executed by the agent, and MCP server responses. * **Agent Native OTEL events:** \ The system captures standard OTLP events generated directly by coding agents, such as Claude, Codex, and Gemini. These events provide visibility into LLM conversations and token usage. The system continuously combines these two event streams and forwards the unified telemetry to the external OTLP target specified in the host's `bluerockd.toml` configuration file. This routing ensures that AWS CloudWatch captures, structures, and displays all coding agent and container actions, providing administrators with a centralized dashboard for security and operational analysis. For example, the following CloudWatch OTEL log shows an OTEL event of `sensor_startup` lifecycle event emitted by `bluerockd` when the identity monitoring agent binary initializes on a host. {% code overflow="wrap" %} ```json { "body": { "file_path": "/opt/bluerock/bin/blueclaude", "pid": 00000, "principal": "@.com" }, "severity_number": 9, "severity_text": "INFO", "attributes": { "component_id": "default/xxx-xxx-xxx-xxx-xxx", "domain": "gyro", "event_name": "sensor_startup", "hostid": "ip-", "origin": "blueclaude", "sensor_id": 0000, "source_event_id": 0, "type": "sensor_lifecycle" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` {% endcode %} OTEL event in AWS CloudWatch:
Another example is an OTEL event `claude_hook` event emitted by `bluerockd` when a new Claude session (`SessionStart`) initializes within a user's workspace context. {% code overflow="wrap" %} ```json { "body": { "context": { "process": { "pid": 00000 } }, "cwd": "/home//", "hook_event_name": "SessionStart", "session_id": "xxx-xxx-xxx-xxx-xxx", "source": "startup", "transcript_path": "/home//.claude/projects/xxx/xxx.jsonl" }, "severity_number": 9, "severity_text": "INFO", "attributes": { "component_id": "default/xxx-xxx-xxx-xxx-xxx", "domain": "gyro", "event_name": "claude_hook", "hostid": "ip-", "origin": "blueclaude", "sensor_id": 0000, "source_event_id": 1, "type": "event" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` {% endcode %} OTEL event in AWS CloudWatch:
## Maintenance and Troubleshooting ### Exporting Connector Logs Administrators and support teams require connector logs to diagnose connection failures, session drops, or authentication errors. The application exports these logs in `.jsonl` (JSON Lines) format, which allows log explorers and parsing tools to easily analyze structured system events, authentication statuses, and error codes. For example, an exported log file contains structured entries such as: ```json { "arch": "aarch64", "argv": [ "/private/var/folders/***/BlueRock Connector.app/Contents/MacOS/BlueRockConnector", "wizard" ], "config": { "cert": false, "enrolled": false }, "event": "session", "git_commit": "6ac14c5a1ce5", "hostname": "**********.local", "level": "INFO", "os": "macos", "pid": 92636, "session": "20260916T100445-******", "surface": "wizard", "target": "cobalt", "ts": "2026-09-16T10:04:45.677Z", "version": "0.3.0" } ``` To export the application logs: 1. Right-click the **BlueRock Connector** icon in the macOS Menu Bar. 2. Select **Export Logs....**
3. Save the generated `.jsonl` log file to a preferred local directory. ### Session Expiration The BlueDev Identity Server enforces session time limits to protect the development environment. When a user session certificate expires, the system automatically logs the user out of the SSH session, unmounts the remote sandbox file system, and stops the sandbox container. The system does not terminate the container. The remote workspace remains intact and resumes after developers sign in again and start the container. The application displays an expiration notification. To reconnect to the host virtual machine, select **Sign in again**.
And complete the authentication flow in the web browser.
### Network and SSH Disconnection If a network issue abruptly closes the SSH session to the sandbox container, the system initiates a one-minute disconnect grace period. If the SSH session to the sandbox container closes normally, the system initiates a 10-minute idle grace period. If the connection does not resume within the respective grace period, the system stops the sandbox container. Select **Start Sandbox** to restart the container and resume the session.
### Resetting Connector Configuration Resetting the connector configuration clears local connection settings, the user SSH certificate, and authentication states to resolve persistent connectivity issues and prepare the application for a fresh enrolment. To reset the configuration and recover the connection: 1. Select **Reset Connector** in the Sandbox dialog box.
2. Select the **Confirm** button in the prompt to clear the current configuration. {% hint style="info" icon="notes" %} **Note:** The application does not automatically re-enroll after a reset. Repeat the enrollment steps to reconnect. The system reconnects to the existing sandbox and preserves the workspace, provided the enrollment uses the same SSO URL and target host. {% 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/bluerock-documentation-2.7.0-beta/bluedev-container/bluerock-connector-for-claude-and-codex-ide/bluerock-connector-macos.md?ask=&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.