OpsPilot

English · 简体中文

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).

Related MCP server: SSH Vault MCP

Features

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

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

Start the local UI / broker

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).

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:

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

Or via npm:

{
  "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):

.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)

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

Dev commands

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.