BlueRock Connector - macOS

The BlueRock Connector application for macOS establishes a secure bridge between local AI IDEs (Claude Code or 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

• IDEs:

  • Claude Code IDE

  • Codex

• BlueRock Connector App: Contact BlueRock support to obtain the BlueRock-Connector-notarized.zip file.

System Requirements

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

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.

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.

Note:

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

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 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.

         
      3. Complete the sign-in flow in the web browser to authorize the application.

   2. SSH Key

      

      1. Select the SSH key option.

      2. Run the following command on the local machine to obtain the fingerprint:

         $ 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.

         

Note:

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:

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

1. 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 container.

(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.

(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.

(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.

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