Preface¶

When developing agents in DeepSeek Harness (DSH), a common bottleneck is that models can only “talk” but cannot “act”: running tests, modifying files, checking logs, and operating Git often require manually switching terminals outside the conversation. Some MCP solutions only offer fragmented file read/write or simplified Git wrappers, still distant from real development environments.

fwerkor/local-shell-mcp (hereafter LSM) exposes a controlled execution environment to clients via MCP. The repository includes a DSH bridge package that integrates the full LSM tool surface into DSH Web and binds each DSH Session to an independent logical session and Live Workspace. Below, we introduce what it is, what it can do, and how to install and enable it in DSH.

What is this¶

LSM is maintained by fwerkor and has approximately 54 stars and 13 forks on GitHub, categorized under Client in SkillHub. The project is positioned as: a shell, file, browser automation, and remote machine control plane for ChatGPT Developer Mode and other MCP clients.

As a DSH plugin, the bundle name is local-shell-mcp-dsh (current version 4.2.1, MIT license). It does not replace the LSM server but allows DSH to connect to a running LSM controller via HTTP, registers mcp__lsm__* tools into the conversation, and embeds a Live Workspace view in DSH Web.

The security boundary lies within the workspace in a container or VM, not fully exposing the host machine. When deployed on the same machine, LSM defaults to listening on 0.0.0.0:8765, and the DSH bridge defaults to accessing http://127.0.0.1:8765/mcp via loopback.

Core features¶

The following capabilities are derived from the project README and DSH integration documentation, organized by module.

Terminal and Files¶

• Shell Execution: Single commands and persistent shell sessions, suitable for running tests, builds, and checking logs.
• Workspace File Tools: Reading, writing, patching, and searching files under a controlled root directory.
• Git: Standard Git CLI calls via ordinary shell commands, rather than a separate Git abstraction layer.

Sessions and Plans¶

• Logical Sessions: session_manage provides task contexts that are resumable across turns and conversations; session_id serves as a persistent task identifier.
• Goal / Plan: Optional planning and progress reports, stored alongside activity and audit data on the LSM controller.

Browser and Remote¶

• Playwright: Page text extraction, PNG/PDF screenshots, and full browser scripting.
• Remote Workers: Connecting to machines behind NAT or firewalls via outbound HTTP(S); DSH can also use mcp__lsm__remote_manage, mcp__lsm__remote_transfer, and regular tools with a machine parameter.

DSH-Specific Integration¶

• Full Tool Surface: Model-visible tools include mcp__lsm__run_shell, mcp__lsm__file_read, mcp__lsm__browser_session, mcp__lsm__session_manage, mcp__lsm__plan_manage, etc., under the mcp__lsm__* namespace.
• Session Binding: Each DSH Session corresponds to a stable LSM logical session and an independent Live Workspace timeline; activities from different conversations do not merge.
• Live Workspace: Displays terminals, files, diffs, jobs, remote machines, and audits in the DSH conversation view; credentials are obtained server-side via MCP connection by the DSH Host and not written into model-visible tool results.

Operations and UI¶

