linux-harness-mcp

A Model Context Protocol server that exposes this host as a Linux harness over public-trusted HTTPS. Designed for AI agents that have no Linux runtime of their own — they connect and get shell, Python, and filesystem tools that execute here.

Features

• 13 MCP tools: shell exec, Python exec, file read/write, directory ops, glob search, health check, opencode run/ultrawork
• Basic Auth or Bearer Token authentication
• Public HTTPS via ngrok (no certificate management needed)
• One-command install with interactive wizard (lhm install)
• Systemd service with auto-restart
• CLI manager (lhm) for status, logs, config, diagnostics

Quick Start

Install via npm

npm install -g linux-harness-mcp

Interactive Setup

sudo lhm install

This walks you through bind address, port, authentication, and optional ngrok exposure.

Check Status

lhm status

Get Public Endpoint

lhm url
# https://your-domain.ngrok-free.dev/mcp

CLI Reference (lhm)

Command	Description
lhm install	Interactive setup wizard
lhm uninstall	Stop + remove service + ngrok cleanup
lhm status	Show service status + public URL
lhm restart	Restart the service
lhm logs	View harness logs (-f to follow)
lhm logs --ngrok	View ngrok tunnel logs
lhm url	Print public MCP endpoint
lhm config	Show configuration (secrets masked)
lhm config --edit	Open config in $EDITOR
lhm doctor	Run health checks (incl. ngrok)
lhm version	Print version

MCP Tools

Tool	Description
shell_exec	Run shell commands via /bin/bash -c
python_exec	Execute Python scripts with system python3
file_read	Read files (auto text/binary, base64)
file_write	Write text or base64 binary files
list_dir	List directory entries with metadata
make_dir	Create directories (recursive)
delete_path	Delete files or directories
move_path	Move/rename paths
stat_path	Get file metadata (type, size, mode, mtime)
glob_search	Glob pattern file search
health_check	Service health + host summary
opencode_run	Execute complex tasks via opencode CLI
opencode_ultrawork	Execute tasks with ultrawork mode

Client Configuration

Basic Auth (recommended)

{
  "mcpServers": {
    "linux-harness": {
      "url": "https://your-domain.ngrok-free.dev/mcp",
      "headers": {
        "Authorization": "Basic <base64(user:pass)>",
        "ngrok-skip-browser-warning": "any"
      }
    }
  }
}

Bearer Token

{
  "mcpServers": {
    "linux-harness": {
      "url": "http://127.0.0.1:8765/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Architecture

Agent (MCP client)
  |  HTTPS (TLS 1.2/1.3, Let's Encrypt via ngrok)
  v
ngrok :443 --> 127.0.0.1:8765  (uvicorn + FastMCP Streamable HTTP)
                   |
                   v
               shell / python3 / filesystem  (as root)

• Public ingress: ngrok tunnel to 127.0.0.1:8765
• MCP transport: Streamable HTTP, stateful sessions
• Auth: ASGI middleware (Basic Auth or Bearer Token)
• /health: unauthenticated health endpoint

Environment Variables

Variable	Default	Description
HARNESS_HOST	127.0.0.1	Bind address
HARNESS_PORT	8765	Bind port
HARNESS_AUTH_USER	—	Basic Auth username
HARNESS_AUTH_PASS	—	Basic Auth password
HARNESS_TOKEN	—	Bearer token (alternative to Basic Auth)
HARNESS_ALLOWED_ORIGINS	—	Comma-separated allowed origins

Development

# Install in editable mode
pip install -e .

# Run tests
pytest tests/ -q

# Build wheel
python -m build --wheel

License

MIT