本地执行环境 fwerkor/local-shell-mcp

local-shell-mcp

面向 ChatGPT 的 MCP 控制平面，覆盖 shell、文件、浏览器自动化、文件链接和远程机器。

dsh.so security

文档 · 快速上手 · 运行时选择 · ChatGPT 连接器 · DSH 插件 · 工具 · 版本发布

local-shell-mcp 让 ChatGPT Developer Mode 和其他 MCP 客户端可控地访问真实执行环境。它提供一个专用工作区，包含 shell、持久 shell、文件系统、搜索、补丁、Playwright、审计、可持久化的逻辑会话（可选 Goal 计划）、公开文件链接，以及出站远程 worker 访问。Git 走普通 shell 命令，不另设一层包装 API。

Runtime: Docker / VS Code extension / binary / Python / stdio
-> exposure: localhost, HTTPS proxy/tunnel, or stdio pipe
-> client: ChatGPT or another MCP client
-> controlled workspace at /workspace or configured root
-> optional remote workers connected over outbound HTTP(S)

安全边界落在容器或 VM 上，不在宿主机。

为什么用它

| 能力 | 能做什么 |
| 真实终端访问 | 跑测试、构建项目、查日志、调试，全程用持久 shell 会话。 |
| 工作区感知的文件工具 | 在受控根目录下读、写、打补丁、搜索、审阅文件。 |
| Git 工作流支持 | 通过 shell 工具跑标准 Git 命令行，不用再学一套残缺的 Git 抽象。 |
| 浏览器自动化 | 提取页面文本、抓取 PNG/PDF 证据，或运行完整 Playwright 脚本。 |
| 原生桌面 GUI | 观察无障碍树和截图，用受保护的语义/坐标操作控制 Linux、Windows 或 macOS 应用。 |
| 远程工作机 | 控制只能向外连接的 NAT、防火墙、HPC、NPU 或实验室机器。 |
| 智能体技能 | 通过三个固定工具发现、加载并读取可复用的 SKILL.md 工作流，无需改动 MCP 工具列表。 |
| ChatGPT 连接器支持 | OAuth 2.1、/mcp、发现控制，以及兼容 ChatGPT 的工具 schema。 |
| DeepSeek Harness 插件 | 把本仓库作为 DSH bundle 安装，暴露完整的 LSM 工具面，包括远程工作机。 |
| ChatGPT Live Workspace | 渲染原生 MCP App，在 ChatGPT 内实时展示活动、终端、文件、差异、任务、远程机、审计，并支持人与智能体直接协作。 |
| 更安全的操作 | 工作区范围限定、shell 超时、输出限制、环境过滤、审计日志和密钥扫描。 |

快速开始

需要宿主运行时，安装官方启动器或 Python 包：

npx local-shell-mcp --help
pipx install local-shell-mcp
lsm --help

npm 和 Python 发行版都提供 local-shell-mcp；安装后的包还提供短命令 lsm。npm 发行版只是对应独立发布二进制的校验启动器，不是第二套服务器实现。

克隆仓库并准备配置：

git clone https://github.com/fwerkor/local-shell-mcp.git
cd local-shell-mcp
cp .env.example .env
python scripts/init_compose_env.py

在 .env 中至少设置这些值：

LOCAL_SHELL_MCP_PUBLIC_BASE_URL=https://your-public-host.example.com
LOCAL_SHELL_MCP_AUTH_MODE=oauth
LOCAL_SHELL_MCP_OAUTH_ADMIN_PIN=change-me-long-random-pin
LOCAL_SHELL_MCP_OAUTH_JWT_SECRET=change-me-64-hex-random-secret
CLOUDFLARE_TUNNEL_TOKEN=

启动服务器：

mkdir -p workspaces/default
docker compose up -d
curl -i http://127.0.0.1:8765/healthz

需要公网 HTTPS 访问时，启动随附的 Cloudflare Tunnel sidecar：

docker compose --profile tunnel up -d

公开的 MCP 端点是：

