Copy of BlueRock Connector for Claude and Codex IDE

BlueRock Connector ships the application for Windows and macOS both, which enables a remote coding workspace from Claude Desktop IDE by launching and managing bluedev-container onto the BlueRock Host VM and supports SSH logging to the remote bluedev-container using SSO or SSH key-based authentication.

Setup and Configuration Workflow

Follow the complete deployment path below, or jump directly to the required phase:

1. Prerequisites

   1. Software and Client Applications

   2. System Requirements

   3. Network and Security

2. Installation (Windows)

3. Installation (macOS)

4. Authentication & Enrollment

   1. SSO (Google OAuth or Microsoft Entra ID)

   2. SSH Key

5. Environment Lifecycle Management

6. Connecting AI Tools & Workspace Integration

   1. Connecting to Claude Code IDE

   2. Connecting to Codex

   3. Verifying Session Execution & Script Output

   4. Browsing Remote Sandbox files via System File Explorer

7. Maintenance & Troubleshooting

Prerequisites

Software and Client Applications

• IDEs:

  • Claude Code

  • Codex

• BlueRock Connector application: Contact BlueRock support to obtain the installation files.

  • Windows: BlueRock_Connector_win64.exe

  • macOS: BlueRock-Connector-notarized.zip

• OpenSSH Client: The client must be installed and added to the user's PATH (e.g., C:\Windows\System32\OpenSSH\).

Note:

The OpenSSH Client is an optional Windows feature and is frequently removed from hardened corporate images.

System Requirements

• Operating System (OS) version:

  • Windows: Windows 11 (24H2 or later) is required for file transfers between the laptop and the BlueRock environment.

  • macOS: Fully supported for standard Connector features on the latest macOS versions.

Important:

Install the application strictly in the user's context. Do not install the application machine-wide or via "Run as administrator" (for Windows) or root (for macOS), because the Connector stores identity locally in the user's profile.

Network and Security

• Virtual Private Network (VPN) connectivity: If the BlueRock instance resides on a private network, each laptop requires active VPN connectivity 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 (Windows)

Locate the BlueRock_Connector_win64.exe application and double-click to run it.

Note:

Windows will display a standard publisher notification warning message because the application is not from Microsoft. Proceed through the prompt to install and run the application.

Access the BlueRock Connector from the System Tray as well.

Installation (macOS)

Locate and unzip the BlueRock-Connector-notarized.zip to extract the application and double-click to run it.

Note:

When launching the app, macOS may warn that it was downloaded from the internet. Click Open to proceed.

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

Important:

While the installation prompts differ between operating systems, the functionality and performance of BlueRock Connector are the same on both Windows and macOS.

Authentication & Enrollment

Once the application opens, select the Set Up Connector button. Then select Continue on the next screen

Log in and enroll using one of two methods:

• Sign in with BlueRock

• SSH Key

Sign in with BlueRock

Run the following command on the instance to enroll the bluedev-bouncer before clicking on the Sign in with BlueRock:

$ sudo bluedev-bouncer enroll --ca <bootstrap-URL> --password

## Enter the BOUNCER_PASSWORD when prompted

1. Select the Sign in with BlueRock option.

   
2. Provide the bootstrap string URL in the Sign-in URL field in the following format: https://<identity-example>.com#fp=<sha256-hex>, and enter the public DNS of the BlueRock host in the Sandbox host field. Then click Sign in.

3. This action automatically redirects to a web browser for authentication.

4. Complete the sign-in flow in the browser to bring up and authorize. Once successfully authenticated, the following screen appears.

   

   

SSH Key

Select the SSH key login option.

1. Run the following command on the local machine to get the fingerprint (SHA256: <base 64>):

   ssh-keyscan -T 10 -t ed25519 <host-ip> | ssh-keygen -lf - 2>&1

2. Insert the Bootstrap string in the following format:

   <host-ip>#fp=SHA256:<base64>

   For example:

   10.101.01.101#fp=SHA256:0x0x0xx00xxx0xx0000x000xxx000000xx0x0x00x00xx0x000x0000xx000x00x/mU

   

   Browse and select the required SSH private key, and select Install Key.

