Docker Setup Guide

lean-ctx is available as a Docker image for containerized development, CI/CD pipelines, and remote setups. The image is minimal (~20 MB) and includes all tree-sitter grammars.

Quick Start

# Pull the latest image
docker pull ghcr.io/yvgude/lean-ctx:latest

# Run lean-ctx as an MCP server (stdio mode)
docker run -i --rm \
  -v "$(pwd):/workspace" \
  -w /workspace \
  ghcr.io/yvgude/lean-ctx:latest \
  serve --stdio

# Run a one-off command with compression
docker run --rm \
  -v "$(pwd):/workspace" \
  -w /workspace \
  ghcr.io/yvgude/lean-ctx:latest \
  -c "git status"

Docker Compose

For projects using Docker Compose, add lean-ctx as a service:

# docker-compose.yml
services:
  lean-ctx:
    image: ghcr.io/yvgude/lean-ctx:latest
    command: serve --stdio
    volumes:
      - .:/workspace:ro
      - lean-ctx-cache:/root/.lean-ctx
    working_dir: /workspace
    stdin_open: true

volumes:
  lean-ctx-cache:

Configuration in Docker

Mount your config file or use environment variables:

Option A: Mount config.toml

docker run -i --rm \
  -v "$(pwd):/workspace" \
  -v "$HOME/.lean-ctx/config.toml:/root/.lean-ctx/config.toml:ro" \
  -w /workspace \
  ghcr.io/yvgude/lean-ctx:latest serve --stdio

Option B: Environment Variables

docker run -i --rm \
  -v "$(pwd):/workspace" \
  -w /workspace \
  -e LEAN_CTX_HEADLESS=1 \
  -e LCTX_MAX_READ_BYTES=10485760 \
  -e LCTX_MAX_SHELL_BYTES=2097152 \
  ghcr.io/yvgude/lean-ctx:latest serve --stdio

Key Environment Variables

Volume Mounts

CI/CD Integration

GitHub Actions

# .github/workflows/lint-context.yml
name: Context Lint
on: [pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run lean-ctx doctor
        run: |
          docker run --rm -v "$PWD:/workspace" -w /workspace \
            ghcr.io/yvgude/lean-ctx:latest doctor
      - name: Benchmark compression
        run: |
          docker run --rm -v "$PWD:/workspace" -w /workspace \
            ghcr.io/yvgude/lean-ctx:latest benchmark --project

GitLab CI

# .gitlab-ci.yml
context-check:
  image: ghcr.io/yvgude/lean-ctx:latest
  script:
    - lean-ctx doctor
    - lean-ctx benchmark --project

Troubleshooting

Permission Issues

If lean-ctx can't read files, ensure the volume mount permissions are correct:

# Run as your user ID
docker run --rm -u "$(id -u):$(id -g)" \
  -v "$(pwd):/workspace" \
  -w /workspace \
  ghcr.io/yvgude/lean-ctx:latest doctor

Cache Persistence

Use a named volume for /root/.lean-ctx to persist the session cache, knowledge base, and configuration between container restarts.

Headless Mode

In CI/CD environments, set LEAN_CTX_HEADLESS=1 to disable the Observatory dashboard and any interactive prompts.