SentinelX MCP

sentinelx-cloud-core

Operate your Linux, macOS, and Windows servers from Claude.ai or ChatGPT — safely. SentinelX gives your LLM an allowlisted, auditable shell: it can only run commands you've explicitly permitted, filesystem access is gated by a per-path allowlist, and every action is recorded. No inbound ports — just a single outbound WebSocket.

The security model is the point. Handing an LLM unrestricted shell on a server you care about is the thing SentinelX is designed to avoid: the allowlist is the real trust boundary, so the agent can't run — or invent — anything you didn't allow. This is the agent you install on the host; structured file edits and service management come with it.

SentinelX in ChatGPT — it reads the allowlist, runs only what's permitted ( df -h , /proc/meminfo ), and reports back.

Install

Most people start with the one-liner — it auto-detects Linux or macOS:

curl -fsSL https://get.sentinelx.app | bash

Windows (PowerShell — needs Python 3.12+ and git on PATH):

*Service install* — runs as LocalSystem at boot; needs an elevated PowerShell:

iwr -useb https://get.sentinelx.app/install.ps1 -OutFile "$env:TEMP\sx.ps1"

powershell -ExecutionPolicy Bypass -File "$env:TEMP\sx.ps1"

*Per-user install* — no admin; runs as you at logon (locked-down machines):

iwr -useb https://get.sentinelx.app/install.ps1 -OutFile "$env:TEMP\sx.ps1"

powershell -ExecutionPolicy Bypass -File "$env:TEMP\sx.ps1" -User

The installer clones this repo into a virtualenv, registers the agent as a service (systemd / launchd / Windows service), and walks you through enrollment. On networks that block PyPI, add -Bundle for an offline install from the wheel bundle on the latest release; the agent uses the OS trust store (truststore) so a TLS-inspecting proxy's CA is accepted. Full options — per-user vs service, offline bundle, all flags, uninstall — live in sentinelx-cloud-installer.

SentinelX is also listed in the ChatGPT app directory — ChatGPT users can connect it in one click, no custom MCP URL required.

This repo is also the agent's source — read on if you want to audit or contribute.

Troubleshooting

Common errors and their fixes, each under the exact message you'll see, are on sentinelx.app/troubleshooting: sign-in failing behind antivirus MCP scanning, hosts that keep reconnecting, -32603 errors during a hub update, ChatGPT safety blocks, Manus setup and agents that stay offline. If none of them matches, open an issue here.

Architecture

                                        Internet

│ ┌────────────────┐ │ ┌─────────────────┐ │ Claude.ai or │ MCP over HTTPS │ WebSocket │ Your host │ │ ChatGPT │ ◄───────────────────► │ ◄──────────────► │ │ │ │ (OAuth via Google) │ │ ┌───────────┐ │ └────────────────┘ │ │ │ agent │ │ ┌───────────────────────┐ │ │ (this) │ │ │ mcp.sentinelx.app │ │ └─────┬─────┘ │ │ (SentinelX hub — │ │ │ │ │ closed source) │ │ shell, edit, │ └───────────────────────┘ │ service mgmt │ └─────────────────┘

The agent is the box on the right. It opens one outbound WebSocket to the hub at install time (after enrollment) and stays connected. No inbound ports, no port-forwarding, no reverse tunnel.

What runs where

Supported platforms: any modern Linux distribution with systemd (tested on Ubuntu 22.04 / 24.04 and Debian 12), macOS with launchd (Intel and Apple Silicon), and Windows — as a service (WinSW, admin) or as a no-admin per-user Scheduled Task (-User); see *Install on Windows* below. The one-line installer auto-detects Linux and macOS; Windows uses a PowerShell installer. The agent also runs unmodified inside WSL2.

Tools exposed

The agent exposes its host's operations as MCP tools to your LLM via the hub:

Progressive introspection (agent operation contract)

The agent-side help and capabilities operations also support optional narrow-response selectors. A Hub/MCP profile may expose these fields through whatever model-facing tool shape it uses; the selectors are backend-operation semantics and do not depend on full vs compact tool names.

