Gnosis Docker

A Flask async server that exposes Docker management endpoints for MCP (Model Context Protocol) integration with Claude Desktop and Claude Code. This server communicates with the Docker daemon via Docker socket mounting, enabling comprehensive container management through AI assistants.

Features

• Full Docker container management (list, start, stop, restart, remove)
• Docker image management (list, pull, remove, build)
• Container logs streaming and stats monitoring
• Container inspection and health checks
• Docker build triggers for Gnosis projects
• Async Flask server with proper error handling
• Security middleware for local-only access
• MCP tools for AI assistant integration

Prerequisites and Setup

Windows with WSL2 (Recommended)

Gnosis Docker works best on Windows using WSL2 with Docker Desktop, as it provides native Docker socket access:

1. Install WSL2

# Run as Administrator in PowerShell
wsl --install
# Restart your computer

2. Install Docker Desktop

• Download Docker Desktop from https://www.docker.com/products/docker-desktop/
• During installation, ensure "Use WSL 2 based engine" is selected
• Start Docker Desktop

3. Configure Docker Desktop for WSL2

# Run the setup helper script
.\setup-docker-desktop.ps1

Or manually configure:

1. Open Docker Desktop Settings
2. Go to General tab → Enable "Use WSL 2 based engine"
3. Go to Resources → WSL Integration → Enable integration with your WSL2 distro
4. Optional for development: In General tab → Enable "Expose daemon on tcp://localhost:2375 without TLS"
5. Click Apply & Restart

4. Verify Docker Socket Access

In WSL2:

# Check if Docker socket is accessible
ls -la /var/run/docker.sock
# Should show: srw-rw---- 1 root docker 0 [date] /var/run/docker.sock

# Test Docker connection
docker version

Windows without WSL2 (Limited)

For development without WSL2, you can use Docker Desktop's TCP endpoint:

1. Enable TCP endpoint in Docker Desktop (Settings → General → "Expose daemon on tcp://localhost:2375")
2. Set environment variable: $env:DOCKER_HOST = "tcp://localhost:2375"
3. Run: .\setup-docker-desktop.ps1 to verify setup

Note: This method has limitations and security considerations. WSL2 is strongly recommended.

Docker Socket Communication

Gnosis Docker uses Docker socket mounting to communicate with the Docker daemon:

• WSL2: Uses Unix socket /var/run/docker.sock (mounted into containers)
• TCP: Uses tcp://localhost:2375 (for development only)
• Security: The server validates all container operations and mounts

Directory Structure

gnosis-docker/
├── deploy.ps1              # Single deployment script for all environments
├── deploy-wsl2.sh          # WSL2 deployment script
├── requirements.txt        # Python dependencies
├── setup.ps1               # Initial setup script
├── setup-docker-desktop.ps1 # Docker Desktop configuration helper
├── Dockerfile             # Docker configuration
├── docker-compose.yml     # Local development with Redis
├── .env.example           # Environment variable template
├── .gitignore            # Git ignore file
├── README.md             # This file
├── WSL2_README.md        # WSL2-specific documentation
├── app.py                # Main Flask application
├── core/                 # Core application modules
│   ├── __init__.py
│   ├── docker_manager.py  # Docker operations handler
│   ├── auth.py           # Authentication middleware
│   ├── config.py         # Configuration management
│   ├── validation.py     # Container security validation
│   └── utils.py          # Utility functions
├── tests/                # Test suite
│   ├── __init__.py
│   └── test_docker_api.py
├── mcp/                  # MCP Tools Directory
│   ├── README.md         # MCP tools documentation
│   ├── requirements.txt  # MCP-specific dependencies
│   ├── setup.py          # MCP tools setup script
│   ├── gnosis_docker_mcp.py    # Docker management MCP tool
│   ├── file_manager_mcp.py     # File operations MCP tool
│   └── example_utilities_mcp.py # Example MCP tool
└── cleanup_*.py|ps1|sh   # Repository cleanup scripts

Quick Start

Deploy the Docker API Server

Windows WSL2 (Recommended)

# From WSL2 terminal
cd /mnt/c/Users/kord/Code/gnosis/gnosis-docker

# Make scripts executable
chmod +x deploy-wsl2.sh

# Deploy locally
./deploy-wsl2.sh

Windows PowerShell

# Initial setup (run once)
.\setup.ps1

# Windows - Deploy locally
.\deploy.ps1 -Target local

# Windows - Deploy to staging
.\deploy.ps1 -Target staging

# Windows - Deploy to production
.\deploy.ps1 -Target production

# Windows - Rebuild from scratch
.\deploy.ps1 -Target local -Rebuild

# Windows - Dry run (see what would happen)
.\deploy.ps1 -Target production -WhatIf

Use MCP Tools with AI Assistants

The /mcp directory contains ready-to-use MCP tools that integrate with Claude Code and Claude Desktop:

# Navigate to MCP tools
cd mcp

# Install dependencies
pip install -r requirements.txt

# Run setup and validation
python setup.py

# Configure with Claude Code
claude mcp add gnosis-docker python3 gnosis_docker_mcp.py

# Test the integration
claude
# Then try: "list docker containers", "check docker health"

See mcp/README.md for complete MCP setup instructions.

API Endpoints

Container Management

• GET /health - Health check
• GET /api/containers - List all containers
• GET /api/containers/<id> - Get container details
• POST /api/containers/<id>/start - Start container
• POST /api/containers/<id>/stop - Stop container
• POST /api/containers/<id>/restart - Restart container
• DELETE /api/containers/<id> - Remove container
• GET /api/containers/<id>/logs - Get container logs
• GET /api/containers/<id>/stats - Get container stats

Image Management

• GET /api/images - List all images
• POST /api/images/pull - Pull an image
• DELETE /api/images/<id> - Remove an image

