Remote Setup

lean-ctx läuft als stdio MCP server - dein AI-Client startet es als lokalen Subprozess. Für Remote-Server, Container oder headless Umgebungen kannst du die Verbindung über SSH tunneln. Keine zusätzliche Server-Komponente nötig.

SSH-Tunnel (empfohlen)

Der einfachste Ansatz: Konfiguriere deinen AI-Client so, dass lean-ctx via SSH ausgeführt wird. Das MCP-Protokoll läuft über SSH stdin/stdout - keine Ports öffnen, kein HTTP, keine Authentifizierung managen. SSH übernimmt Verschlüsselung und Authentifizierung nativ.

1. lean-ctx auf dem Remote-Server installieren

Per SSH einloggen und lean-ctx installieren:

ssh user@server
cargo install lean-ctx
# or download pre-built binary:
curl -fsSL https://leanctx.com/install.sh | sh

2. Verbindung testen

Prüfe, dass lean-ctx über SSH funktioniert. Du kannst entweder den MCP-Server direkt ausführen oder das Dashboard tunneln:

# Terminal 1: SSH tunnel (keeps running)
ssh -L 3333:localhost:3333 user@server "lean-ctx dashboard --port 3333"

# Or just forward the MCP stdio over SSH:
ssh user@server "lean-ctx"

3. AI-Client konfigurieren

Setze in der MCP-Konfiguration deines AI-Clients, dass lean-ctx via SSH gestartet wird. Das funktioniert mit Cursor, Claude Code, Windsurf und jedem MCP-kompatiblen Client:

// ~/.cursor/mcp.json or ~/.claude.json
{
  "mcpServers": {
    "lean-ctx": {
      "command": "ssh",
      "args": ["user@server", "lean-ctx"]
    }
  }
}

Damit startet der Client ssh user@server "lean-ctx" statt eines lokalen lean-ctx. Das MCP-Protokoll läuft transparent über die SSH-Verbindung - stdin/stdout werden automatisch getunnelt.

Port-Forwarding (Dashboard)

Wenn du das lean-ctx dashboard (Observatory) lokal im Browser öffnen willst, während lean-ctx remote läuft, nutze SSH Port-Forwarding:

Persistente SSH-Konfiguration

# ~/.ssh/config
Host dev-server
  HostName 192.168.1.100
  User developer
  LocalForward 3333 localhost:3333
  ServerAliveInterval 60
  ServerAliveCountMax 3

Dann verbinden und Dashboard starten:

ssh dev-server "lean-ctx dashboard --port 3333"
# Dashboard now available at http://localhost:3333

VS Code Remote SSH

Wenn du VS Code mit der Remote - SSH-Extension nutzt, funktioniert lean-ctx automatisch - der MCP-Server läuft remote wie jeder andere Terminal-Befehl. Installiere lean-ctx remote, führe lean-ctx setup aus, und es konfiguriert sich für die Remote-Umgebung.

Docker / Container

Für containerisierte Entwicklung mounte das lean-ctx Binary und sein Datenverzeichnis in deinen Container:

# Mount lean-ctx binary into your dev container
docker run -it \
  -v $(which lean-ctx):/usr/local/bin/lean-ctx:ro \
  -v ~/.lean-ctx:/root/.lean-ctx \
  your-dev-image bash

Für Docker Compose füge die Volumes zu deinem Service hinzu:

# docker-compose.yml
services:
  dev:
    image: your-dev-image
    volumes:
      - ./:/workspace
      - lean-ctx-bin:/usr/local/bin/lean-ctx:ro
      - ~/.lean-ctx:/root/.lean-ctx

Fehlerbehebung

Verbindung bricht nach Idle-Zeit ab

SSH-Verbindungen können bei langen Idle-Phasen timeouts bekommen. Füge Keepalive-Settings hinzu:

ssh -o ServerAliveInterval=60 -o ServerAliveCountMax=3 user@server "lean-ctx"

Permission denied auf dem Remote

Stelle sicher, dass lean-ctx im PATH des Remote-Users ist. Bei cargo install liegt es unter ~/.cargo/bin/lean-ctx. Füge export PATH=\"$HOME/.cargo/bin:$PATH\" in ~/.bashrc oder ~/.zshrc hinzu.

Versions-Mismatch zwischen lokal und remote

Der lokale AI-Client und das remote laufende lean-ctx sollten dieselbe Version verwenden, um Protokoll-Probleme zu vermeiden. Halte beide aktuell:

# Check versions on both machines
lean-ctx --version              # local
ssh user@server "lean-ctx --version"  # remote

Diagnose auf dem Remote ausführen

Nutze lean-ctx doctor auf dem Remote-Server, um Installation, Shell-Hooks und MCP-Konfiguration zu prüfen:

ssh user@server "lean-ctx doctor"