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

# BlueRock Connector for Claude and Codex IDE

BlueRock Connector ships the application for [Windows](#prerequisites) and [macOS](#prerequisites) 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](#prerequisites)
2. [Installation (Windows)](#installation-windows)
3. [Authentication & Enrollment](#authentication-and-enrollment)
   1. [SSO (Google OAuth or Microsoft Entra ID)](#sso-google-oauth-or-microsoft-entra-id)
   2. [SSH Key](#ssh-key)
4. [Environment Lifecycle Management](#environment-lifecycle-management)
5. [Connecting AI Tools & 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 & Script Output](#verifying-session-execution-and-script-output)
   4. [Browsing Remote Sandbox files via System File Explorer](#browsing-remote-sandbox-files-via-system-file-explorer)
6. [Maintenance & Troubleshooting](#maintenance-and-troubleshooting)

### Prerequisites

* [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 get the BlueRock Connector app)
  * For Windows: `BlueRock_Connector_win64.exe` 
  * For macOS: `BlueRock-Connector-notarized.zip`

### Installation (Windows)

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

{% hint style="info" icon="notes-sticky" %}
**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.

<img src="/files/OiCfwZUmnVZNban4o3OF" alt="" data-size="original">
{% endhint %}

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

<div align="left"><figure><img src="/files/tASfshVvMJhZ0q0h99Gt" alt=""><figcaption></figcaption></figure></div>

### Installation (macOS)

Locate and unzip the `BlueRock-Connector-notarized.zip` to extract the application and double-click to run it.&#x20;

<div align="left"><figure><img src="/files/CffLXCw0z5z4fhPXghrp" alt=""><figcaption></figcaption></figure></div>

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

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

![](/files/iyTS5qTRmhUMNPfunvlT)
{% endhint %}

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

<figure><img src="/files/q8YUjHZtU2RvNC39cjfu" alt=""><figcaption></figcaption></figure>

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

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

### Authentication & Enrollment

Once the application opens, select the **Set Up Connector** button.

<div align="left"><img src="/files/2PiMBUwBPWeKSZqbg8xx" alt="" height="219" width="350"></div>

Then select **Continue** on the next screen

<div align="left"><img src="/files/SURIh81f7RcB7vJJBMeg" alt="" height="247" width="350"></div>

Log in and enroll using one of two methods:&#x20;

* **SSO** (recommended)
* **SSH Key**

<div align="left"><img src="/files/Jg28VdWlVFALyOt9GjOH" alt="" height="242" width="350"></div>

#### SSO (Google OAuth or Microsoft Entra ID)

Run the following command on the instance to enroll the bluedev bouncer before clicking on the **SSO (recommended)**:

{% code overflow="wrap" %}

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

## Enter the BOUNCER_PASSWORD when prompted
```

{% endcode %}

1. Select the **SSO (Recommended)** 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**:

   <div align="left"><img src="/files/PEa00kQfSMI5f3Lx3Pdd" alt="" height="247" width="350"></div>
3. This action automatically redirects you to your web browser for authentication.<br>

   <div align="left"><img src="/files/AwKO5y5V4paFDOUjV1aW" alt="" height="247" width="350"></div>
4. Complete the sign-in flow in your browser to bring up and authorize. Once successfully authenticated, the following log appears.<br>

   <div align="left"><img src="/files/GSiWAaH8xE31P1mDePgs" alt="" height="168" width="350"></div>

#### SSH Key

Select the **SSH key** login option.

<div align="left"><img src="/files/UWLKcb0qux4H3kTQDeo5" alt="" height="242" width="350"></div>

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

   <pre class="language-shellscript" data-overflow="wrap"><code class="lang-shellscript">ssh-keyscan -T 10 -t ed25519 &#x3C;host-ip> | ssh-keygen -lf - 2>&#x26;1
   </code></pre>
2. Insert the Bootstrap string in the following format:

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

   \
   For example:

   ```shellscript
   10.101.01.101#fp=SHA256:0x0x0xx00xxx0xx0000x000xxx000000xx0x0x00x00xx0x000x0000xx000x00x/mU
   ```

   <div align="left"><figure><img src="/files/UjBm6gjyAgSnWWHpsR9P" alt=""><figcaption></figcaption></figure></div>

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

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

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

{% code overflow="wrap" %}

```shellscript
## 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
```

{% endcode %}
{% endhint %}

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

<div align="left"><figure><img src="/files/QrYITQ3cHqnx7VcRLCtR" alt=""><figcaption></figcaption></figure></div>

### Environment Lifecycle Management

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

BlueRock Connector app supports a single container environment only.
{% endhint %}

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

  <div align="left"><img src="/files/GGGrFEIksWdD7SqNiG0d" alt="" height="191" width="350"></div>
* **Monitoring Active Sandbox Status and Session Expiration**\
  Verify that it is running by executing `docker ps` directly on your BlueRock instance.

  <div align="left"><img src="/files/NptmxfE9VxsOsbM7Gegg" alt="" height="107" width="350"></div>
* **Extend session duration**\
  In the Create Sandbox dialog box, click **Extend** the signed-in session.\
  ![](/files/9X4aQHdzS7RTTdVzUSZe)
* **Stop Sandbox**: \
  Click **Stop Sandbox** to halt your running container. Verifying the container status on the BlueRock instance will confirm that it has stopped.

  <div align="left"><figure><img src="/files/BLO63RaCI95fXVOhpN6W" alt=""><figcaption></figcaption></figure></div>

  \
  **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.\
  ![](/files/Icp0slpniJsqKzFhP4s0)
* **Destroy Environment**: \
  Click **Destroy Sandbox** to completely purge and delete the container instance from the host.

  <div align="left"><figure><img src="/files/H62C23pZquwMfYEOACeE" alt=""><figcaption></figcaption></figure></div>

  \
  It will prompt to confirm destroying the sandbox completely.

  <div align="left"><figure><img src="/files/Ayk4SwlrGu5ZMMjzM0X0" alt=""><figcaption></figcaption></figure></div>

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

   <div align="left"><figure><img src="/files/KfPVF9I2aNfJmpCFXRXa" alt=""><figcaption></figcaption></figure></div>

   \
   For macOS:

   <div align="left"><figure><img src="/files/dbtPGftHxyOWk23Dp84X" alt=""><figcaption></figcaption></figure></div>
2. Select Open Claude Desktop and follow the instructions given on the screen.

   <div align="left"><img src="/files/OQJ6ngF5Pg0a2SkwnzYd" alt="" height="420" width="350"></div>

   \
   For macOS:

   <div align="left"><figure><img src="/files/CpHDKc9mU4m8xtHnoAdn" alt=""><figcaption></figcaption></figure></div>
3. In the Claude IDE:
   1. Click on the **Code** menu option.
   2. Select **Local**.

      <figure><img src="/files/Jcr2Jfyx3mwT8Mek6zsV" alt=""><figcaption></figcaption></figure>
   3. Select **Add SSH Host**.

      <div align="left"><figure><img src="/files/YcVEdZ2EoVJgnUyO6Rrd" alt=""><figcaption></figcaption></figure></div>
   4. Enter `cobalt-59` in the **SSH Host** field in the hostname prompt.

      <figure><img src="/files/c0QaIkOQIYAAqGB0WI00" alt=""><figcaption></figcaption></figure>
   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.

      <figure><img src="/files/aMNtbbVMMYMUklyVAmN5" alt=""><figcaption></figcaption></figure>

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

OTEL events are generated by the `blueclaude_sensor` for all the actions done by the coding agent running inside the remote container.
{% endhint %}

#### Connecting to Codex

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

1. Select the **Connect Codex** button.

   <figure><img src="/files/MkROdJhYEx6rSU1OC9KP" alt=""><figcaption></figcaption></figure>

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.

   <figure><img src="/files/jsYHYd4xonssIglOEhPN" alt=""><figcaption></figcaption></figure>

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

   <figure><img src="/files/f1o8KZe2WbjNLjilgkHl" alt=""><figcaption></figcaption></figure>

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

   <div align="left"><figure><img src="/files/pJWNJrc53JebBxXte8UP" alt=""><figcaption></figcaption></figure></div>

5. Upon completion of OpenAI account setup, the BlueRock Bridge app gives a new prompt to **Open Codex Settings**.

   <div align="left"><figure><img src="/files/s8IX1llwHCN9Iv9RLm9i" alt=""><figcaption></figcaption></figure></div>

6. In Codex, navigate to **Connections** > select **SSH** > click **Add**.

   <div align="left"><figure><img src="/files/dbWpRv2245ASXmTxfQKO" alt=""><figcaption></figcaption></figure></div>

7. Select Remote and click Next.

   <div align="left"><figure><img src="/files/vF02BnjPg9BYlIhVzZOx" alt=""><figcaption></figcaption></figure></div>

8. Select **cobalt-59** and click Add.

   <div align="left"><figure><img src="/files/40bOdaHNET24EinXVpzR" alt=""><figcaption></figcaption></figure></div>

9. In the New Remote Project pane, select **cobalt-59** from the Remote dropdown and select Add Project.\
   ![](/files/WlYg6Vlo01fO8y39dDyF)

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

<div align="left"><figure><img src="/files/MkSXMP8AlIoKECGPb1yl" alt=""><figcaption></figcaption></figure></div>

Then use it as a project in the Codex workspace.

<div align="left"><figure><img src="/files/7khNNGOBtsGCpeS13eYu" alt=""><figcaption></figcaption></figure></div>

#### Verifying Session Execution & Script Output

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

<figure><img src="/files/L56SmIVf6uGkuLfbKEfB" alt=""><figcaption></figcaption></figure>

Example of verifying the script output in the Claude desktop shell

<div align="left"><img src="/files/M7zdp9LI1XdbNludVQYs" alt="" height="98" width="350"></div>

#### Browsing Remote Sandbox Files via System File Explorer

Select Browse Files

<div align="left"><figure><img src="/files/p6asYcSTb5k7AvWFzMbc" alt=""><figcaption></figcaption></figure></div>

In **Windows Explorer,** it will open the files

<div align="left"><img src="/files/HEzlW9AdbnqTW05xwNfk" alt="" height="219" width="350"></div>

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

<figure><img src="/files/fyD2hKIIHYd6VMVyhRZD" alt=""><figcaption></figcaption></figure>

### Maintenance & Troubleshooting

* **Resetting BlueRock Connector Configuration:**\
  Reset the BlueRock Connector with the **Reset** option in the Sandbox dialog box.<br>

  <div align="left"><img src="/files/GFhBQGp5BSbGz8CxjeJ4" alt="" height="182" width="350"></div>

  \
  Then confirm the reset.<br>

  <div align="left"><img src="/files/WnnOdvItEsh5GfF7pkZ1" alt="" height="192" width="350"></div>

* **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,&#x20;
  * After stopping the container

    <div align="left"><img src="/files/LwynIAxpmBkFf8abCN38" alt="" height="214" width="350"></div>
  * After destroying the container

    <div align="left"><img src="/files/2vRyaKTjyPfs9DmF6kdn" alt="" height="219" width="350"></div>

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

  <div align="left"><img src="/files/krfFfMhGhwWrGCOOWY2N" alt="" height="196" width="350"></div>


---

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