<div align="center"> <img src="docs/assets/logo.svg" alt="local-shell-mcp logo" width="152">

local-shell-mcp

A ChatGPT-ready MCP control plane for shell, files, browser automation, file links, and remote machines.

Docs CI dsh.so security Release Python Docker License

Documentation · Quickstart · Runtime choices · ChatGPT connector · DSH plugin · Tools · Releases

</div>

---

local-shell-mcp gives ChatGPT Developer Mode and other MCP clients controlled access to a real execution environment. It exposes a dedicated workspace with shell, persistent shell, filesystem, search, patch, Playwright, audit, durable logical sessions with optional Goal plans, public file links, and outbound remote-worker access. Git is handled through ordinary shell commands instead of a parallel wrapper 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)

The intended safety boundary is the container or VM, not the host.

Why use it

Capability	What it enables
Real terminal access	Run tests, build projects, inspect logs, and debug with persistent shell sessions.
Workspace-aware file tools	Read, write, patch, search, and review files under a controlled root.
Git workflow support	Run the standard Git CLI through shell tools without a second, incomplete Git abstraction.
Browser automation	Extract page text, capture PNG/PDF evidence, or run a full Playwright script.
Native desktop GUI	Observe accessibility trees plus screenshots and control Linux, Windows, or macOS applications with guarded semantic/coordinate actions.
Remote workers	Control NAT, firewall, HPC, NPU, or lab machines that can only connect outward.
Agent Skills	Discover, load, and read reusable SKILL.md workflows through three fixed tools without changing the MCP tool list.
ChatGPT connector support	OAuth 2.1, /mcp, discovery controls, and ChatGPT-compatible tool schemas.
DeepSeek Harness plugin	Install this repository as a DSH bundle and expose the complete LSM tool surface, including remote workers.
ChatGPT Live Workspace	Render a native MCP App for real-time activity, terminal, files, diffs, jobs, remotes, audit, and direct human/agent collaboration inside ChatGPT.
Safer operations	Workspace scoping, shell timeouts, output limits, environment filtering, audit logs, and secret scanning.

Quick start

Install the official launcher or Python package when you want a host runtime:

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

The npm and Python distributions both expose local-shell-mcp; installed packages also expose lsm as the short command. The npm distribution is only a verified launcher for the matching standalone release binary, not a second server implementation.

Clone the repository and prepare configuration:

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

Set at least these values in .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=

Start the server:

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

Start the bundled Cloudflare Tunnel sidecar when you need public HTTPS access:

docker compose --profile tunnel up -d

The public MCP endpoint is:

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

Full setup instructions are in the documentation. Runtime choices are documented separately from client connections.

Human interface

The service includes two compatible human interfaces backed by the same authenticated API and state:

• Web UI is a native browser dashboard for system health, machines, workloads, recent MCP activity, and alerts.
• OpenTUI is the full terminal-oriented interface with Dashboard, Files, Terminals, Remotes, and Audit screens. It remains available in the browser as a selectable console and as the native local-shell-mcp tui command.

Open the browser interface on the service origin:

http://127.0.0.1:8765/ui

The OAuth screen lets you choose Web UI or OpenTUI before authorization. After login, switch modes at any time from the interface selector. Native Web UI routes use URL hashes such as #/overview and #/console, so a selected mode or page can be bookmarked. The OpenTUI console retains the existing authenticated xterm.js/PTY transport, mouse interaction, automatic resizing, reconnects, fullscreen mode, and mobile shortcut row.

Standalone release executables embed the native OpenTUI runtime, while Docker images provide it inside the image. Start the service, then launch it without a human login prompt:

local-shell-mcp tui

The native TUI authenticates the loopback Human UI API with the same host-only dedicated CLI credential used by lsm call; split-runtime layouts can pass --token-file. Browser-spawned OpenTUI uses a controller-process credential created lazily in memory and never writes that privileged credential to the state directory or state backend. A dedicated local CLI credential can also invoke the registered MCP tool surface directly from shell scripts; the Human UI token is intentionally never accepted by /mcp. By default, call connects to the running loopback controller, so remote-worker calls use the live controller process instead of a separate process-local worker registry:

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