https://your-public-host.example.com/mcp

完整安装说明见文档。运行时选型与客户端连接分开说明。

人机界面

服务包含两个兼容的人机界面，共用同一套认证 API 和状态：

- Web UI 是原生浏览器仪表盘，展示系统健康、机器、工作负载、近期 MCP 活动和告警。
- OpenTUI 是完整的终端界面，含 Dashboard、Files、Terminals、Remotes 和 Audit 屏幕。它在浏览器中仍可作为可选控制台使用，也可通过原生命令 local-shell-mcp tui 启动。

在服务源站打开浏览器界面：

http://127.0.0.1:8765/ui

OAuth 界面让你在授权前选择 Web UI 或 OpenTUI。登录后，随时可以在界面选择器里切换模式。原生 Web UI 路由使用 URL 哈希，例如 #/overview 和 #/console，所以选中的模式或页面可以加书签。OpenTUI 控制台保留现有的已认证 xterm.js/PTY 传输、鼠标交互、自动调整大小、重连、全屏模式，以及移动端快捷行。

独立发布的可执行文件内嵌原生 OpenTUI 运行时，Docker 镜像则在镜像内提供它。启动服务，然后无需人工登录提示即可启动：

local-shell-mcp tui

原生 TUI 用与 lsm call 相同的、仅限本机的专用命令行凭据，认证回环 Human UI API；分离运行时布局可以传 --token-file。浏览器启动的 OpenTUI 使用控制器进程凭据，该凭据在内存中惰性创建，绝不把这份特权凭据写入状态目录或状态后端。专用本地命令行凭据也可以直接从 shell 脚本调用已注册的 MCP 工具面；Human UI token 有意永不被 /mcp 接受。默认情况下，call 连接正在运行的回环控制器，因此远程 worker 调用使用实时控制器进程，而不是单独的进程内 worker 注册表：

lsm call run_shell --json '{"command":"uname -a"}'
lsm call run_shell --json '{"command":"nvidia-smi","machine":"gpu-node"}'
printf '%s\n' '{"path":"README.md"}' | lsm call file_read

用 --session s_... 把普通工具调用挂到持久逻辑会话上。在文档给出的 Docker Compose 配置里，原始 LOCAL_SHELL_MCP_CLI_LOCAL_TOKEN 只留在主机所有、权限受限的 .env 中；Compose 只把它的 SHA-256 校验值传给控制器，命令行读取原始值时不初始化服务端状态。其他分离运行时布局可以用 --token-file <path> 或同一个环境变量，并在控制器上配置匹配的 LOCAL_SHELL_MCP_CLI_LOCAL_TOKEN_SHA256。底层命令失败会让 lsm call 以非零状态退出。没有控制器运行时，独立本地调用可以用 --direct；直接模式下有意不提供远程 worker。

worker 安装的 local-shell-mcp 启动器仅用于管理（worker start、worker status 等）；它既不暴露 call 也不暴露 tui。worker 下载包只包含显式选定的执行模块，不含 Controller CLI、TUI 或 WebUI。worker 接收并上报任务，但不能用 worker 凭据发起控制器工具调用。
Files 仍是 OpenTUI 内的 LSM 原生三栏文件管理器，支持本地和远程机器。它能渲染有尺寸限制的 PNG/JPEG/GIF/WebP 缩略图，并通过共享服务 API 提供一致的文件操作。无论从哪个人工界面发起的手动操作，都不计入 MCP 审计日志；Activity、Audit 和终端审计栏只显示由模型发起的 MCP 活动。

参见人工界面指南。

ChatGPT 配置

要用完整的 shell、文件系统、远程 worker 和 Playwright 工具，请使用 ChatGPT Developer Mode 或其他完整的 MCP 客户端。ChatGPT 只是一个客户端连接；先选好并启动运行时。

