# OpsPilot

[English](README.md) · [简体中文](README.zh-CN.md)

Local AI ops broker: SSH secrets stay on your machine, agents call intent-level MCP tools (no keys in chat), and dangerous writes wait for approval in a loopback Web UI.

## What it is

Day-to-day Linux ops via AI assistants often either:

1. Puts SSH private keys/passwords into model context or tool arguments, or  
2. Exposes raw remote shell with weak “approve in chat” gates  

**OpsPilot** is a single-user, loopback control plane on your machine:

- Secrets stay in the local broker process / `~/.opspilot/` — **never** in MCP args or model-visible output  
- **MCP** exposes structured intent tools (`host_alias` + typed params), not arbitrary `ssh`/`bash`  
- Read-only work can run automatically; writes/restarts wait for the local Web UI **approval queue**  
- A project **Agent Skill** teaches assistants the same boundaries and hard-stops if the MCP broker is missing (no fallback to raw SSH)  

Listens on `127.0.0.1` only (default port `4317`).

## Features

| Area | Notes |
| --- | --- |
| Host catalog | Alias, SSH address, services, log roots, credentials |
| Read-only ops | Inspect, list log dirs, truncated logs, allowlisted files, Docker read-only |
| Approval-gated writes | Service restart, file write/upload |
| Per-host auto-approve reads | Optional; writes still require approval |
| Approvals + audit | UI queue + local `audit.jsonl` |
| EN / 中文 UI | Top-bar language toggle |

**Out of v1 scope:** arbitrary remote shell/PTY, Docker writes, local Docker socket, Kubernetes, cloud APIs, bastion multi-hop, multi-host orchestration.

## Requirements

- Node.js **≥ 20**
- Network reachability to target Linux hosts  
- Cursor (or another MCP + Skills client) optional for agents  

## Install

```bash
git clone <your-repo-url> OpsPilot
cd OpsPilot
npm install
```

## Start the local UI / broker

```bash
npm start
```

Open <http://127.0.0.1:4317>

1. Create a host under **Hosts** (alias, address, user, port)  
2. Paste an SSH **password or private key** and save (the field clears after save on purpose; status shows attached)  
3. Prefer registering log **directories** (e.g. `/opt/prod-log/`); agents list files first, then fetch a concrete file  
4. For test hosts, optionally enable **Auto-approve read-only ops**  
5. Use **Test connection**  
6. Approve/reject gated ops under **Approvals**  

Data directory default: `~/.opspilot/` (`catalog.json`, `secrets.json`, `audit.jsonl`).

| Env var | Default | Meaning |
| --- | --- | --- |
| `OPSPILOT_PORT` | `4317` | Web UI / HTTP MCP bridge port |
| `OPSPILOT_DATA_DIR` | `~/.opspilot` | Data directory |
| `OPSPILOT_APPROVAL_TIMEOUT_MS` | `600000` (10m) | Approval timeout |

Recommended: start **`npm start` first**, then connect Cursor MCP. If the MCP child finds the port in use, it **proxies** tool calls to the primary broker so the Approvals UI stays in sync.

## Configure Cursor MCP

Add OpsPilot to user or project `mcp.json` (use your absolute path):

**Project** `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "opspilot": {
      "command": "npx",
      "args": ["tsx", "/ABSOLUTE/PATH/TO/OpsPilot/src/index.ts"],
      "env": {
        "OPSPILOT_PORT": "4317"
      }
    }
  }
}
```

Or via npm:

```json
{
  "mcpServers": {
    "opspilot": {
      "command": "npm",
      "args": ["start", "--prefix", "/ABSOLUTE/PATH/TO/OpsPilot"],
      "env": {
        "OPSPILOT_PORT": "4317"
      }
    }
  }
}
```

Then:

1. Restart MCP / Reload Window in Cursor  
2. Confirm tools such as `opspilot_list_hosts` and `opspilot_fetch_logs` appear  
3. Keep one primary `npm start` UI; let MCP proxy rather than running conflicting brokers  

Example prompt: “Use OpsPilot to show the latest log on `user-test`.”

## Configure the Agent Skill

Shipped in two places (same content):

```text
.cursor/skills/opspilot/   # Cursor project skill (used when this repo is the workspace)
skills/opspilot/           # Standalone copy for reuse / distribution
  SKILL.md
  BOUNDARIES.md
```

Open this repo as the Cursor workspace so the **opspilot** skill under `.cursor/skills/` can be selected. To install elsewhere, copy `skills/opspilot/` (or `.cursor/skills/opspilot/`) into that project’s `.cursor/skills/opspilot/`.

Rules of thumb:

- Require a connected **OpsPilot MCP**; if absent, **stop** — do not fall back to generic SSH MCP or handwritten `ssh`  
- Logs: `opspilot_list_log_files` first, then `opspilot_fetch_logs` on a **file** path  
- Chat “approve” is **not** approval — use the local **Approvals** UI and `request_id`  

## MCP tools (illustrative)

| Tool | Purpose |
| --- | --- |
| `opspilot_list_hosts` / `opspilot_describe_host` | Catalog discovery |
| `opspilot_inspect_host` | Read-only inspect |
| `opspilot_list_log_files` | List a catalog log directory |
| `opspilot_fetch_logs` | Fetch a concrete log file (truncated) |
| `opspilot_restart_service` | Restart (needs approval) |
| `opspilot_read_file` / `write_file` / `upload_file` | Allowlisted paths |
| `opspilot_docker_ps` / `opspilot_docker_logs` | Remote Docker read-only |
| `opspilot_get_request` | Request / approval status |

Always trust the live `tools/list` schemas; never invent tool names.

## Dev commands

```bash
npm test
npm run typecheck
npm start
```

## Security notes

- Loopback only — do not expose port `4317` publicly  
- Never paste private keys/passwords into chat; save them only in the local UI  
- Approval timeout defaults to 10 minutes with no auto-retry  

## License

Private / unlicensed unless you add a license file.