Docker Installation¶

Running Code Scalpel in Docker is ideal for:

• CI/CD pipelines - Consistent environment across builds
• Isolated analysis - No impact on host system
• Team standardization - Same tools for everyone
• Security scanning - Sandboxed vulnerability analysis

Quick Start¶

# Pull the latest image
docker pull ghcr.io/your-org/code-scalpel:latest

# Run analysis on current directory
docker run -v $(pwd):/workspace ghcr.io/your-org/code-scalpel:latest \
  analyze_code --file /workspace/src/main.py

Docker Images¶

Usage Patterns¶

One-Off Analysis¶

Analyze a single file:

docker run -v $(pwd):/workspace ghcr.io/your-org/code-scalpel:latest \
  analyze_code --file /workspace/src/main.py

Security Scanning¶

Scan for vulnerabilities:

docker run -v $(pwd):/workspace ghcr.io/your-org/code-scalpel:latest \
  security_scan --file /workspace/src/auth.py

Project-Wide Analysis¶

Analyze entire project:

docker run -v $(pwd):/workspace ghcr.io/your-org/code-scalpel:latest \
  get_project_map --project-root /workspace

Interactive Mode¶

Start an interactive session:

docker run -it -v $(pwd):/workspace ghcr.io/your-org/code-scalpel:latest /bin/bash

MCP Server Mode¶

To run Code Scalpel as an MCP server in Docker (for connecting to AI assistants):

Code Scalpel supports three MCP transports: stdio, SSE, and streamable-http. For network deployments like Docker, use SSE or streamable-http. See the MCP Transports Guide for comprehensive setup options.

Using Docker Compose (Recommended)¶

version: '3.8'

services:
  code-scalpel:
    image: ghcr.io/your-org/code-scalpel:latest
    command: ["mcp", "--transport", "sse", "--host", "0.0.0.0", "--port", "8080", "--allow-lan"]
    ports:
      - "8080:8080"
    volumes:
      - ./:/workspace:ro
      - ./config:/config:ro
    environment:
      - CODE_SCALPEL_LICENSE_PATH=/config/license.jwt

docker-compose up -d

Alternative: streamable-http Transport¶

For production systems or when behind a reverse proxy:

services:
  code-scalpel:
    image: ghcr.io/your-org/code-scalpel:latest
    command: ["mcp", "--transport", "streamable-http", "--host", "0.0.0.0", "--port", "8080", "--allow-lan"]
    ports:
      - "8080:8080"

Claude Desktop with Docker¶

Configure Claude to connect to the Docker container using stdio transport:

{
  "mcpServers": {
    "code-scalpel": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/project:/workspace",
        "ghcr.io/your-org/code-scalpel:latest",
        "mcp"
      ]
    }
  }
}

Or connect to a running Docker container via HTTP (SSE transport):

{
  "mcpServers": {
    "code-scalpel": {
      "url": "http://localhost:8080/sse",
      "transport": "sse"
    }
  }
}

For streamable-http:

{
  "mcpServers": {
    "code-scalpel": {
      "url": "http://localhost:8080/mcp",
      "transport": "http"
    }
  }
}

CI/CD Integration¶

GitHub Actions¶

name: Security Scan

on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Code Scalpel Security Scan
        run: |
          docker run -v ${{ github.workspace }}:/workspace \
            ghcr.io/your-org/code-scalpel:latest \
            security_scan --project-root /workspace --output json \
            > security-report.json

      - name: Upload Security Report
        uses: actions/upload-artifact@v4
        with:
          name: security-report
          path: security-report.json

GitLab CI¶

security-scan:
  image: ghcr.io/your-org/code-scalpel:latest
  stage: test
  script:
    - security_scan --project-root /builds/$CI_PROJECT_PATH --output json > report.json
  artifacts:
    reports:
      security: report.json

Jenkins¶

pipeline {
    agent any

    stages {
        stage('Security Scan') {
            steps {
                script {
                    docker.image('ghcr.io/your-org/code-scalpel:latest').inside('-v ${WORKSPACE}:/workspace') {
                        sh 'security_scan --project-root /workspace --output json > security-report.json'
                    }
                }
            }
        }
    }

    post {
        always {
            archiveArtifacts artifacts: 'security-report.json'
        }
    }
}

Configuration¶

Volume Mounts¶

Environment Variables¶

Custom Configuration¶

Mount your .code-scalpel directory:

docker run \
  -v $(pwd):/workspace:ro \
  -v $(pwd)/.code-scalpel:/config:ro \
  -e CODE_SCALPEL_CONFIG_PATH=/config \
  ghcr.io/your-org/code-scalpel:latest \
  analyze_code --file /workspace/src/main.py

Building Custom Images¶

Extend the Base Image¶

FROM ghcr.io/your-org/code-scalpel:latest

# Add custom tools
RUN pip install additional-package

# Add custom configuration
COPY .code-scalpel /config

# Set defaults
ENV CODE_SCALPEL_CONFIG_PATH=/config

docker build -t my-code-scalpel .

Multi-Stage Build for Slim Image¶

FROM python:3.11-slim as builder

WORKDIR /app
RUN pip install codescalpel

FROM python:3.11-slim
COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
COPY --from=builder /usr/local/bin/codescalpel /usr/local/bin/

WORKDIR /workspace
ENTRYPOINT ["codescalpel"]

Troubleshooting¶

Security Considerations¶

docker run --user 1000:1000 -v $(pwd):/workspace:ro ...

Next Steps¶

• CI/CD Integration Guide - Full CI/CD setup
• GitHub Actions Guide - Detailed GitHub setup
• Tool Reference - All available tools