session_manage 为智能体工作提供一个持久的逻辑任务上下文。会话刻意独立于机器和工作目录：它保存任务目标、语义进度报告、最近的执行 Activity，以及可选的 Plan。session_id 是唯一持久的任务标识。要在另一个 ChatGPT 对话里继续工作，用户需显式传入已有的 session_id，新智能体调用 session_manage(action="resume", session_id=...)。智能体不会列出或自动选择其他对话的会话。启动/恢复之后、有意义的进度检查点、以及结束一轮之前，智能体都应报告当前 session_id；语义进度用 session_manage(action="report", session_id=...) 上报，不要把每个工具结果都抄进摘要。普通工具拿到的任务标识与 logical_session_id 相同。

客户端支持 MCP Apps 时，workspace_open(session_id=...) 会为显式选中的会话打开执行视图，以浮动 MCP App 呈现，可展开为全屏。v3 名称 open_live_workspace 仍作为隐藏的、不参与枚举的兼容别名，供缓存了 recipient 的 ChatGPT 客户端使用；新集成只会看到并使用 workspace_open。Live Workspace 是可重连的查看器和协作界面，不是任务状态的持有者：关闭它或重连 MCP 都不会丢弃会话进度、Activity 或 Plan。普通 MCP 工具仍是执行 API，app 则额外提供实时操作活动、持久终端、文件/差异检查、作业、远程、审计数据和当前会话 id。不渲染 MCP Apps 的客户端继续使用普通工具界面，行为不变。
plan_manage(session_id=...) 可以选择为指定的会话启用 Goal 模式，用来处理大型多步任务。激活的计划就是目标：执行情况变化时，可以修订计划里的步骤；挂载 Live Workspace 期间，如果智能体 15 分钟没有工具活动，应用可以请求继续。自动继续最多 10 次尝试（无论接受还是拒绝），继续前会恢复同一个会话。计划状态为 blocked、completed、cancelled 时不会触发提醒；如果激活的计划里所有步骤都已完成或跳过，仍然可以触发清理式继续，让恢复后的智能体调用 plan_manage(action="finish")。会话不要求必须有计划。

1. 通过 HTTPS 暴露服务器。
2. 保持 OAuth 开启。
3. 添加 MCP 端点：https://your-public-host.example.com/mcp。
4. 完成 OAuth 授权流程。
5. 先从一个范围有限的任务开始，需要时查看审计日志。

阅读专门的 ChatGPT 连接器指南。

DeepSeek Harness 插件

dsh.so install

DSH 桥接单独发布为 local-shell-mcp-dsh。同一台主机上跑着正常的 LSM HTTP/MCP 服务时，把插件安装到 DSH 配置档：

dsh plugin --profile web add local-shell-mcp-dsh

这个包使用能识别 LSM 的 Streamable HTTP 桥接，保留完整的 LSM 工具面，包括 remote_manage、remote_transfer、浏览器工具和 Dynamic MCP 工具。每个 DSH 会话都会获得稳定的 v4 逻辑会话标识，因此它的 Logical Session、活动运行、Activity 和原生 Live Workspace 视图与其他 DSH 对话相互隔离，并且在 DSH 侧重建 MCP 传输后依然保留。DSH 在常规的 mcp__lsm__ 命名空间下看到模型工具。DSH npm 包与 LSM 使用同一发布版本。从仓库安装仍然适合基于 checkout 做开发。

参见 DeepSeek Harness 集成指南。

VS Code 扩展运行时

发布产物包含 local-shell-mcp-<version>.vsix。这个扩展是当前 VS Code 工作区的运行时启动器。它启动同一个服务器，检查 /healthz，复制 MCP URL，并复制一段可直接粘贴的 ChatGPT 配置提示词。

基本流程：

Install executable -> install VSIX -> open a workspace -> Start Server -> copy MCP URL

要让 ChatGPT 从公网访问，用 HTTPS 隧道暴露本地服务器，并在 VS Code 设置里配置 local-shell-mcp.publicBaseUrl。直接使用宿主机时保持 local-shell-mcp.allowFullContainer 关闭；只在一次性容器或虚拟机里开启。

远程工作节点

