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

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

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

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:

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

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

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.