Content
# Secure Grid Genesis Execution
An open-source, lightweight, and ultra-secure **Model Context Protocol (MCP) Server** designed to run arbitrary Python, JavaScript (Node.js), and Bash code in a highly restricted local Docker container.
This repository allows AI agents (like Claude Desktop, Antigravity, or Cursor) to test and run code locally without risking damage to the host system.
---
## 🔒 Security Features (Strict Sandbox Isolation)
When an AI agent requests to execute code, the server:
1. **Air-Gaps Execution:** Disables all network access (`network_mode="none"`) inside the container to prevent data exfiltration, reverse shells, or local network scanning.
2. **Mounts Read-Only Workspace:** Mounts the host directory as a read-only (`ro`) volume, ensuring that scripts can read workspace context but cannot delete, rewrite, or modify host files.
3. **Applies CPU & Memory Caps:** Caps memory consumption to **256MB** and restricts compute resources to **1 CPU core** to prevent denial-of-service (DoS) exploits or memory leaks.
4. **Runs as Non-Root User:** Forces execution as a restricted user (`sandboxuser` with UID `10001`) inside the container to prevent container breakout vulnerabilities.
---
## 🚀 Setup & Installation
### 1. Prerequisites
- **Python 3.10+**
- **Docker Desktop** (Make sure the Docker daemon is running on your system)
### 2. Clone and Install Dependencies
```bash
git clone https://github.com/yourusername/secure-grid-genesis-execution.git
cd secure-grid-genesis-execution
pip install -r requirements.txt
```
### 3. Build the Sandbox Container
Build the isolated environment image:
```bash
docker build -t secure-grid-sandbox -f Dockerfile.sandbox .
```
### 4. Run Automated Containment Tests
Run the test script to verify that the sandbox correctly blocks file writes and network connections:
```bash
python test_sandbox.py
```
---
## 🛠️ Registering the MCP Server
Add the following to your AI client's configuration file to register the server.
### For Claude Desktop
Add this to `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
```json
{
"mcpServers": {
"secure-grid-genesis-execution": {
"command": "python",
"args": [
"C:\\path\\to\\secure-grid-genesis-execution\\secure_executor.py"
]
}
}
}
```
*(Make sure to replace the path with the absolute path where you cloned the repo)*
### For Google Antigravity
Add this to `~/.gemini/config/mcp_config.json`:
```json
{
"mcpServers": {
"secure-grid-genesis-execution": {
"command": "python",
"args": [
"C:\\path\\to\\secure-grid-genesis-execution\\secure_executor.py"
]
}
}
}
```
---
## 🛠️ Exposed MCP Tools
The server exposes three tools to the AI agent:
1. `execute_python(code)`: Safely executes a Python snippet.
2. `execute_node(code)`: Safely executes JavaScript code inside Node.js.
3. `execute_bash(command)`: Runs shell commands in a sandboxed Linux environment.
