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 applications in isolated environments.

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

Primary Options

Option	Description
--socket <SOCKET>	Path to the sensor socket. (Default: /run/bluerock/sensor.sock)
--name <NAME>	Assigns a unique name to the BlueRock Sandbox instance. (Default: sandbox)
-l, --logfile <LOGFILE>	Path to the log file. (Default: ./brace.log)
-K, --clear-env	Clears all host environment variables for a "clean slate."
-e, --env <ENV>	Passes environment variables into the BlueRock Sandbox.
--pid <PID>	PID namespace mode: 'host' to share host PID namespace, or 'isolated' for a separate namespace (overrides config).
--mount-proc <MOUNT_PROC>	Mounts /proc inside the sandbox (overrides config). Possible values: true, false
-v, --volume <VOLUME>	Bind-mounts host directories: HOST_PATH:CONTAINER_PATH. Append :ro for read-only access (overrides config mounts).
--user-ns <USER_NS>	Runs the sandbox with an enabled user namespace. Possible values: true, false
--tmpfs <TMPFS>	Mounts a temporary file system (tmpfs) at the specified PATH inside the sandbox.
--skip-mnts	Skips all policy-configured mounts; only CLI --volume mounts will be used.
--disable-network	Disables the network namespace setup.
--nested	Runs nested inside another brace container (disables the seccomp listener).
-h, --help	Prints help information.
-V, --version	Prints version information.

Architectural Workflow

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

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

BlueRock Sandbox Container

Using Mount Points in Command Line Arguments

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

$ docker run -it --runtime io.containerd.bluerock.v2 \
  -v /home/ubuntu/langchain-data:/app/data:ro \
  -v /run/bluerock:/run/bluerock \
  --name test-langchain \
  docker.io/library/langchain-mcp-server:v1 /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.

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

Run BlueRock Sandbox Container using Docker Image

Execute OCI-compliant Docker images within the BlueRock Sandbox environment. The brace and docker command facilitates the process and manages the subsequent container lifecycle.

When launching containers, specifying --runtime io.containerd.bluerock.v2 forces the workload through a secure abstraction layer.

Containerd Shim Mode

The brace-shim natively implements the containerd shim v2 (io.containerd.bluerock.v2) to wrap runc and attach acoustic monitoring at the boundary of every container.

For example:

$ docker run -it --runtime io.containerd.bluerock.v2 ubuntu:latest bash

Terminal changes to:

root@4bc05f087a5b:/#

Native OCI Annotations

When orchestrating container deployments via standard engine runtimes, you can pass custom Open Container Initiative (OCI) annotations directly through the command line, or deployment manifests to modify runtime behavior.

Annotation	Default Value	Purpose / Behavior
io.bluerock.socket	/run/bluerock/sensor.sock	Overrides the target acoustic sensor Unix domain socket path for this specific container.
io.bluerock.principal	(None)	Specifies the principal identifier. This is written to /etc/bluerock.env inside the container rootfs so nested runtime sensors (e.g., bluepython) automatically inherit it.
io.bluerock.policy-hint	(None)	Provides a policy selection hint passed directly to bluerockd to determine which access policy applies to the workload.

Example Invocation with OCI Annotations:

docker run --runtime io.containerd.bluerock.v2 \
  --annotation io.bluerock.socket=/run/bluerock/sensor.sock \
  --annotation io.bluerock.principal=myuser \
  ubuntu:22.04 bash