Ops Hub
Enables remote operations on Linux machines through an outbound agent, including command execution, file upload/download, file listing and paging, log tailing/search, and host information retrieval.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 groupRename 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_packagegenerates a ready-to-install Windows/Linux package with the enrollment token embedded and returns a time-limited private URLJSON 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/agentWebSocket path; MySQL/HTTP/RDP become127.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
allowedRootspath sandbox for file APIsTLS 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/mcpThe 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.jsonEdit 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 serveOpen 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.shThe 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 commandsEnterexecutes the current command↑/↓browse command history (stored per client in the browser)Ctrl+Lclears the screenCtrl+Ccancels the running job (when no text is selected)helpprints 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 tokenBuild the Agent
Requirements: Go 1.20 (the last Go release supporting Windows 7 / Server 2008 R2).
./scripts/build-agent.sh
./scripts/package-agent.shOutputs:
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.gzIf 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.
Extract the zip.
Copy
config.example.jsontoconfig.json.Fill in
server,enrollmentToken,name,tags, andallowedRoots.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.logState (client ID + token):
C:\ProgramData\OpsHubAgent\agent-state.jsonDo 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 OpsHubAgentThe 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 administratorLinux
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.shService name: ops-hub-agent
Logs: /opt/ops-hub-agent/logs/agent.log
Uninstall:
sudo ./uninstall-linux.shAgent 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
}allowedRootsrestricts file APIs. Empty means “allow all” — set it in production.maxTransferKBpslimits file transfer speed (0 = unlimited); use e.g.4096on 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.
proxysupportshttp://user:pass@proxy:8080;HTTP_PROXY/HTTPS_PROXYare also honored.agentTokenis issued by the hub on first registration and stored inagent-state.json.insecureSkipVerifyis 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/tunnelRun 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:80Then connect locally:
Navicat -> 127.0.0.1:13306
Browser -> http://127.0.0.1:18080
mstsc -> 127.0.0.1:13389The 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: falseUsername selects the target Agent (
clientIdor registered name)Password is
socks5.token, separate from the tunnel tokenTargets are restricted by
tunnel.allowedCidrs/tunnel.allowedPortsTCP only (
udp: false); idle timeout and per-client stream limits applyThe 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.jsonand 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 1080Clash:
proxies:
- name: ops-local
type: socks5
server: 127.0.0.1
port: 1080
udp: falseNo security-group change, no new public port, TLS end to end
One local port per
--client; run 1080/1081/... for multiple AgentsOr add
--socks5-user-select: the SOCKS5 username selects the targetclientId, 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:
downloads the binary from the Hub's own host (URL host is validated)
verifies its SHA-256 against the manifest
writes
<exe>.newand starts a detached updaterthe 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 |
| List clients; filter by tag/status/query |
| OS, CPU, memory, disks, network, users, uptime, agent version |
| Live CPU/memory/disk/load snapshot |
| Execute a command; waits 15s by default, returns |
| Read incremental output by byte offset |
| Terminate a job (process tree) |
| List jobs |
| Upload a hub-local file to a client |
| Download a client file to the hub |
| Write text (UTF-8/GBK/GB18030/UTF-16LE) |
| Page through a text file by byte offset |
| Tail a log with a reconnect-safe cursor |
| Agent-side grep with context and regex |
| List a directory (glob/recursive) |
| Size/mtime/mode/SHA-256 |
| Delete a file or directory ( |
| Build preconfigured Agent installers with |
| 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
insecureSkipVerifyin productionPer-agent tokens; revoke deleted clients
adminToken,mcpToken, andenrollmentTokenare different random valuesMCP endpoint and admin UI on a private network / VPN / SSO
Only
/agentexposed publiclyDangerous commands require explicit approval
Audit logs enabled and retained
allowedRootsrestricted on the AgentAgent service runs with the least privilege that still works
EDR/antivirus exclusion approved by the customer
Data retention/cleanup for
data/jobsanddata/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/healthReverse 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_timeoutfor long-lived WebSockets.Increase
client_max_body_sizeif 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 e2eTesting
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;0means unlimited. Set e.g.4096on busy desktops.Windows installs configure SCM recovery (
sc failure ... restart); Linux systemd usesRestart=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
GitHub: @a2237837517
Repository: https://github.com/a2237837517/ops-hub
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…
This server cannot be deployed
Maintenance
Related MCP Connectors
MCP gateway and cloud hosting for MCP servers, agents and apps like RAG, managed from your agent.
Secure and manage MCP servers through the Speakeasy AI Control Plane from your agent.
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Private networking for AI agents: networks, nodes, commands, files, services via hosted MCP.
Related MCP Servers
- AlicenseCqualityBmaintenanceEnables AI agents to manage system updates, application installations, and remote host orchestration through MCP tools.813MIT
- AlicenseNot gradedqualityAmaintenanceEnables 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

noxgild-cliofficial
AlicenseNot gradedqualityCmaintenanceConnects 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 npmApache 2.0- AlicenseNot gradedqualityCmaintenanceEnables 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 npmAGPL 3.0