# linux-harness-mcp

A [Model Context Protocol](https://modelcontextprotocol.io/) 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

```bash
npm install -g linux-harness-mcp
```

### Interactive Setup

```bash
sudo lhm install
```

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

### Check Status

```bash
lhm status
```

### Get Public Endpoint

```bash
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)

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

### Bearer Token

```json
{
  "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

```bash
# Install in editable mode
pip install -e .

# Run tests
pytest tests/ -q

# Build wheel
python -m build --wheel
```

## License

MIT