Skip to main content
Glama

Ops Hub

Self-hosted reverse-connection remote operations hub with MCP tools for AI agents.

Ops Hub lets you manage Windows and Linux machines that are behind NAT, firewalls, or have no SSH/WinRM access. The Agent only makes an outbound WebSocket connection to your hub; you do not need a public IP, inbound port, port forwarding, or a VPN on the target machine.

The hub exposes the managed machines as MCP (Model Context Protocol) tools, so AI agents (Claude, OpenAI-compatible agents, OpenCode, MCP gateways, etc.) can:

  • list clients and read host information

  • run commands and stream/poll output

  • upload and download files with chunking and SHA-256 verification

  • page through text files

  • tail logs with a cursor that survives reconnects and log rotation

  • search logs on the Agent side (grep-like, with context)

  • survive network drops and replay unfinished command output

This is not a remote desktop or GUI tool. Keep using RDP/VNC/Sunflower/ToDesk for GUI access. Ops Hub is for CLI, files, logs, and automation.


⚠️ Authorized Use Only / 合法使用声明

Read this before deploying.

Ops Hub can execute commands and transfer files on remote machines. That is a powerful capability and can be misused. It is intended only for:

  • IT administrators managing machines they own

  • managed service providers managing customer machines with explicit written authorization

  • lab, test, and internal automation environments

  • incident response and maintenance on systems you are responsible for

Do not use Ops Hub for:

  • unauthorized access to computers, accounts, or data

  • covert surveillance, stalking, harassment, or monitoring people without consent

  • deploying malware, ransomware, miners, or persistence mechanisms

  • bypassing security controls, license checks, or access restrictions

  • violating privacy laws, computer-misuse laws, contracts, or customer policies

  • any activity that is illegal in your jurisdiction

You are solely responsible for:

  • obtaining authorization from the system owner and the customer

  • complying with laws and regulations (e.g. computer fraud/abuse laws, GDPR, China PIPL, data protection and privacy rules)

  • customer contracts, data-processing agreements, and security policies

  • securing the hub, tokens, TLS certificates, audit logs, and downloaded data

The software is provided “AS IS”, without warranty of any kind. The author is not liable for misuse, data loss, service interruption, legal claims, or damages caused by this software. See LICENSE.

If you are not sure whether you are allowed to manage a machine, do not install the Agent.


Related MCP server: Remote Runtime

Keywords

MCP · Model Context Protocol · MCP server · MCP tools · AI agent · AI operations · AIOps · remote operations · remote administration · RMM · IT operations · DevOps · SRE · infrastructure management · self-hosted · WebSocket · reverse connection · NAT traversal · remote shell · command execution · file transfer · log tail · log viewer · Windows Server · Linux · Golang · Node.js · MCP gateway · MCPHub · Claude · OpenAI · automation

GitHub topics are configured on the repository page. The project is designed to be discoverable by people looking for self-hosted MCP remote operations, AI agent server management, and reverse-connection RMM.


Features

Hub (Node.js)

  • Agent WebSocket gateway with registration, per-agent tokens, heartbeat, and reconnect

  • Command jobs with on-disk spool, incremental output, byte offsets, timeout, cancel, and process-tree termination

  • Chunked file upload/download with SHA-256 and atomic writes; browser uploads above 8MB are split into 8MB parts with retry and resume

  • MCP server over Streamable HTTP (and legacy-compatible JSON-RPC behavior)

  • 25 MCP tools covering inventory, command execution, files, logs, search, tunnels, SOCKS5, and upgrades

  • Web admin UI: clients, terminal, files, jobs, audit

  • Client list grouped by customer name (config.json → name), with per-machine status inside each group

  • Rename clients (Hub display name) and view OS/IP/CPU/memory/disk info

  • File browser with parent-directory navigation, left-side upload/download, drag-and-drop upload, and download-only handling for archives/binaries (.gz, .zip, images, etc.)

  • Delete files or directories from the UI (with confirmation); protected system roots are refused by the Agent

  • MCP tool ops_agent_package generates a ready-to-install Windows/Linux package with the enrollment token embedded and returns a time-limited private URL

  • JSON state persistence + JSONL audit log

  • Dangerous-command approval policy

  • Client revocation list with a 封禁管理 UI to unban client IDs

  • Local TCP port forwarding (ops-agent tunnel) over the existing /agent WebSocket path; MySQL/HTTP/RDP become 127.0.0.1:<port>

  • Remote Agent upgrade from the Hub UI or ops_agent_upgrade (SHA-256 verified, automatic service restart)

  • No inbound connection to agents