Project Operations

• POST /api/build - Build a Gnosis project
• POST /api/projects/<name>/deploy - Deploy a project

MCP Integration

This server provides Docker management capabilities to AI assistants through MCP tools:

Available MCP Tools

1. Gnosis Docker MCP (mcp/gnosis_docker_mcp.py)

   • Complete Docker management through Claude Code/Desktop
   • List, start, stop, restart containers
   • Get container logs and statistics
   • Manage Docker images
   • Build and deploy Gnosis projects

2. File Manager MCP (mcp/file_manager_mcp.py)

   • Cross-platform file operations
   • Create, copy, move, delete files and directories
   • Backup support for safe operations

3. Example Utilities MCP (mcp/example_utilities_mcp.py)

   • Demonstrates MCP development patterns
   • Basic utilities (echo, timestamps, calculations)
   • Text analysis and system information

Configuration Methods

Claude Code (Recommended):

claude mcp add gnosis-docker python3 /path/to/gnosis-docker/mcp/gnosis_docker_mcp.py

Claude Desktop: Add to claude_desktop_config.json:

{
  "mcpServers": {
    "gnosis-docker-mcp": {
      "command": "python",
      "args": ["C:\\path\\to\\gnosis-docker\\mcp\\gnosis_docker_mcp.py"]
    }
  }
}

Repository Maintenance

Clean Up Versioning Directories

This repository includes cleanup scripts to remove unwanted versioning directories and Python cache files:

# Python script (cross-platform)
python cleanup_comprehensive.py

# PowerShell script (Windows)
.\cleanup_comprehensive.ps1


# Bash script (Linux/WSL2)
./cleanup_quick.sh

These scripts will remove:

• *_versions/ directories
• __pycache__/ directories
• *.pyc files
• Update .gitignore with proper patterns

Environment Variables

• FLASK_ENV - Environment (development/staging/production)

• DOCKER_HOST - Docker daemon URL (default: unix:///var/run/docker.sock, or tcp://localhost:2375 for Windows)

• API_KEY - Authentication key for production

• REDIS_URL - Redis URL for caching (optional)

• GNOSIS_DOCKER_URL - API endpoint URL (default: http://localhost:5680)

Security

• Local-only access by default (binds to 127.0.0.1)
• API key authentication for production deployments
• Request validation and sanitization
• Docker socket security with proper permissions and validation
• CORS protection for web interfaces
• Container parameter validation prevents dangerous operations
• Volume mount restrictions limit filesystem access

Development

Running Locally

# Install dependencies
pip install -r requirements.txt

# Or use setup script
.\setup.ps1

# Run in development mode
python app.py


# Run tests
python -m pytest tests/

# Test API endpoints
python test_api.py

Docker Development

# Build container
docker build -t gnosis-docker .

# Or use deployment script
.\deploy.ps1 -Target local

# Run with Docker Compose
docker-compose up -d


# View logs
docker-compose logs -f gnosis-docker

Integration with Gnosis Ecosystem

This Docker controller is designed to work with other Gnosis components:

• Gnosis Wraith - Web crawling and data extraction
• Gnosis Mystic - Function interception and analysis
• Gnosis Stream - Data processing and streaming
• Gnosis Evolve - Development tools and utilities

The MCP tools provide a unified interface for AI assistants to manage the entire Gnosis ecosystem through Docker containers.

API Usage Examples

List Running Containers

curl http://localhost:5680/api/containers

Start a Container

curl -X POST http://localhost:5680/api/containers/mycontainer/start

Get Container Logs

curl http://localhost:5680/api/containers/mycontainer/logs?tail=100

Build a Gnosis Project

curl -X POST http://localhost:5680/api/build \
  -H "Content-Type: application/json" \
  -d '{"project": "gnosis-wraith", "tag": "latest"}'

Troubleshooting

Common Issues

1. Docker daemon not accessible in WSL2

   • Check Docker Desktop is running
   • Verify WSL2 integration is enabled in Docker Desktop
   • Check Docker socket exists: ls -la /var/run/docker.sock
   • Restart Docker Desktop and try again

2. Docker daemon not accessible on Windows

   • Ensure Docker Desktop is running
   • Check if TCP endpoint is enabled (Settings → General)
   • Verify DOCKER_HOST environment variable
   • Try running: .\setup-docker-desktop.ps1

3. "Cannot connect to Docker daemon" errors

   • WSL2: Check that Docker socket is mounted: docker version
   • Windows: Verify TCP endpoint: curl http://localhost:2375/version
   • Check firewall settings
   • Ensure Docker Desktop has started completely

4. Container fails to start

   • Check Docker logs: docker-compose logs gnosis-docker
   • Verify port 5680 is not in use: netstat -an | findstr 5680
   • Check volume mounts in docker-compose.yml

5. Port 5680 already in use

   • Stop existing instances
   • Change port in deployment scripts
   • Check for conflicting services

6. MCP tools not connecting

   • Verify API server is running on localhost:5680
   • Check firewall settings
   • Ensure MCP dependencies are installed

7. Path issues with double slashes

   • Use single backslashes in Windows paths
   • WSL2 paths should use /mnt/c/ prefix
   • Docker-compose uses Linux-style paths inside containers
   • Check docker-compose.yml volume mappings

Logs and Debugging

# Check API server logs
docker-compose logs gnosis-docker

# Enable debug logging
export FLASK_ENV=development  # WSL2
$env:FLASK_ENV = "development"  # PowerShell
python app.py

# Test API health
curl http://localhost:5680/health

# Test Docker socket access (WSL2)
docker version
ls -la /var/run/docker.sock

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Update documentation
6. Submit a pull request

License

This project is part of the Gnosis ecosystem and follows the same licensing terms.