For the complete documentation index, see llms.txt. This page is also available as Markdown.

BlueRock Connector - Windows

The BlueRock Connector application for Windows 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.

Setup and Configuration Workflow

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

Prerequisites

Software and Client Applications

  • BlueRock Connector App: Contact BlueRock support to obtain BlueRock_Connector_win64.exe.

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

notes

Note:

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

System Requirements

Operating System:

Windows 11 (24H2 or later) is required for file transfers between the local machine and the BlueRock environment.

lightbulb-exclamation-on

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

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

notes

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.

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 Also, known as Single Sign On (SSO) login option.

      1. Select the Sign in with BlueRock option then select Next.

      2. Provide the bootstrap string 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. SSH Key

      1. Select the SSH key option then select Next.

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

      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.

notes

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:

  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.

Stop Sandbox

Click Stop Sandbox to halt the running container.

Destroy Environment

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

Click Destroy Sandbox - confirm buttong in the prompt to destrory the sandbox and its files completely.

Connecting AI Tools and Workspace Integration

Connecting to 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 Code IDE:

    1. Click the Code menu option.

    2. Select Local > SSH > Add SSH Host...

    3. Enter cobalt-59 only in the SSH Host field, with the other details as per the requirements, and click Add SSH Connection.

Then Claude Code will SSH into the instance, and any tasks or development scripts created inside this window will now execute directly inside your active remote bluedev Docker container.

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.

Connecting to Codex

  1. Select the Connect Codex button in the Connector app.

  2. Follow the on-screen dialog instructions and click the provided link to authenticate. A one-time code is also present to enter while setting up an OpenAI account.

  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 to create a new remote project.

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

    The bluedev container mounts natively on the Windows file system under Network Locations.

BlueRock Connector Command-Line Interface Features

The BlueRock Connector provides a Command-Line Interface (CLI) for advanced configurations on Windows. 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.

lightbulb-exclamation-on

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):

Server Message Block (SMB) Example for Azure Files:

lightbulb-exclamation-on

Share Configuration Parameters

The --share flag accepts a comma-separated list of key-value pairs.

Key

Meaning

type=nfs or type=cifs

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

ro

Mounts the storage as read-only.

user=

The SMB username.

password-env=VAR

The SMB password, read from the specified environment variable.

opt=key=value

An extra mount option. This key is repeatable.

Port Forwarding

The BlueRock Connector relays a TCP server running inside the sandbox to the local machine.

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.

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.

  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:

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:

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.

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.

OTEL event in AWS CloudWatch:

Maintenance and Troubleshooting

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 and select Export Logs.... Save the generated log file to a preferred location.

Resetting Connector Configuration

Select Reset in the Sandbox dialog box.

Then confirm the prompt to clear the current configuration.

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.

  • After stopping the container

  • After destroying the container

Last updated