Agent (Go, single binary)

  • Windows amd64 / 386, Linux amd64 / arm64 / 386

  • Native Windows service (no nssm/Node/Python dependency)

  • Linux systemd installer

  • Host info: OS, CPU, memory, disks, network, users, uptime

  • Command execution: cmd / PowerShell / bash / sh

  • stdout/stderr framing and replay after reconnect

  • File read/tail/search/list/stat/write

  • Upload/download with SHA-256

  • UTF-8 / GBK / GB18030 / UTF-16 detection

  • Log rotation/truncation and partial-line handling

  • allowedRoots path sandbox for file APIs

  • TLS 1.2+, custom CA, HTTP proxy support

  • Exponential backoff reconnect


Architecture

AI agent / OpenCode / Claude / MCP client
   │  MCP over HTTPS
   ▼
MCP gateway (MCPHub, etc.)  ── mcp.example.com
   │  MCP Streamable HTTP (private network)
   ▼
ops-hub  ── 127.0.0.1:7100
   ▲
   │  WSS 443, outbound only
   │
┌──┴──────────────┬─────────────────┬──────────────┐
│ Windows Agent   │ Linux Agent     │ Windows Agent│
│ customer A      │ customer B      │ lab machine  │
└─────────────────┴─────────────────┴──────────────┘

Physical path:

Agent  →  wss://ops.example.com/agent  →  edge nginx  →  127.0.0.1:7100
MCP gateway →  http://127.0.0.1:7100/mcp

The Agent never listens on an inbound port. The hub never dials the Agent. This is what makes NAT/firewall traversal possible without a VPN or port mapping.


Quick Start (local)

Requirements: Node.js >= 20.

git clone https://github.com/a2237837517/ops-hub.git
cd ops-hub
npm install
cp config.example.json config.local.json

Edit config.local.json and change all three tokens:

{
  "hub": {
    "host": "0.0.0.0",
    "port": 7100,
    "publicUrl": "wss://ops.example.com/agent"
  },
  "auth": {
    "enrollmentToken": "replace-with-a-random-enrollment-token",
    "mcpToken": "replace-with-a-random-mcp-token",
    "adminToken": "replace-with-a-random-admin-token"
  }
}

Start:

node index.js serve

Open http://127.0.0.1:7100 and log in with adminToken.

After login, click 下载客户端 in the top bar to download the Windows/Linux Agent package and a ready-to-edit config.json (the config includes the current enrollment token, so only share it with authorized machines).

If the download page says no packages are available, build them first:

./scripts/package-agent.sh

The script writes packages to dist/packages/ and copies them to public/downloads/ for the Hub UI.

Web terminal shortcuts

The admin UI terminal works like a shell prompt:

  • cd <path> changes the working directory for subsequent commands

  • Enter executes the current command

  • ↑ / ↓ browse command history (stored per client in the browser)

  • Ctrl+L clears the screen

  • Ctrl+C cancels the running job (when no text is selected)

  • help prints the built-in shortcut help

Click anywhere in the terminal panel to focus the prompt.

CLI:

node index.js clients
node index.js exec <clientId> "uname -a" --shell bash
node index.js doctor
node index.js token

Build the Agent

Requirements: Go 1.20 (the last Go release supporting Windows 7 / Server 2008 R2).

