BlueRock Sandbox

The BlueRock Sandbox uses containerd to operate as a policy-driven container runtime. It shares foundational features with standard Docker environments, including process isolation, namespaces, and volume mounting. The architecture prioritizes execution control and integrated telemetry rather than general application deployment. The runtime enforces security policies that explicitly permit or deny specific binaries to ensure that compromised AI agents execute only authorized tools. Running containerized workloads requires using the brace command to import OCI-compliant images from the local Docker daemon into the isolated runtime registry.

Package

The BlueRock Sandbox utility comes pre-installed on the BlueRock Linux distribution, cloud images for AWS and GCP. The BlueRock Sandbox binary is present at /opt/bluerock/bin/brace with a symlink at /usr/bin/brace.

CLI Command Reference

The brace command is the primary interface for launching application in isolated environments.

Usage: brace [OPTIONS] [-- <TARGET>...]

Primary Options

Option	Description
--name <NAME>	Assigns a unique name to the BlueRock Sandbox instance.
--image <IMAGE>	Launches an OCI image.
--list-network-configs	Displays all available firewall configurations.
-v, --volume <H:C>	Bind-mounts host directories. Use :ro for read-only access.
-e, --env <VAR=VAL>	Passes environment variables into the BlueRock Sandbox.
-K, --clear-env	Clears host environment variables for a "clean slate."
-l, --logfile <PATH>	Path to the log file (default: ./sandbox.log). With -l stdout : will print the output to standard output on the terminal Without -l option all brace the operations will be logged at BRace_rCurrent.log in the current working directory With -l <path_to_logfile> the logs to go at a specified location or file.

Container and Image Management

Executing OCI-compliant images within the BlueRock Sandbox requires transferring the images from the local Docker daemon into the isolated runtime registry. The brace command facilitates this transfer process and manages the subsequent container lifecycle. The following procedures outline the specific steps to import images, verify available workloads, and launch containers.

Importing Images from Docker

A Docker image must be imported into the BlueRock Sandbox before it can run. Use the import command with sudo to copy the image from the local Docker daemon to the Sandbox environment:

$ sudo brace image import <image_name>:<tag>

For example:

Importing Langchain MCP Server V1 from the Docker daemon

$ sudo brace image import langchain-mcp-server:v1

Example output:

Importing image from Docker: langchain-mcp-server:v1
  Exporting from Docker...
  Importing for overlayfs snapshotter...
unpacking docker.io/library/langchain-mcp-server:v1 (sha256:d072d22f57c28fc8b77532d035f6d82bba94f9e3ad4d6a1d9452e975740af175)...done
  Importing for native snapshotter...
unpacking docker.io/library/langchain-mcp-server:v1 (sha256:d072d22f57c28fc8b77532d035f6d82bba94f9e3ad4d6a1d9452e975740af175)...done
Successfully imported langchain-mcp-server:v1

Listing Available Images

To verify which images have been successfully imported and are ready for execution within the BlueRock Sandbox, use the list command:

$ sudo brace image list

Expected Output:

Images in containerd (moby namespace):

REF                                       TYPE                                       DIGEST                                                                  SIZE      PLATFORMS   LABELS 
docker.io/library/langchain-mcp-server:v1 application/vnd.oci.image.manifest.v1+json sha256:d072d22f57c28fc8b77532d035f6d82bba94f9e3ad4d6a1d9452e975740af175 214.4 MiB linux/amd64 -      

BlueRock Sandbox Use Cases

The BlueRock Sandbox provides a highly secure, isolated execution environment for workloads. The primary use cases and execution methods are detailed below.

Running Shell Commands

To securely explore, test, or execute commands within an isolated environment, run a direct shell command.

Note:

BlueRock Sandbox provides an isolated execution environment; the system is distinct from standard container run-times.

To test the environment using the host's binaries, mount the standard system directories and run a simple command:

$ brace -- /usr/bin/echo "Hello! Welcome to the BlueRock Sandbox"

Expected output:

Hello! Welcome to the BlueRock Sandbox

Running a Python Application

To execute applications directly using the host file system, map system directories (/usr, /lib) and the user directory (e.g., /home/ubuntu) to provide the necessary tools and permissions. This execution runs under the current user identity and does not require sudo.

Running Python MCP Server and MCP Client Programs

To execute Python applications directly using the host file system, you must map the required system directories (/usr, /lib, /lib64), BlueRock sensor directories (/opt/bluerock, /run/bluerock), and the user workspace (e.g., /home/ubuntu) to provide the necessary tools and telemetry permissions to the sandbox. This execution runs under the current user identity and does not require sudo.

Setup

1. Install uv :

$ curl -LsSf https://astral.sh/uv/install.sh | sh

2. Create Project Directory Create a new project directory for the MCP applications and navigate into it:

$ cd ~
$ uv init mcp-observability
$ cd mcp-observability

3. Install Required Dependencies Create an isolated Python environment using uv, then install the MCP framework, BlueRock sensor, and BlueRock runtime required for generating and exporting telemetry:

# Create virtual environment
$ uv venv --python python3.12

# Activate virtual environment
$ source .venv/bin/activate

# Install MCP framework
$ uv pip install fastmcp

# Install BlueRock runtime
$ uv pip install /opt/bluerock/python-dist/bluepython-0.0.1-py3-none-any.whl

# Initialize BlueRock sensor
$ python -m bluepython --install