LSM includes a Web UI (http://127.0.0.1:8765/ui) and OpenTUI terminal interface for health checks, machine lists, recent MCP activities, and alerts. Mechanisms like workspace scope restrictions, shell timeouts, output limits, environment variable filtering, audit logs, and secret scanning are documented in the README.

Recommended topology¶

Same-machine deployment is the documented recommended approach:

DSH Web
  |
  | One LSM MCP connection per DSH Session
  | 127.0.0.1:8765/mcp
  v
local-shell-mcp :8765
  |-- Local execution = this LSM host
  |-- /mcp, /remote/*, /ui
  |-- Live Workspace / audit / browser / jobs
  |
  +--> Remote Workers

Integration uses HTTP instead of stdio because Remote Workers rely on the controller’s /remote/* routes beyond MCP tools; a single stdio subprocess cannot preserve this service plane.

Installation and enablement¶

1. Prepare LSM runtime¶

Install the official launcher or Python package (Python 3.11+):

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

For source deployment, copy the environment configuration and set variables like LOCAL_SHELL_MCP_PUBLIC_BASE_URL as per the documentation, then start with Docker Compose:

git clone https://github.com/fwerkor/local-shell-mcp.git
cd local-shell-mcp
cp .env.example .env
mkdir -p workspaces/default
docker compose up -d
curl -i http://127.0.0.1:8765/healthz

2. Start MCP service¶

Before DSH integration, run LSM in MCP mode:

local-shell-mcp --mode mcp

The bundle will not start a second LSM process; if LSM is not ready, the bridge will back off and reconnect, synchronizing the tool directory once the service is online.

3. Install DSH plugin¶

Install this repository in the DSH Web profile:

dsh plugin --profile web add 'github:fwerkor/local-shell-mcp#main'

For production, pin the Git reference to a reviewed release tag or commit. For local development, install from a checked-out directory:

dsh plugin --profile web add .

4. Verification¶

Check the combined DSH configuration:

dsh --profile web --dump-config

The output should include entries like:

id: local-shell-mcp
name: local-shell-mcp-dsh
url: http://127.0.0.1:8765/mcp

Once LSM is online, tools like mcp__lsm__run_shell, mcp__lsm__remote_manage, and mcp__lsm__session_manage should be visible in conversations; non-empty DSH Web conversations should also show a Live Workspace view entry.

5. Optional environment variables¶

Same-machine deployment typically does not require Authorization; do not expose an unauthenticated LSM to the public internet. Example for a remote protected controller:

export DSH_LSM_MCP_URL='https://lsm.example.com/mcp'
export DSH_LSM_AUTHORIZATION='Bearer <token>'
dsh --profile web

Uninstall plugin (without stopping the LSM process):

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

Typical usage¶

Executing commands in the shell¶

The model executes builds, tests, or Git operations in the workspace via mcp__lsm__run_shell. Persistent shells are suitable for continuous debugging where environment variables need to be retained.

Managing cross-turn tasks¶

When starting a task, call session_manage(action="start", ...); for cross-conversation continuation, explicitly pass an existing session_id and resume. Agents should report semantic progress using report at critical points and inform the current session_id before the turn ends.

Operating remote machines¶

In environments with registered Remote Workers, use remote_manage, remote_transfer, or regular tools with a machine parameter to share the same controller state with other LSM clients like ChatGPT.

Viewing Live Workspace in DSH¶

After starting a conversation, enter the Live Workspace from the session view to view terminals, file changes, jobs, and audit records bound to the current DSH Session; UI operations access the LSM API via server-side credentials, not through the model context.

Use cases and notes¶

Who is it for

• Agent developers who need to run CLI commands, modify code, and view diffs directly within DSH conversations.
• Teams with or planning to deploy LSM controllers that may connect to remote workers behind firewalls.
• Scenarios where Live Workspace is used to consolidate viewing execution activities instead of pasting large command outputs in conversations.

Please note before use

1. Permission boundaries: The plugin runs with the current DSH process permissions, and LSM tools can execute shell and file operations within the configured workspace. Before installation, read the source code and MIT license to ensure the workspace root directory and network exposure comply with your security policy.
2. Start LSM first, then install the plugin: The bundle only handles bridging, not starting the controller.
3. No replay on transmission failure: In case of ambiguous transmission failures, model tool calls will not be automatically replayed, preventing changeable operations like shell/file/remote from being executed twice.
4. Node version: The DSH bundle requires Node.js >= 22 (see repository package.json).
5. Community directory: SkillHub is a community site for Skills targeting Chinese users and has no official affiliation with DeepSeek / High-Flyer; plugin information is based on the directory page and GitHub repository.

Conclusion¶

local-shell-mcp converges real CLI environments, file workspaces, browser automation, and remote workers into a single MCP control plane; as a DSH plugin, it retains the full mcp__lsm__* tool surface and provides an independent Live Workspace for each session. If you are building agents in DSH that can modify code and run commands, you can first deploy LSM on the same machine, then follow the steps above to integrate with DSH Web.

• SkillHub directory page: fwerkor/local-shell-mcp
• GitHub repository: github.com/fwerkor/local-shell-mcp
• DSH integration documentation: DeepSeek Harness (DSH)