• help({"topic":"index"}) — small topic + paged playbook index.
• help({"topic":"security"}) — one broad help section.
• help({"path":"security_model.permission_errors"}) — one exact leaf from the existing help tree.
• help({"playbook":"update_sentinelx_code"}) — one playbook only; optional path, offset, and limit can select/page a subfield such as steps.
• capabilities({"detail":"summary"}) — host/operation/limit metadata and policy counts without command/service/location/playbook bodies.

Progressive help/playbook responses normalize explicit full-profile sentinel_* references to op: canonical operation hints so the same guidance can be routed through compact or full presentation without teaching a playbook two sets of MCP tool names.

For compatibility, empty help({}) and capabilities({}) requests retain the legacy full responses. A Hub that wants compact-first behavior should map its compact help/capabilities branches to the narrow selectors rather than changing the agent's legacy empty-payload semantics.

sentinel_read, sentinel_list, and sentinel_search are read-only filesystem primitives. sentinel_edit and the mutating primitives (sentinel_move, sentinel_copy, sentinel_delete, sentinel_chmod, sentinel_chown) write. All of them give the LLM structured access to the filesystem without shelling out to cat/ls/mv/rm through exec, and all of them are gated by the same path allowlist (file_ops in the config, see below), not the command allowlist. Each path in that allowlist declares an access level: r (read-only ops) or rw (read-only ops plus the writing ops). Destructive operations that overwrite or remove an existing target make a timestamped backup first.

The hub additionally exposes a handful of hub-side integrations (Cloudflare DNS, Resend email, Telegram) as MCP tools your LLM can use alongside the agent's tools — those live on the hub, not in this repo. See the integrations table on sentinelx.app.

Config (/etc/sentinelx/config.yaml)

A starter config is generated at install time. Editable. Reloaded when the service restarts. Schema:

# Commands the agent can execute via the `exec` op (exec_mode: allowlist, the

default). Whole-word match, and every command in a chained line must be

covered. Empty/missing = nothing allowed (deny by default).

allowed_commands:

• uptime
• df -h
• free
• systemctl
• sudo systemctl
• journalctl

See config.example.yaml for the full starter list (file inspection,

networking, containers, git, etc.) plus opt-in categories

(Cloudflare tunnels, WireGuard, Android tooling, firewalling, SSH).

Service units the agent is allowed to control via service / restart.

Each unit explicitly lists which actions are permitted.

services: nginx: actions: [status, start, stop, restart, reload] docker: actions: [status, restart]

The agent itself, so the LLM can reload policy after editing the

config. Restarting re-reads /etc/sentinelx/config.yaml. Conservative

actions only — no start/stop, since the agent can't remotely start

itself once stopped.

sentinelx-cloud-core: actions: [status, restart, is-active, is-enabled]

postgresql:

actions: [status, start, stop, restart, reload]

Optional: named playbooks the LLM can read or execute. Two shapes are

supported and can coexist in the same map:

#

1) Diagnostic playbook — a fixed sequence of allowlisted commands the

agent can run in order. Useful for "give me a quick health snapshot"

type prompts where you want one named entry-point.

#

2) Procedure playbook — a structured recipe for the LLM to follow,

expressed in description / when / steps / requires / notes

fields. Pure documentation: the agent does NOT execute the steps,

the LLM reads them via capabilities and then calls the regular

tools (sentinel_exec, sentinel_edit, sentinel_service) on its own.

#

See config.example.yaml for the full reference.

playbooks:

Diagnostic playbook (shape 1)

health: description: "Show system health summary" commands:

• "uptime"
• "df -h /"
• "free -m"

Procedure playbook (shape 2) — guides the LLM through extending the

allowlist itself. Useful so users can ask "let me run htop here" and

the LLM knows the exact procedure (edit config, restart service,

verify with capabilities).

add_allowed_command: description: "How to add a new command to this host's allowlist" when: "User asks to allow a new command on this host" steps:

• "Read /etc/sentinelx/config.yaml with sentinel_exec"
• "Insert under allowed_com