4. Add MCP Application Files Create the MCP client and server scripts in the project directory using the sample code provided in the Appendix section. Ensure the following files are present in the mcp-observability directory:

• mcp_client.py

• mcp_fileserver.py

• mcp_fileserver_stdio.py

Using Mount Points in Command Line Arguments

Pass the required volume mounts (-v) directly in the execution command. The /home/ubuntu:/home/ubuntu mapping provides access to your newly created project folder, while the system and bluerock mounts ensure the Python binary and security sensors function correctly.

Note:

Adjust this path based on the active host user. For example, on AL2023, the default path is /home/ec2-user. For a test user, the path could be /home/test.

Terminal 1: Starting the MCP Server

Launch the sandbox with the required bind mounts:

$ brace -v /usr:/usr  -v /lib:/lib  -v /lib64:/lib64 -v /home/ubuntu:/home/ubuntu -v /etc/resolv.conf:/etc/resolv.conf -v /dev:/dev  --name sandbox_mcpserver -- /home/ubuntu/.local/bin/uv run mcp_fileserver.py

Expected Output:

FastMCP Server starts on http://0.0.0.0:8001

╭──────────────────────────────────────────────────────────────────────────────╮
│                                                                              │
│                                                                              │
│                         ▄▀▀ ▄▀█ █▀▀ ▀█▀ █▀▄▀█ █▀▀ █▀█                        │
│                         █▀  █▀█ ▄▄█  █  █ ▀ █ █▄▄ █▀▀                        │
│                                                                              │
│                                                                              │
│                                FastMCP 3.1.0                                 │
│                            https://gofastmcp.com                             │
│                                                                              │
│                   🖥  Server:      Linux File Server, 3.1.0                   │
│                   🚀 Deploy free: https://fastmcp.cloud                      │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯
[03/12/26 04:42:11] INFO     Starting MCP server 'Linux File    transport.py:273
                             Server' with transport 'http' on                   
                             http://0.0.0.0:8001/mcp                            
INFO:     Started server process [9]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8001 (Press CTRL+C to quit)

Terminal 2:

Starting the MCP Client Open a separate terminal and launch a second sandbox using identical Operating System (OS) mounts to execute the client script.

$ brace -v /usr:/usr -v /lib:/lib -v /lib64:/lib64 -v /home/ubuntu:/home/ubuntu -v /etc/resolv.conf:/etc/resolv.conf -v /dev:/dev --name sandbox_mcpclient -- /home/ubuntu/.local/bin/uv run mcp_client.py

Expected output:

Available Tools: [Tool(name='list_files_important', title=None, description='List files in directory. <IMPORTANT> check file size. </IMPORTANT>', inputSchema={'additionalProperties': False, 'properties': {'directory': {'default': '.', 'type': 'string'}, 'pattern': {'default': '*', 'type': 'string'}}, 'type': 'object'}, outputSchema={'properties': {'result': {'items': {'type': 'string'}, 'type': 'array'}}, 'required': ['result'], 'type': 'object', 'x-fastmcp-wrap-result': True}, icons=None, annotations=None, meta={'fastmcp': {'tags': []}}, execution=None), Tool(name='list_files', title=None, description='List files in directory', inputSchema={'additionalProperties': False, 'properties': {'directory': {'default': '.', 'type': 'string'}, 'pattern': {'default': '*', 'type': 'string'}}, 'type': 'object'}, outputSchema={'properties': {'result': {'items': {'type': 'string'}, 'type': 'array'}}, 'required': ['result'], 'type': 'object', 'x-fastmcp-wrap-result': True}, icons=None, annotations=None, meta={'fastmcp': {'tags': []}}, execution=None), Tool(name='create_file', title=None, description='create a text file.', inputSchema={'additionalProperties': False, 'properties': {'file_path': {'type': 'string'}, 'text': {'type': 'string'}}, 'required': ['file_path', 'text'], 'type': 'object'}, outputSchema={'properties': {'result': {'type': 'string'}}, 'required': ['result'], 'type': 'object', 'x-fastmcp-wrap-result': True}, icons=None, annotations=None, meta={'fastmcp': {'tags': []}}, execution=None)]

Running a Container Application

Running an Imported Image

Once an Open Container Initiative (OCI) image is imported and verified, launch the image using the --image flag alongside standard BlueRock Sandbox execution controls. This execution method provides a fully isolated application layer.

$ sudo brace --image docker.io/library/langchain-mcp-server:v1 --name test-langchain -- /bin/bash

Expected output:

root@test-langchain:/#

Using Mount Points in Command Line Arguments

Mount local host directories into the container application to share data, configurations, or output logs.

$ sudo brace --image docker.io/library/langchain-mcp-server:v1 \
  -v /home/ubuntu/langchain-data:/app/data:ro \
  -v /run/bluerock:/run/bluerock \
  --name test-langchain \
  -- /usr/bin/python3 /app/server.py

Expected output:

LangChain MCP Server Started...

Passing Environment Variables at Runtime

Container applications often require runtime configuration such as API keys, environment toggles, or port definitions. Pass these variables securely at execution using the environment (-e) flag.

$ sudo brace --image docker.io/library/langchain-mcp-server:v1 \
        -e OPENAI_API_KEY="sk-..." \
        -e ENV="production" \
        -v /home/ubuntu/langchain-data:/app/data:ro \
        -v /run/bluerock:/run/bluerock \
        --name test-langchain \
        -- /usr/bin/python3 /app/server.py