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

# BlueRock Connector for VS Code

The BlueRock Connector extension authenticates to connect to and execute the BlueRock instance VM, and to run Sandbox containers from VS Code.

This document details the configuration, authentication, and access requirements for the BlueRock Connector VS Code extension. 

#### Setup and Configuration Workflow

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

1. [**Prerequisites**](#prerequisites)
2. [**Host Enrollment**](#host-enrollment)
3. [**VS Code Identity Configuration**](#setting-up-the-identity)
   1. [BlueRock Identity Service](#bluerock-identity-service)
   2. [SSH Key Trust](#ssh-key-trust)
4. [**Working with Containers**](#working-with-containers)
   1. [Creating a Container using Catalog](#creating-a-container-using-catalog)
   2. [Creating a Container using a Git Repo](#creating-a-container-using-a-git-repo)
5. [**Manage Containers**](#manage-containers)
6. [**OTEL Events**](#otel-events)

### Prerequisites

* [VS Code](https://code.visualstudio.com/) (latest version)
* Remote - SSH extension (from Microsoft VS Code Marketplace)
* BlueRock Connector VS Code Extension (from Microsoft VS Code Marketplace).<br>

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

{% hint style="warning" %}
**Windows System Requirements:**

The **BlueRock Connector** requires the **Microsoft Visual C++ Redistributable** package `VCRUNTIME140.dll` to function correctly on **Windows**. Ensure optimal performance by installing this package via the terminal before launching the connector:

```shellscript
winget install Microsoft.VCRedist.2015+.x64
```

{% endhint %}

#### Host Enrollment

Run the BlueRock host enrollment directly on the BlueRock instance VM before configuring the BlueRock Connector in VS Code.

1. Access the BlueRock instance VM terminal.
2. Run the following command to enroll the `bluedev-bouncer`:

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

   \
   Enter the `BOUNCER_PASSWORD` when prompted.
3. Construct the `<bootstrap-URL>` by combining the instance's Public DNS (or IP address) and the appropriate SHA256 fingerprint:&#x20;

   ```
   https://<instance-public-DNS>#fp=<sha256>
   ```

   1. **Obtaining the Public DNS / IP Address**

      Navigate to the respective cloud provider console such as AWS, GCP, or Azure to locate the public address of the BlueRock instance:
   2. **Obtaining the Fingerprint (`<sha256>`)**

      The required fingerprint depends on the chosen authentication method for the workspace:

      * **For BlueRock Identity Service (OIDC):** The fingerprint is the SHA-256 hash of the CA certificate. Retrieve this directly from the identity service administrator, or by running `just fingerprint --auto` on the CA host. For more details, refer to the [BlueDev Identity Development Kit](/bluedev-container/bluedev-identity-deployment-kit.md).
      * **For SSH Key Trust:** The fingerprint is the host's SSH key fingerprint. Retrieve it by running the following command on the local machine, replacing `<host-ip>` with the public address obtained above:

        Bash

        ```shellscript
        ssh-keyscan -t ed25519 <host-ip> | ssh-keygen -lf -
        ```

### Setting up the Identity

Once the BlueRock Connector extension is installed, restart VS Code. The extension will load in the left panel. In the extension, select the **Setup** button to configure the BlueRock Instance using either of the following authentication methods.

1. BlueRock Identity Service
2. SSH key trust

#### BlueRock Identity Service

1. Select the **Enroll with identity service...** button.<br>

   <figure><img src="/files/rDHfaDTVz5Pxvqs5rBUv" alt=""><figcaption></figcaption></figure>
2. Insert the [**`Bootstrap URL`**](#host-enrollment) .

   ```shellscript
   https://<instance-public-DNS>#fp=<sha256>
   ```
3. Enter the Public DNS or IP Address of the instance and select **Enroll**.

   <figure><img src="/files/ythcIJTrBIr5RroR3Yxs" alt=""><figcaption></figcaption></figure>
4. Select **Sign-in** and complete the authentication on the browser.<br>

   <div align="left"><figure><img src="/files/ih78n4IvUHon2UUyKNNf" alt=""><figcaption></figcaption></figure></div>
5. After successful authentication, the left panel will show the green icon next to the identity and host.<br>

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

When authenticated with the identity service, the following files are created on the BlueRock instance:

{% code overflow="wrap" %}

```shellscript
$ ls -l .config/bluedev/identity/
total 12
-rw------- 1 bluerock bluerock  200 Jun 30 08:56 config.toml
-rw------- 1 bluerock bluerock  179 Jun 30 08:57 known_hosts
drwx------ 2 bluerock bluerock 4096 Jun 30 08:56 trust

$ cat .config/bluedev/identity/config.toml 
schema_version = 1
service_url = "https://<url>"
default_provisioner = "google"
tls_trust_mode = "system"

[host]
address = "0.101.010.0"
user = "bluedev"
```

{% endcode %}

#### SSH key trust

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

If **BlueRock Identity Service** is previously configured, then unenroll the bouncer on the host instance first to prevent configuration conflicts before switching to the **SSH Key Trust**:

{% code overflow="wrap" %}

```shellscript
$ sudo bluedev-bouncer unenroll
```

{% endcode %}
{% endhint %}

1. Select the **Set up SSH key Trust...** button to enroll using an existing SSH key.

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

   \
   Insert the Bootstrap string with the following format

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

   \
   For example:

   ```
   10.101.01.101#fp=SHA256:0x0x0xx00xxx0xx0000x000xxx000000xx0x0x00x00xx0x000x0000xx000x00x/mU
   ```
3. Select **Verify**, and once verified, select **I have compared these and they match - Next** button.<br>

   <figure><img src="/files/VR1N9vrBLrtQLnKZORbf" alt=""><figcaption></figcaption></figure>
4. Select the required key from the local `.ssh` folder or select **Use another key file...** to browse the other keys. Click the **Configure** button.

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

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

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

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

{% endhint %}

### Working with Containers

#### Creating a Container using Catalog

Once the instance is successfully connected to VS Code, create containers using a pre-built template from the Catalog. These reside at the `/srv/bluedev/catalog` in the BlueRock instance with packages at `/srv/bluedev/packages`.&#x20;

By default, the BlueRock Instance ships the following catalog containers:

* **Claude workload sandbox**:\
  It’s a template specifically for the Claude IDE for dev containers.
* **Fedora - BlueRock dev**:\
  It’s a template with a Fedora environment for dev containers.
* **Ubuntu - BlueRock dev**:\
  It’s a template with an Ubuntu environment for dev containers.

To launch them in VS Code, select the **Arrow** icon next to the container template. It will create the Container and connect it automatically. For example, starting an **Ubuntu - BlueRock dev** container

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

Then the Ubuntu Container will be created on the fly and load in a new VS Code window with all its files.&#x20;

While loading, click the **Connecting to Dev Container (show log)** dialog box

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

To trust the authors of the files and folders\
![](/files/55xgKdcWsrSAosazHtXk)

Also loads pre-installed packages such as Claude, Gemini, and Codex in the container. Authenticate the package with the required account to run within the container.&#x20;

For example, using Claude to create a dummy shell script in the Ubuntu container.

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

#### Creating a Container using a Git Repo

Select the Repo tab and paste the GitHub/GitLab repo link that has `devcontainer.json` . Click **Warp**; it will fetch the `devcontainer.json`.

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

For the first time on a new repo, it will prompt to **Trust this repo** to build and create hooks defined in the repo.&#x20;

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

Also, provide the Personal Access Token (PAT) of your GitLab/GitHub account once prompted.

Select the Container based on the options from the `devcontainer.json` file.&#x20;

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

Then it will clone the repo, create the container, and open it in a new VS Code window.

### Manage Containers

Select the **Containers** tab to manage the Containers created with different icons.&#x20;

* **Arrow** icon to attach the container in a new VS Code window.
* **Pen** icon to rename the container.
* **Square** icon to stop the running container.
* **Bin** icon to destroy the container and its content from VS Code and the host.

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

### OTEL Events

In CloudWatch, all events are captured for all actions triggered on any Container from VS Code. \
\
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": "<user_email>@<domain>.com"
    },
    "severity_number": 9,
    "severity_text": "INFO",
    "attributes": {
        "component_id": "default/xxx-xxx-xxx-xxx-xxx",
        "domain": "gyro",
        "event_name": "sensor_startup",
        "hostid": "ip-<ip_address>",
        "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:

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

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/<username>/<workspace_dir>",
        "hook_event_name": "SessionStart",
        "session_id": "xxx-xxx-xxx-xxx-xxx",
        "source": "startup",
        "transcript_path": "/home/<username>/.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-<ip_address>",
        "origin": "blueclaude",
        "sensor_id": 0000,
        "source_event_id": 1,
        "type": "event"
    },
    "scope": {
        "name": "bluerockd"
    },
    "resource": {
        "service.name": "bluerock"
    }
}
```

{% endcode %}

OTEL event in AWS CloudWatch:

<figure><img src="/files/0FQuKTYknqTP5ba3JlWT" alt=""><figcaption></figcaption></figure>


---

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