远程 worker 模式默认开启。在控制服务器上创建一次性邀请，把生成的命令粘贴到远程机器，之后就能用常规工具，并带上可选的 machine 参数。只有 worker 管理功能保留 remote_ 命名。

适用于：

- 防火墙后面的 HPC 登录节点或计算节点。
- 没有入站连接能力的 NPU/GPU 服务器。
- 能发起出站 HTTPS 请求的实验室机器。
- 临时构建主机或远程测试环境。

参见 remote workers 指南。

智能体技能

技能从三个有序来源发现：项目级 /workspace/.agents/skills、LSM 托管的 /workspace/.local-shell-mcp/agent_config/skills，以及全局 ~/.config/agents/skills。优先级高的来源会覆盖同名的低优先级技能，支持符号链接的技能目录和文件。

这样通用的 Skills CLI 布局可以直接使用，例如 npx skills add owner/repo --agent universal -y。用 skill_list 发现已安装的技能，用 skill_load 加载一套指令，用 skill_read 按返回的技能相对路径读取相关文件。下次调用时才会检测到变更；不注册按技能划分的 MCP 工具，也不需要客户端重连。

参见 Agent Skills 指南。

工具面

公开的 MCP 工具面包括：

- Live Workspace：workspace_open 为当前逻辑会话打开可重连的 MCP App。
- Shell 与作业：run_shell、run_python、持久化的 shell_，以及可跟踪的 job_ 工具。Git 命令行操作请用 run_shell。
- 文件系统：file_list、file_tree、file_glob、file_grep、统一的 file_read、原生视觉的 image_view、file_write、统一的 file_edit、file_delete，以及 file_patch。
- 传输：remote_transfer，在控制器与 worker 端点之间传输文件或目录。
- 动态 MCP：mcp_manage、mcp_tool_search、mcp_tool_inspect 和 mcp_tool_call。外部工具逐步发现，绝不扩展 LSM 自身的 tools/list 工具面。
- 浏览器：持久化的高层工具 browser_session、browser_snapshot 和 browser_act；browser_run_script 是底层 Playwright 逃生通道。
- 桌面 GUI：gui_list、gui_state 和 gui_action，用于控制原生 Linux/Windows/macOS 应用，优先按无障碍信息定位，失败时回退到截图；Native WebUI 还通过同一套后端提供低带宽的 WebSocket 桌面流，无需逐帧的工具 RPC。
- 文件链接：link_create、link_list、link_revoke。
- 远程 worker：remote_manage，支持 invite、list、rename 和 revoke 操作；常规执行工具接受可选的 machine。
- 智能体技能：skill_list、skill_load、skill_read。
- 会话：session_manage，用于持久化任务上下文、进度交接、智能体运行接管，以及跨运行继承。
- 规划：plan_manage，用于可选的 Session 自有 Goal 模式与自动续跑。
- 诊断：environment_get（含版本信息）、secret_scan 和 audit_tail。

run_shell 和 run_python 都接受 persist_on_timeout（默认 false）。把它设为 true，命令会作为受跟踪任务启动，并最多等待 timeout_s；如果命令仍在运行，工具会返回 timed_out: true、job_id 和 job_status，不会停止或重跑命令。接着用 job_tail、 job_list 和 job_stop 继续操作，远程任务要传同一个 machine。开启该选项的调用使用任务运行器的 stdout/stderr 合并日志，命令在等待期内结束也一样。

lsm call run_shell --json '{"command":"make test","timeout_s":10,"persist_on_timeout":true}'
lsm call run_python --json '{"code":"import time; time.sleep(60)","timeout_s":10,"persist_on_timeout":true}'

完整的工具参考见 docs，其中列出每个工具的用途、输入、返回、组合用法和注意事项。

相关项目

下面这些项目独立维护，围绕 LSM 探索相近的会话与编排模型：

