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 <zip-or-url> 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.

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:<name> 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. Prefix-matched against
# this list; 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]