./scripts/build-agent.sh
./scripts/package-agent.sh

Outputs:

dist/agent/ops-agent-windows-amd64.exe
dist/agent/ops-agent-windows-386.exe
dist/agent/ops-agent-linux-amd64
dist/agent/ops-agent-linux-arm64
dist/agent/ops-agent-linux-386
dist/packages/*.zip
dist/packages/*.tar.gz

If Go is not installed, use the official Go 1.20 tarball or a golang:1.20 container. The build script uses GO_BIN or go from PATH.


Agent Installation

Windows / Windows Server

Supported: Windows Server 2008 R2 and later (amd64/386). Windows Server 2008 (non-R2) is outside Go 1.20's support range.

  1. Extract the zip.

  2. Copy config.example.json to config.json.

  3. Fill in server, enrollmentToken, name, tags, and allowedRoots.

  4. Right-click install.bat → Run as administrator.

If install.bat reports A system shutdown is in progress, the Windows Service Control Manager is refusing to create a service during shutdown/restart. Reboot and retry, or run run.bat for foreground mode (no service; keep the window open).

The Agent installs as the OpsHubAgent Windows service and writes logs to:

C:\ProgramData\OpsHubAgent\logs\agent.log

State (client ID + token):

C:\ProgramData\OpsHubAgent\agent-state.json

Do not delete agent-state.json unless you intend to re-enroll the client.

clientId is generated per machine (hostname + hash(MachineGuid|hostname)) and persisted in this file. If the file is copied to another machine (disk clone, VM template, manual copy), both machines would present the same clientId and the Hub would keep replacing one connection with the other.

New Agents store a machine key in the state file and detect this automatically. They also recover from a lost state file: the Hub reissues an agentToken when the same machine presents the enrollment token and a matching fingerprint.

For a full clone that keeps the same MachineGuid and SMBIOS UUID, reset the identity manually (this also generates a random suffix, so the clone no longer collides):

sc stop OpsHubAgent
ops-agent.exe reset-id --config "C:\path\to\config.json"
sc start OpsHubAgent

The Hub rejects a clientId reconnecting from a different machine (machine fingerprint mismatch) and writes an agent.id.conflict audit record instead of silently kicking the live session.

Uninstall:

Right-click uninstall.bat → Run as administrator

Linux

tar -xzf ops-agent-linux-amd64.tar.gz
cd ops-agent-linux-amd64
cp config.example.json config.json
vi config.json
sudo ./install-linux.sh

Service name: ops-hub-agent
Logs: /opt/ops-hub-agent/logs/agent.log

Uninstall:

sudo ./uninstall-linux.sh

Agent Config

{
  "server": "wss://ops.example.com/agent",
  "enrollmentToken": "replace-me",
  "agentToken": "",
  "clientId": "",
  "name": "customerA-app01",
  "tags": ["customer:A", "prod"],
  "spoolDir": "",
  "allowedRoots": ["C:\\", "D:\\"],
  "maxSpoolMB": 2048,
  "maxConcurrentJobs": 4,
  "maxTransferKBps": 0,
  "insecureSkipVerify": false,
  "caFile": "",
  "proxy": "",
  "heartbeatIntervalSec": 15
}
  • allowedRoots restricts file APIs. Empty means “allow all” — set it in production.

  • maxTransferKBps limits file transfer speed (0 = unlimited); use e.g. 4096 on busy desktops.

  • File transfers are chunked at 256KB with per-chunk ACKs; the Agent log set is capped at 100MB and Windows service recovery restarts a crashed Agent.

  • proxy supports http://user:pass@proxy:8080; HTTP_PROXY/HTTPS_PROXY are also honored.

  • agentToken is issued by the hub on first registration and stored in agent-state.json.

  • insecureSkipVerify is for testing only.


Port Forwarding

The Agent already has an outbound WebSocket under /agent. The tunnel reuses that nginx location, so no nginx change, no new port, no new certificate:

wss://<hub>/agent/tunnel

Run the same ops-agent binary on your own computer:

Enable it in config.local.json first (disabled by default):

{
  "tunnel": {
    "enabled": true,
    "token": "<random tunnel token>",
    "allowedCidrs": ["127.0.0.0/8", "10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"],
    "allowedPorts": [],
    "maxStreamsPerTunnel": 16,
    "idleTimeoutSec": 1800
  }
}

Then run the same ops-agent binary on your own computer:

ops-agent.exe tunnel \
  --server wss://mcp.example.com/agent/tunnel \
  --token <tunnelToken> \
  --client <clientId> \
  --forward 13306=127.0.0.1:3306 \
  --forward 18080=192.168.1.30:80

Then connect locally:

Navicat   -> 127.0.0.1:13306
Browser   -> http://127.0.0.1:18080
mstsc     -> 127.0.0.1:13389

The target is dialed by the Agent, so it can be 127.0.0.1 (the Agent machine) or any TCP address the Agent can reach. Targets are restricted to private CIDRs by default (tunnel.allowedCidrs); public targets require an explicit allowlist. UDP is not supported.

The admin UI has a 端口转发 dialog that generates the command and lists active tunnels. MCP tools: ops_tunnel_command, ops_tunnel_list, ops_tunnel_close.


SOCKS5 Proxy (server-side)

The Hub can expose a SOCKS5 endpoint that routes through any online Agent. The managed machines do nothing; they already hold the outbound WebSocket.

Enable it in the admin UI (SOCKS5) or with ops_socks_enable. The Hub returns:

host:     118.31.73.50
port:     1080
username: <clientId>
password: <socks5 token>

Clash / browser:

proxies:
  - name: ops-185
    type: socks5
    server: 118.31.73.50
    port: 1080
    username: DESKTOP-FCUE0HS-336ac8d717
    password: "<token>"
    udp: false
  • Username selects the target Agent (clientId or registered name)

  • Password is socks5.token, separate from the tunnel token

  • Targets are restricted by tunnel.allowedCidrs / tunnel.allowedPorts

  • TCP only (udp: false); idle timeout and per-client stream limits apply

  • The listener is configured by socks5.host/port; publish the port and open it in the cloud security group (ideally only to your egress IP)

  • Plain SOCKS5 has no TLS; use it over VPN/SSH, or keep the source IP allowlist tight

  • Settings are persisted to data/settings.json and survive Hub restarts

MCP tools: ops_socks_enable, ops_socks_disable, ops_socks_status.

Local SOCKS5 (no new port)

If you do not want to open a public port, run the tunnel client on the machine that needs the proxy. It reuses the existing 443 WebSocket:

ops-agent.exe tunnel \
  --server wss://mcp.example.com/agent/tunnel \
  --token <tunnelToken> \
  --client <clientId> \
  --socks5 1080

Clash:

proxies:
  - name: ops-local
    type: socks5
    server: 127.0.0.1
    port: 1080
    udp: false
  • No security-group change, no new public port, TLS end to end

  • One local port per --client; run 1080/1081/... for multiple Agents

  • Or add --socks5-user-select: the SOCKS5 username selects the target clientId, so one local listener reaches every Agent. The password is the tunnel token by default, or --socks5-pass <password>

  • Optional local auth: --socks5-user ops --socks5-pass <password>

  • Targets are still restricted by tunnel.allowedCidrs / tunnel.allowedPorts


Remote Upgrade

The Hub serves raw Agent binaries and manifest.json under /downloads/. Click 升级 in the client header (or call ops_agent_upgrade) and the Agent:

  1. downloads the binary from the Hub's own host (URL host is validated)

  2. verifies its SHA-256 against the manifest

  3. writes <exe>.new and starts a detached updater

  4. the updater stops the service, replaces the binary (keeps .bak), and starts it again

The Agent reconnects with the new version, which is shown in the client meta line. Upgrade requires the Agent to be online and on 0.1.17 or newer (older builds do not understand agent.upgrade; the Hub returns a clear error and you install once manually). A failed download or checksum leaves the running version untouched.


MCP Gateway Registration

Register the hub as a Streamable HTTP MCP server in your gateway (MCPHub, etc.):

{
  "ops-hub": {
    "type": "streamable-http",
    "url": "http://127.0.0.1:7100/mcp",
    "headers": {
      "Authorization": "Bearer <HUB_MCP_TOKEN>"
    },
    "protocolNegotiation": "legacy",
    "enableKeepAlive": true,
    "keepAliveInterval": 30000
  }
}

If the gateway runs in a container and cannot reach the host loopback, use the host's private IP or http://172.17.0.1:7100/mcp, or put both containers on the same Docker network.

MCP clients then connect to the gateway (for example https://mcp.example.com/mcp?key=<gateway-api-key>), not directly to the hub's mcpToken.

In MCPHub mode the admin UI can be mounted at https://mcp.example.com/ops/ using deploy/nginx/mcp-ops-ui-location.conf; it still requires adminToken to log in.

Optional per-user audit: declare an upstream credential slot so every gateway user binds their own hub token:

"credentialTemplate": [
  { "target": "headers", "name": "Authorization", "label": "Ops Hub Token" }
]

MCP Tools

Tool

Purpose

ops_list_clients

List clients; filter by tag/status/query

ops_client_info

OS, CPU, memory, disks, network, users, uptime, agent version

ops_client_stats

Live CPU/memory/disk/load snapshot

ops_exec

Execute a command; waits 15s by default, returns job_id for long tasks

ops_exec_output

Read incremental output by byte offset

ops_exec_cancel

Terminate a job (process tree)

ops_list_jobs

List jobs

ops_upload

Upload a hub-local file to a client

ops_download

Download a client file to the hub

ops_write_file

Write text (UTF-8/GBK/GB18030/UTF-16LE)

ops_read_file

Page through a text file by byte offset

ops_tail_file

Tail a log with a reconnect-safe cursor

ops_search_file

Agent-side grep with context and regex

ops_list_dir

List a directory (glob/recursive)

ops_stat_file

Size/mtime/mode/SHA-256

ops_delete

Delete a file or directory (recursive=true for dirs; protected system paths refused)

ops_agent_package

Build preconfigured Agent installers with config.json embedded; defaults to all Windows/Linux architectures and returns 24h private URLs

ops_access_info

Return admin URL, token-login URL, admin/enrollment tokens, download page and endpoints

Output is intentionally bounded: ops_exec returns at most 64KB by default and stores the full log under data/jobs/. Continue with ops_exec_output and next_offset.

Log/file content is treated as untrusted data. Tool descriptions warn the model not to execute instructions found in logs.


Security Model

This project is C2-shaped by design: an agent that accepts commands and transfers files. Treat it as security-sensitive infrastructure.

Minimum production checklist:

  • Written authorization for every managed machine

  • TLS with a valid certificate; never insecureSkipVerify in production

  • Per-agent tokens; revoke deleted clients

  • adminToken, mcpToken, and enrollmentToken are different random values

  • MCP endpoint and admin UI on a private network / VPN / SSO

  • Only /agent exposed publicly

  • Dangerous commands require explicit approval

  • Audit logs enabled and retained

  • allowedRoots restricted on the Agent

  • Agent service runs with the least privilege that still works

  • EDR/antivirus exclusion approved by the customer

  • Data retention/cleanup for data/jobs and data/downloads

See docs/security.md for the full checklist and incident response guidance.


Deployment

Docker:

cp config.example.json config.local.json
docker compose -f deploy/docker-compose.yml up -d --build
curl http://127.0.0.1:7100/health

Reverse proxy:

  • Use deploy/nginx/ops.example.com.conf as a starting point.

  • Public: only wss://ops.example.com/agent.

  • Private: /mcp, /api, and the admin UI.

  • Increase proxy_read_timeout for long-lived WebSockets.

  • Increase client_max_body_size if uploading large files through the UI.

See docs/deploy.md for the mode index, or read docs/deploy-mcphub.md (only MCPHub public) and docs/deploy-standalone.md (own domain).


Project Layout

ops-hub/
├── index.js                 # CLI: serve / clients / exec / doctor / token
├── config.example.json      # Hub config template
├── src/
│   ├── config/              # config load/validate
│   ├── hub/                 # WebSocket gateway, jobs, file transfer, HTTP/UI
│   ├── mcp/                 # MCP tool definitions
│   ├── protocol.js          # message types, job states, cursor
│   ├── store.js             # JSON state + JSONL audit
│   └── commands/            # CLI commands
├── public/                  # admin UI
├── agent/                   # Go agent (Windows/Linux)
├── scripts/                 # build/package/install
├── deploy/                  # Dockerfile, compose, nginx example
├── docs/                    # protocol, deploy, security, runbook
└── tests/                   # Node tests + fake agent e2e

Testing

npm test
npm run check

cd agent
go test ./...

Covered:

  • config merge and validation

  • state persistence and audit

  • cursor and dangerous-command detection

  • hub + simulated agent end-to-end command execution

  • MCP authentication and tool listing

  • Agent encoding (UTF-8/GBK), file read/tail/search, path sandbox


Resource behavior

  • Agent logs: 10MB per file, 9 rotated backups, 100MB total.

  • Hub logs: same 10MB × 9 rotation (100MB total); Docker logs are separately capped at 50MB × 3.

  • Job output is separate from logs: capped by maxOutputBytesPerJob (default 50MB) and pruned by age/count.

  • File transfer is chunked at 256KB with a per-chunk ACK; the whole file is never loaded into memory.

  • maxTransferKBps (Hub and Agent) can cap transfer bandwidth; 0 means unlimited. Set e.g. 4096 on busy desktops.

  • Windows installs configure SCM recovery (sc failure ... restart); Linux systemd uses Restart=always. A crashed Agent is restarted, but a running transfer is not automatically throttled or cancelled.

  • Large files can still saturate the client's disk/network; use the bandwidth cap or schedule transfers off-hours.

Limitations

  • No GUI/desktop control, screenshots, or remote desktop. Use RDP/VNC/Sunflower/ToDesk.

  • No interactive PTY. Commands that require password prompts or interactive input may hang.

  • File transfer retries the whole transfer after a disconnect; command jobs support resume.

  • Single hub instance is designed for hundreds to a few thousand clients. Larger deployments need sharding/Redis.

  • Windows support is cross-compiled; test on your exact Windows Server version and antivirus before rollout.

  • Windows Server 2008 R2 is end-of-life; prefer a supported OS.


Sponsor / 赞赏码

如果这个项目对你有帮助,可以请作者喝杯咖啡。金额随意,不影响任何功能。

赞赏码

赞赏码仅用于自愿支持作者,不构成商业授权、服务承诺或技术支持合同。

Author

jijiawei

License

Non-Commercial Source-Available License 1.0 — see LICENSE.

You may use, copy, modify, and distribute this software for non-commercial purposes only. Commercial use is prohibited without prior written permission from the author. This is a source-available license, not an OSI-approved open-source license, because it restricts commercial use.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI coding agents and MCP clients to securely execute shell commands, manage files, and access remote devices or SSH hosts through centralized authentication, routing, and auditing.
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Connects MCP-compatible AI clients to an explicitly authorized Windows, macOS, or Linux computer for controlled Machine, Browser, and Desktop execution, including files, shell commands, native apps, and local browser sessions. Also offers a separate hosted Cloud Browser for browser tasks that should run outside the user's own workstation.
      7 npm
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI clients to reach tools running on any machine or existing MCP server, even behind NAT, using only outbound connections with no open ports, tunnels, or third-party services, while keeping oversized responses out of the model's context and enforcing per-token access policies.
      8 npm
      AGPL 3.0