- rijuyuezhu/local-shell-mcp 采用另一种面向执行的会话模型，把工作区上下文和相关资源绑定到显式会话。它有自己的工具接口和发布周期。
- DongYaoZe/localshell-web-supervisor 是本地可靠性编排层，服务于用 Local Shell MCP 的浏览器驱动智能体。它监管可替换的浏览器 worker，同时协调持久化的 LSM 会话、Goal/job 以及实际的工作区/Git 状态，并提供带保护的租约、交接、接管和恢复流程。它不属于 LSM 运行时，也不在 LSM 的发布周期内。

Star History

安全模型

本项目有意暴露能力很强的工具。请把接入的模型当作拥有容器或 VM 的控制权。

默认防护包括：

- 工作区限定在 /workspace，除非显式启用全容器模式。
- 命令超时、输出上限和并发上限。
- 针对主机控制片段的默认命令/路径拒绝列表。
- Shell 预检是一道尽力而为的效率防线，针对常见的递归发现写法（例如 Get-ChildItem -Recurse、find、rg、grep -R）：拦截已识别的大范围无界扫描，为范围较窄但开销大的发现操作设定边界，并把智能体引导到限定范围的文件工具上。它不是 Shell 的安全边界。
- 对 Shell 子进程做环境变量过滤，防止服务端密钥泄露。
- 动态 stdio MCP 服务器只继承最小化的操作系统环境，外加按服务器显式配置的变量；配置的环境变量和请求头值存放在权限为 0600 的状态文件中，并在工具结果和 Audit 参数中脱敏。
- 审计日志位于 /workspace/.local-shell-mcp/audit.jsonl。
- 提交和推送前运行密钥扫描辅助工具。
- 带 token 的文件链接，支持 TTL、下载次数限制和吊销。

硬性规则：

1. 不要挂载 /var/run/docker.sock。
2. 不要挂载宿主机根文件系统。
3. 不要在公网环境下用 LOCAL_SHELL_MCP_AUTH_MODE=none 暴露服务。
4. 不要把长期有效的凭据放进模型可见的环境变量。
5. 优先使用单仓库部署密钥或短期 token。
6. 在一次性容器或虚拟机中运行服务。
7. 把 local-shell-mcp-credentials Docker 卷视为敏感数据。

漏洞上报请阅读 SECURITY.md。

配置

标准部署请复制 .env.example。配置参考 记录了全部环境变量，以及高级部署可选用的 YAML 格式。

重要选项：

| 设置 | 用途 |
| LOCAL_SHELL_MCP_PUBLIC_BASE_URL | OAuth 和 ChatGPT 使用的公网 HTTPS 源。 |
| LOCAL_SHELL_MCP_AUTH_MODE | 公网部署请用 oauth。 |
| LOCAL_SHELL_MCP_ALLOW_FULL_CONTAINER | 仅在一次性容器/虚拟机中关闭工作区限制。 |
| LOCAL_SHELL_MCP_REMOTE_ENABLED | 启用或禁用远程 worker 控制工具。 |
| LOCAL_SHELL_MCP_UI_ENABLED | 挂载或禁用共享的 OpenTUI/WebUI 人机界面。 |
| LOCAL_SHELL_MCP_UI_PATH | 同一服务上的 WebUI 挂载路径，默认 /ui。 |
| LOCAL_SHELL_MCP_UI_WALLPAPER | 为 OpenTUI 浏览器控制台背景选择 bing、aurora 或 none。 |
| LOCAL_SHELL_MCP_SHELL_ENV_BLOCKLIST | 从派生的 Shell 进程中移除的环境变量。 |
| LOCAL_SHELL_MCP_FILE_DOWNLOAD_ENABLED | 启用带 token 的文件下载链接。 |

开发

安装开发依赖并运行检查：

python -m venv .venv
. .venv/bin/activate
pip install -e '.[dev,docs]'
ruff check .
pytest -q
mkdocs build --strict

构建 VS Code 扩展：

npm --prefix vscode-extension install
npm --prefix vscode-extension run compile

贡献流程见 CONTRIBUTING.md。

项目文档

- 文档站点
- 贡献指南
- 安全策略
- 行为准则
- 支持指南
- OAuth 配置
- 许可证