Use --session s_... to attach an ordinary tool call to a durable logical Session. In the documented Docker Compose setup, the raw LOCAL_SHELL_MCP_CLI_LOCAL_TOKEN stays only in the host-owned, permission-restricted .env; Compose passes only its SHA-256 verifier into the controller, and the CLI reads the raw value without initializing server state. Other split-runtime layouts can use --token-file <path> or the same environment variable, with the matching LOCAL_SHELL_MCP_CLI_LOCAL_TOKEN_SHA256 configured on the controller. A failed underlying command makes lsm call exit non-zero. --direct is available for standalone local calls when no controller is running; remote workers are intentionally unavailable in direct mode.

The worker-installed local-shell-mcp launcher is management-only (worker start, worker status, etc.); it exposes neither call nor tui. The worker download contains only explicitly selected execution modules, not the Controller CLI, TUI, or WebUI. Workers receive and report tasks but cannot initiate controller tool calls using worker credentials.

Files remains an LSM-native three-pane file manager inside OpenTUI for local and remote machines. It renders bounded PNG/JPEG/GIF/WebP thumbnails and provides consistent file operations through the shared service API. Manual actions entered through either human interface are excluded from the MCP audit log; Activity, Audit, and the terminal audit rail show model-originated MCP activity.

See the human interface guide.

ChatGPT setup

For full shell, filesystem, remote-worker, and Playwright tools, use ChatGPT Developer Mode or another full MCP client. ChatGPT is a client connection; choose and start a runtime first.

session_manage provides one durable logical task context for agent work. A Session is deliberately independent of machine and working directory: it stores the task objective, semantic progress reports, recent execution Activity, and an optional Plan. session_id is the only durable task identity. To continue work in another ChatGPT conversation, the user explicitly passes the existing session_id, and the new agent calls session_manage(action="resume", session_id=...). Agents do not list or auto-select Sessions from other conversations. They should report the active session_id after start/resume, at meaningful progress checkpoints, and before ending a turn, while using session_manage(action="report", session_id=...) for semantic progress rather than copying every tool result into the summary. Ordinary tools receive the same task identity as logical_session_id.

When the client supports MCP Apps, workspace_open(session_id=...) opens the execution view for the explicitly selected Session as a floating MCP App and can expand to fullscreen. The v3 name open_live_workspace remains a hidden, non-enumerated compatibility alias for ChatGPT clients with a cached recipient; new integrations see and use only workspace_open. The Live Workspace is a reconnectable viewer and collaboration surface, not the owner of task state: closing it or reconnecting MCP does not discard Session progress, Activity, or its Plan. Ordinary MCP tools remain the execution API, while the app adds live operational activity, persistent terminals, file/diff inspection, jobs, remotes, audit data, and the active Session id. Clients that do not render MCP Apps continue to use the normal tool surface unchanged.

plan_manage(session_id=...) optionally enables Goal mode on that explicit Session for substantial multi-step work. An active Plan is the goal: its steps can be revised as execution changes and, while a Live Workspace is attached, the app can request continuation after 15 minutes without agent tool activity. Automatic continuation is capped at 10 continuation attempts (accepted or rejected) and resumes the same Session before continuing. Blocked, completed, and cancelled Plan statuses are never nudged; an active Plan whose steps are all completed or skipped remains eligible for cleanup continuation so a resumed agent can call plan_manage(action="finish"). A Session does not require a Plan.

1. Expose the server through HTTPS.
2. Keep OAuth enabled.
3. Add the MCP endpoint: https://your-public-host.example.com/mcp.
4. Complete the OAuth authorization flow.
5. Start with a bounded task and inspect the audit log when needed.

Read the dedicated [ChatGPT connector guide](https://fwerko