Note:

Ensure the same SSH key is present in the .ssh folder of the instance's Bluedev profile. For that, run the following commands:

## Switch to root user
$ sudo su

## Then switch to bluedev user
$ sudo su bluedev

# Create the .ssh directory with correct permissions
$ mkdir -p ~/.ssh
$ chmod 700 ~/.ssh

# Add your local public key to authorized_keys
$ vi ~/.ssh/authorized_keys

# Set secure permissions for the authorized_keys file
$ chmod 600 ~/.ssh/authorized_keys

After this, the app will validate and authenticate based on the SSH Key.

Environment Lifecycle Management

Note:

BlueRock Connector app supports a single container environment only.

• Creating and Initializing a BlueRock Sandbox Select the Create sandbox button to create a sandbox.

  
• Monitoring Active Sandbox Status and Session Expiration Verify that it is running by executing docker ps directly on your BlueRock instance.

  
• Extend session duration In the Create Sandbox dialog box, click Extend the signed-in session.

  
• Stop Sandbox: Click Stop Sandbox to halt your running container. Verifying the container status on the BlueRock instance will confirm that it has stopped.

  

  Restart Container: If an environment has been stopped but not destroyed, a Start Sandbox option is available to restart the existing container and preserve its state.

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

  

  It will prompt to confirm destroying the sandbox completely.

  

Connecting AI Tools & Workspace Integration

Connecting to Claude Code IDE

To bridge your local Claude IDE environment with the remote container, follow these configuration steps:

1. Select the Connect Claude button.

   

   For macOS:

   
2. Select Open Claude Desktop and follow the instructions given on the screen.

   

   For macOS:

   
3. In the Claude IDE:

   1. Click on the Code menu option.

   2. Select Local.

      
   3. Select Add SSH Host.

      
   4. Enter cobalt-59 in the SSH Host field in the hostname prompt.

      
   5. Click Add SSH Connection. Any tasks or development scripts created inside this window will now execute directly inside your active remote bluedev Docker container.

      

Note:

OTEL events are generated by the blueclaude_sensor for all the actions done by the coding agent running inside the remote container.

Connecting to Codex

To bridge your local Codex environment with the remote container, follow these configuration steps:

1. Select the Connect Codex button.

   
2. Follow the instructions given in the dialog screen. Click the link given here. On this screen, a one-time code is also present to enter while setting up an OpenAI account.

   
3. Authenticate with the OpenAI/ChatGPT account on the default browser.

   
4. Enter the one-time code and select Continue.

   
5. Upon completion of OpenAI account setup, the BlueRock Bridge 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.

   

9. In the New Remote Project pane, select cobalt-59 from the Remote dropdown and select Add Project.

Once the project connetos successfully, it will be added in the SSH section

Then use it as a project in the Codex workspace.

Verifying Session Execution & Script Output

In the Claude IDE or Codex, give a prompt to create a hello Python script to verify the session.

Example of verifying the script output in the Claude desktop shell

Browsing Remote Sandbox Files via System File Explorer

Select Browse Files

In Windows Explorer, it will open the files

The bluedev Container mounts on the Windows file system under Network Location.

Maintenance & Troubleshooting

• Resetting BlueRock Connector Configuration: Reset the BlueRock Connector with the Reset option in the Sandbox dialog box.

  

  Then confirm the reset.

  

• Re-authenticating After Reset or Expiration When a session expires or after stopping/destroying containers and resetting configuration, remote network locations automatically unmount, and Docker containers terminate. Re-run Authentication and Sandbox Creation to establish a new session. On the Windows file system,

  • After stopping the container

    
  • After destroying the container

    

• Access the BlueRock Connector from the System Tray as well.

  

• Exporting Connector Logs: To troubleshoot issues, export the application logs directly from the system tray. Right-click the BlueRock Connector icon in the System Tray (or Menu Bar for macOS) and select Export Logs...