local-shell-mcp
Enables LLM to use a cli environment.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/fwerkor/local-shell-mcp with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/fwerkor/local-shell-mcp'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/fwerkor--local-shell-mcp)HTML
<a href="/listings/fwerkor--local-shell-mcp"><img src="/api/listings/fwerkor--local-shell-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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](https://fwerkor.github.io/local-shell-mcp/). Runtime choices are documented separately from client connections.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 326 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- <div align="center">
- <img src="docs/assets/logo.svg" alt="local-shell-mcp logo" width="152">
- # local-shell-mcp
- **A self-hosted AI workspace and MCP control plane for shell, files, browsers, and remote machines.**
- [](https://fwerkor.github.io/local-shell-mcp/)
- [](https://github.com/fwerkor/local-shell-mcp/actions/workflows/ci.yml)
- [](https://www.dsh.so/artifact/local-shell-mcp)
- [](https://github.com/fwerkor/local-shell-mcp/releases)
- [](https://github.com/fwerkor/local-shell-mcp)
- [](https://github.com/fwerkor/local-shell-mcp/pkgs/container/local-shell-mcp)
- [](LICENSE)
- [Documentation](https://fwerkor.github.io/local-shell-mcp/) · [Quickstart](https://fwerkor.github.io/local-shell-mcp/getting-started/quickstart/) · [Runtime choices](https://fwerkor.github.io/local-shell-mcp/guides/deployment/) · [Web workspace](https://fwerkor.github.io/local-shell-mcp/getting-started/web-workspace/) · [Gemini Spark](https://fwerkor.github.io/local-shell-mcp/getting-started/gemini-spark/) · [ChatGPT connector](https://fwerkor.github.io/local-shell-mcp/getting-started/chatgpt-connector/) · [DSH plugin](https://fwerkor.github.io/local-shell-mcp/clients/deepseek-harness/) · [Tools](https://fwerkor.github.io/local-shell-mcp/reference/tools/) · [Releases](https://github.com/fwerkor/local-shell-mcp/releases)
- </div>
- ---
- `local-shell-mcp` combines a self-hosted AI chat workspace with controlled access to a real execution environment. The unified browser UI is the recommended daily entry point; ChatGPT, Gemini and other external MCP clients remain supported. 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.
- ```text
- Runtime: Docker / VS Code extension / binary / Python / stdio
- -> exposure: localhost, HTTPS proxy/tunnel, or stdio pipe
- -> client: unified LSM WebUI (optional), ChatGPT, Gemini, 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. |
- | Unified web workspace | Chat, projects, history, files, terminals, desktop, sessions, remotes, audit and nested MCP management in one browser UI. |
- | External MCP clients | OAuth 2.1 and `/mcp` for ChatGPT, Gemini and other compatible clients. |
- | 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
- **Recommended deployment: the standalone single-file Controller executable** from [GitHub Releases](https://github.com/fwerkor/local-shell-mcp/releases/latest). It bundles the Controller and native WebUI, runs without a system Python installation or Docker, and needs no repository checkout. Choose the matching binary for your OS/architecture; the following example is for **Linux x86_64**:
- ```bash
- mkdir -p ~/lsm && cd ~/lsm
- curl -fL https://github.com/fwerkor/local-shell-mcp/releases/latest/download/local-shell-mcp-linux-x86_64 -o local-shell-mcp
- chmod +x local-shell-mcp
- ./local-shell-mcp --help
- openssl rand -hex 32
- ```
- Create a private `.env` file with the necessary `LOCAL_SHELL_MCP_` variables (see the [quickstart](https://fwerkor.github.io/local-shell-mcp/getting-started/quickstart/)). Use a strong OAuth PIN and the generated JWT secret, then start the executable with those variables explicitly exported:
- ```bash
- chmod 600 .env
- set -a
- . ./.env
- set +a
- mkdir -p workspace
- export LOCAL_SHELL_MCP_WORKSPACE_ROOT="$PWD/workspace"
- ./local-shell-mcp --mode mcp
- ```
- Check `http://127.0.0.1:8765/healthz` and open the native UI at `http://127.0.0.1:8765/ui`. For remote access, prefer a public HTTPS server or reverse proxy; Cloudflare Tunnel is not recommended for file-heavy transfers. Keep OAuth enabled on publicly accessible endpoints.
- The one-file executable is the **Controller distribution**, not an all-inclusive operating-system image. It uses host-installed task tools and optional external Playwright/browser dependencies. Integrated **chat and projects** use the separately deployed [unified web workspace](https://fwerkor.github.io/local-shell-mcp/getting-started/web-workspace/) (Node.js, MongoDB, Meilisearch, and SearXNG); the remote **Worker** is distributed separately. No chat backend or database is claimed to be embedded in the Controller binary.
- Other deployment methods remain supported: [Docker Compose](https://fwerkor.github.io/local-shell-mcp/installation/docker/), [Python/pipx/source](https://fwerkor.github.io/local-shell-mcp/installation/python/), and the [VS Code extension](https://fwerkor.github.io/local-shell-mcp/installation/vscode-extension/). See [platform-specific binary installation](https://fwerkor.github.io/local-shell-mcp/installation/binary/) for Windows, macOS, ARM64 and updates.
- ## Human interface
- The **recommended interface** is the [unified web workspace](https://fwerkor.github.io/local-shell-mcp/getting-started/web-workspace/), which integrates chat and LSM Controller pages directly into a modified LibreChat React application. It uses the LSM login, stores chat projects and history on the server, and manages external tools through LSM's nested MCP registry. Its Node.js, MongoDB, Meilisearch and SearXNG services are **optional**, deployed separately from the lightweight Controller and Worker bundles.
- The Controller also retains two lightweight fallback 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 an optional terminal-oriented interface with Dashboard, Files, Terminals, Remotes, and Audit screens. Build the native sidecar separately (`cd ui && bun run build:tui`) or install a Python wheel that embeds it. The browser console and native `local-shell-mcp tui` command appear when the runtime is installed.
- Open the browser interface on the service origin:
- ```text
- http://127.0.0.1:8765/ui
- ```
- When OpenTUI is installed, the OAuth screen lets you choose Web UI or OpenTUI before authorization, and the interface selector can switch modes after login. 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 and Docker images include the WebUI and native terminal but **do not bundle OpenTUI**. Their TUI controls are hidden unless a separately installed runtime is available. The Python wheel and source-development build retain optional OpenTUI support. To enable it, install an appropriate sidecar, set `LOCAL_SHELL_MCP_UI_TUI_COMMAND=/path/to/local-shell-mcp-tui`, and launch:
- ```bash
- local-shell-mcp tui
- ```
- The lean Docker image includes Python runtime dependencies, common shell utilities, and tmux. It does not include toolchains, Node.js, office suites, scientific Python packages, **Playwright, or browser binaries**. These can be installed in a derived image or the agent workspace when required.
- Playwright is an **optional external dependency** for standalone binaries. The built-in `browser_session`, `browser_snapshot`, and `browser_act` interfaces use an external Python child process, while `browser_get_text`, `browser_capture`, and `browser_run_script` already execute scripts using the configured Python. Install Playwright and a browser into that Python environment:
- ```bash
- python3 -m pip install playwright
- python3 -m playwright install chromium
- # If using a dedicated virtual environment, point LSM to its interpreter:
- # LOCAL_SHELL_MCP_PYTHON_BIN=/path/to/venv/bin/python
- ```
- Python-wheel installations can enable browser support with `pip install 'local-shell-mcp[browser]'`, then install the desired browser. Without Playwright, ordinary LSM features work as usual; browser calls report the missing dependency. In containers, browser system dependencies can be installed on demand using `python -m playwright install --with-deps chromium`.
- 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:
- ```bash
- 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](https://fwerkor.github.io/local-shell-mcp/guides/human-interface/).
- ## External MCP clients
- The built-in web workspace is the primary browser experience. External clients connect separately using LSM's `/mcp` endpoint; consult [Gemini Spark / Custom Apps](https://fwerkor.github.io/local-shell-mcp/getting-started/gemini-spark/) or the [ChatGPT connector](https://fwerkor.github.io/local-shell-mcp/getting-started/chatgpt-connector/).
- 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://fwerkor.github.io/local-shell-mcp/getting-started/chatgpt-connector/).
- ## DeepSeek Harness plugin
- [](https://www.dsh.so/artifact/local-shell-mcp)
- The DSH bridge is published separately as `local-shell-mcp-dsh`. With a normal LSM HTTP/MCP service running on the same host, install the plugin into a DSH profile:
- ```bash
- dsh plugin --profile web add local-shell-mcp-dsh
- ```
- The bundle uses an LSM-aware Streamable HTTP bridge and keeps the complete LSM tool surface, including `remote_manage`, `remote_transfer`, browser tools, and Dynamic MCP tools. Each DSH Session receives a stable v4 logical-session identity, so its Logical Session, active run, Activity, and native **Live Workspace** view stay isolated from other DSH conversations and survive DSH-side MCP transport recreation. DSH sees model tools under the normal `mcp__lsm__*` namespace. The DSH npm package follows the same release version as LSM. Repository installs remain useful for development from a checkout.
- See the [DeepSeek Harness integration guide](https://fwerkor.github.io/local-shell-mcp/clients/deepseek-harness/).
- ## VS Code extension runtime
- Release assets include `local-shell-mcp-<version>.vsix`. The extension is a runtime launcher for the current VS Code workspace. It starts the same server, checks `/healthz`, copies the MCP URL, and copies a ready-to-paste ChatGPT setup prompt.
- Basic flow:
- ```text
- Install executable -> install VSIX -> open a workspace -> Start Server -> copy MCP URL
- ```
- For public ChatGPT access, expose the local server through an HTTPS tunnel and set `local-shell-mcp.publicBaseUrl` in VS Code settings. Keep `local-shell-mcp.allowFullContainer` disabled for direct host usage; enable it only inside disposable containers or VMs.
- ## Remote workers
- Remote worker mode is enabled by default. Create a one-time invite on the control server, paste the generated command on a remote machine, then use the normal tools with their optional `machine` argument. Only worker administration retains `remote_*` names.
- This is intended for:
- - HPC login nodes or compute nodes behind firewalls.
- - NPU/GPU servers without inbound connectivity.
- - Lab machines that can make outbound HTTPS requests.
- - Temporary build hosts or remote test environments.
- See the [remote workers guide](https://fwerkor.github.io/local-shell-mcp/guides/remote-workers/).
- ## Agent Skills
- Skills are discovered from three ordered sources: project-level `/workspace/.agents/skills`, the LSM-managed `/workspace/.local-shell-mcp/agent_config/skills`, and global `~/.config/agents/skills`. Higher-priority sources override lower-priority Skills with the same name, and symlinked Skill directories and files are supported.
- This makes the universal Skills CLI layout work directly, for example `npx skills add owner/repo --agent universal -y`. Use `skill_list` to discover installed Skills, `skill_load` to load one instruction set, and `skill_read` to read a related file by the returned Skill-relative path. Changes are detected on the next call; no per-Skill MCP tools are registered and no client reconnect is required.
- See the [Agent Skills guide](https://fwerkor.github.io/local-shell-mcp/guides/skills/).
- ## Tool surface
- The public MCP surface includes:
- - Live Workspace: `workspace_open` opens the reconnectable MCP App for the current logical Session.
- - Shell and jobs: `run_shell`, `run_python`, persistent `shell_*`, and tracked `job_*` tools. Use `run_shell` for Git CLI operations.
- - Filesystem: `file_list`, `file_tree`, `file_glob`, `file_grep`, unified `file_read`, native-vision `image_view`, `file_write`, unified `file_edit`, `file_delete`, and `file_patch`.
- - Transfer: `remote_transfer` for files or directories across controller and worker endpoints.
- - Dynamic MCP: `mcp_manage`, `mcp_tool_search`, `mcp_tool_inspect`, and `mcp_tool_call`. External tools are discovered progressively and never expand LSM's own `tools/list` surface.
- - Browser: persistent high-level `browser_session`, `browser_snapshot`, and `browser_act`; `browser_run_script` is the low-level Playwright escape hatch.
- - Desktop GUI: `gui_list`, `gui_state`, and `gui_action` for native Linux/Windows/macOS application control with accessibility-first targeting and screenshot fallback; Native WebUI also provides a low-bandwidth WebSocket Desktop stream over the same backends without per-frame tool RPCs.
- - File links: `link_create`, `link_list`, `link_revoke`.
- - Remote workers: `remote_manage` with `invite`, `list`, `rename`, and `revoke` actions; normal execution tools accept optional `machine`.
- - Agent Skills: `skill_list`, `skill_load`, `skill_read`.
- - Sessions: `session_manage` for durable task context, progress handoff, agent-run takeover, and cross-run inheritance.
- - Planning: `plan_manage` for optional Session-owned Goal mode and automatic continuation.
- - Diagnostics: `environment_get` (including version information), `secret_scan`, and `audit_tail`.
- Both `run_shell` and `run_python` accept `persist_on_timeout` (default `false`). Set it to
- `true` to start the command as a tracked job and wait up to `timeout_s`; if it is still
- running, the tool returns `timed_out: true`, `job_id`, and `job_status` without stopping
- or rerunning the command. Continue with `job_tail`, `job_list`, and `job_stop`, supplying
- the same `machine` for remote jobs. Opted-in calls use the job runner's combined
- stdout/stderr log, including when the command finishes within the wait period.
- ```bash
- 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}'
- ```
- The detailed tool reference, including purpose, inputs, returns, combinations, and notes for every tool, is available in the [docs](https://fwerkor.github.io/local-shell-mcp/reference/tools/).
- ## Related projects
- The following independently maintained projects explore adjacent session and orchestration models around LSM:
- - [rijuyuezhu/local-shell-mcp](https://github.com/rijuyuezhu/local-shell-mcp) uses a different, execution-oriented session model that binds workspace context and related resources to explicit sessions. It has its own tool surface and release lifecycle.
- - [DongYaoZe/localshell-web-supervisor](https://github.com/DongYaoZe/localshell-web-supervisor) is a local reliability and orchestration layer for browser-driven agents using Local Shell MCP. It supervises replaceable browser workers while reconciling durable LSM sessions, Goals/jobs, and actual workspace/Git state, with guarded lease, handoff, takeover, and recovery flows. It is not part of the LSM runtime or release lifecycle.
- ## Star History
- <a href="https://www.star-history.com/fwerkor/local-shell-mcp">
- <picture>
- <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=fwerkor/local-shell-mcp&type=Date&theme=dark" />
- <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=fwerkor/local-shell-mcp&type=Date" />
- <img alt="Star History Chart for fwerkor/local-shell-mcp" src="https://api.star-history.com/svg?repos=fwerkor/local-shell-mcp&type=Date" />
- </picture>
- </a>
- ## Security model
- This project intentionally exposes powerful tools. Treat the connected model as having control of the container or VM.
- Default protections include:
- - Workspace scoping to `/workspace` unless full-container mode is explicitly enabled.
- - Command timeouts, output limits, and concurrency limits.
- - Default command/path denylists for host-control fragments.
- - Shell preflight is a best-effort efficiency guard for common recursive discovery forms (for example `Get-ChildItem -Recurse`, `find`, `rg`, and `grep -R`): it blocks recognized wide unbounded scans, bounds narrower expensive discovery, and redirects agents toward scoped file tools. It is not a shell security boundary.
- - Shell subprocess environment filtering for service-side secrets.
- - Dynamic stdio MCP servers inherit only a minimal OS environment plus explicitly configured per-server variables; configured environment/header values are stored in a mode-`0600` state file and redacted from tool results and Audit arguments.
- - Audit logs at `/workspace/.local-shell-mcp/audit.jsonl`.
- - Secret scanning helpers before commits and pushes.
- - Tokenized file links with TTL/download limits and revocation.
- Hard rules:
- 1. Do not mount `/var/run/docker.sock`.
- 2. Do not mount the host root filesystem.
- 3. Do not expose the service with `LOCAL_SHELL_MCP_AUTH_MODE=none` on a public network.
- 4. Do not put long-lived credentials in environment variables visible to the model.
- 5. Prefer single-repository deploy keys or short-lived tokens.
- 6. Run the service in a disposable container or VM.
- 7. Treat the `local-shell-mcp-credentials` Docker volume as sensitive.
- For vulnerability reporting, read [SECURITY.md](SECURITY.md).
- ## Configuration
- Copy [`.env.example`](.env.example) for the standard setup. The [configuration reference](https://fwerkor.github.io/local-shell-mcp/reference/configuration/) documents every environment variable and the optional YAML format for advanced deployments.
- Important options:
- | Setting | Purpose |
- |---|---|
- | `LOCAL_SHELL_MCP_PUBLIC_BASE_URL` | Public HTTPS origin used by OAuth and ChatGPT. |
- | `LOCAL_SHELL_MCP_AUTH_MODE` | Use `oauth` for public deployments. |
- | `LOCAL_SHELL_MCP_ALLOW_FULL_CONTAINER` | Disable workspace restrictions only in disposable containers/VMs. |
- | `LOCAL_SHELL_MCP_REMOTE_ENABLED` | Enable or disable remote worker control tools. |
- | `LOCAL_SHELL_MCP_UI_ENABLED` | Mount or disable the shared OpenTUI/WebUI human interface. |
- | `LOCAL_SHELL_MCP_UI_PATH` | WebUI mount path on the same service; default `/ui`. |
- | `LOCAL_SHELL_MCP_UI_WALLPAPER` | Select `bing`, `aurora`, or `none` for the OpenTUI browser console background. |
- | `LOCAL_SHELL_MCP_SHELL_ENV_BLOCKLIST` | Environment variables removed from spawned shell processes. |
- | `LOCAL_SHELL_MCP_FILE_DOWNLOAD_ENABLED` | Enable tokenized file download links. |
- ## Development
- Install development dependencies and run checks:
- ```bash
- python -m venv .venv
- . .venv/bin/activate
- pip install -e '.[dev,docs]'
- ruff check .
- pytest -q
- mkdocs build --strict
- ```
- Build the VS Code extension:
- ```bash
- npm --prefix vscode-extension install
- npm --prefix vscode-extension run compile
- ```
- Contribution workflow is documented in [CONTRIBUTING.md](CONTRIBUTING.md).
- ## Project documents
- - [Documentation site](https://fwerkor.github.io/local-shell-mcp/)
- - [Contributing guide](CONTRIBUTING.md)
- - [Security policy](SECURITY.md)
- - [Code of conduct](CODE_OF_CONDUCT.md)
- - [Support guide](SUPPORT.md)
- - [OAuth setup](OAUTH_SETUP.md)
- - [License](LICENSE)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.