> 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/bluerock-sandbox/bluerock-sandbox.md). # 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] [-- ...]` **Primary Options** | **Option** | **Description** | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--name ` | Assigns a unique name to the BlueRock Sandbox instance. | | `--image ` | Launches an OCI image. | | `--list-network-configs` | Displays all available firewall configurations. | | `-v, --volume ` | Bind-mounts host directories. Use `:ro` for read-only access. | | `-e, --env ` | Passes environment variables into the BlueRock Sandbox. | | `-K, --clear-env` | Clears host environment variables for a "clean slate." | | `-l, --logfile ` |

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 \ 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 ```shellscript $ sudo brace image import langchain-mcp-server:v1 ``` Example output: ```shellscript 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: ```shellscript $ sudo brace image list ``` Expected Output: ```shellscript 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. {% hint style="info" icon="notes-sticky" %} **Note**: BlueRock Sandbox provides an isolated execution environment; the system is distinct from standard container run-times. {% endhint %} To test the environment using the host's binaries, mount the standard system directories and run a simple command: {% code overflow="wrap" %} ```shellscript $ brace -- /usr/bin/echo "Hello! Welcome to the BlueRock Sandbox" ``` {% endcode %} Expected output: ```shellscript 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` : ```shellscript $ 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: ```shellscript $ 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: ```shellscript # 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](/glossary/appendix.md). Ensure the following files are present in the `mcp-observability` directory: * [`mcp_client.py`](/glossary/appendix.md#mcp-client-script-python) * [`mcp_fileserver.py`](/glossary/appendix.md#mcp-file-server-http-python) * [`mcp_fileserver_stdio.py`](/glossary/appendix.md#mcp-file-server-stdio-python) **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. {% hint style="info" icon="notes-sticky" %} **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`. {% endhint %} **Terminal 1:** Starting the MCP Server Launch the sandbox with the required bind mounts: {% code overflow="wrap" %} ```shellscript $ 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 ``` {% endcode %} **Expected Output**: FastMCP Server starts on {% code overflow="wrap" lineNumbers="true" %} ```shellscript ╭──────────────────────────────────────────────────────────────────────────────╮ │ │ │ │ │ ▄▀▀ ▄▀█ █▀▀ ▀█▀ █▀▄▀█ █▀▀ █▀█ │ │ █▀ █▀█ ▄▄█ █ █ ▀ █ █▄▄ █▀▀ │ │ │ │ │ │ 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) ``` {% endcode %} **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. {% code overflow="wrap" %} ```shellscript $ 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 ``` {% endcode %} Expected output: {% code overflow="wrap" %} ```shellscript Available Tools: [Tool(name='list_files_important', title=None, description='List files in directory. check file size. ', 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)] ``` {% endcode %} ### 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. {% code overflow="wrap" %} ```shellscript $ sudo brace --image docker.io/library/langchain-mcp-server:v1 --name test-langchain -- /bin/bash ``` {% endcode %} Expected output: ```shellscript 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. ```shellscript $ 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: ```shellscript 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. {% code overflow="wrap" %} ```shellscript $ 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 ``` {% endcode %} --- # 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/bluerock-sandbox/bluerock-sandbox.md?ask=&goal= ``` `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.