远程设置 — LeanCTX Docs

lean-ctx 作为 stdio MCP server 运行--你的 AI 客户端会把它当作本地子进程启动。对于远程服务器、容器或 headless 环境，你可以通过 SSH 将连接隧道化。无需额外的服务器组件。

SSH 隧道（推荐）

最简单的方法：让你的 AI 客户端通过 SSH 运行 lean-ctx。MCP 协议通过 SSH 的 stdin/stdout 传输--无需开放端口、无需 HTTP、无需管理额外认证。SSH 原生提供加密与认证。

1. 在远程服务器上安装 lean-ctx

通过 SSH 登录服务器并安装 lean-ctx：

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

2. 测试连接

验证 lean-ctx 可通过 SSH 正常工作。你可以直接转发 MCP server，或对 dashboard 进行隧道：

# 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 客户端

将 AI 客户端的 MCP 配置指向通过 SSH 启动 lean-ctx。这适用于 Cursor、Claude Code、Windsurf 以及任何兼容 MCP 的客户端：

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

这会让客户端启动 ssh user@server "lean-ctx"，而不是本地 lean-ctx。MCP 协议会在 SSH 连接上透明传输--stdin/stdout 会自动隧道化。

端口转发（Dashboard）

如果你希望在 lean-ctx 运行于远程服务器时，仍能在本地浏览器访问 lean-ctx dashboard（Observatory），请使用 SSH 端口转发：

持久化 SSH 配置

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

然后连接并启动 dashboard：

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

VS Code Remote SSH

如果你使用 VS Code 的 Remote - SSH 扩展，lean-ctx 会自动工作--MCP server 会在远端像普通终端命令一样运行。请在远端安装 lean-ctx，运行 lean-ctx setup，它会为远程环境完成配置。

Docker / 容器

在容器化开发中，将 lean-ctx 二进制文件与其数据目录挂载进容器：

# 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

对于 Docker Compose，将卷挂载添加到你的服务中：

# 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

故障排查

空闲一段时间后连接断开

SSH 连接在长时间空闲时可能超时。添加 keepalive 配置：

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

远端 Permission denied

确保远端用户的 PATH 中包含 lean-ctx。如果通过 cargo install 安装，路径为 ~/.cargo/bin/lean-ctx。将 export PATH=\"$HOME/.cargo/bin:$PATH\" 添加到远端 ~/.bashrc 或 ~/.zshrc。

本地与远端版本不一致

为避免协议问题，本地 AI 客户端与远端 lean-ctx 应保持相同版本。请同时更新两端：

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

在远端运行诊断

在远程服务器上运行 lean-ctx doctor，以验证安装、shell hook 以及 MCP 配置：

ssh user@server "lean-ctx doctor"