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.
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
| Component | Where | What it does |
|---|
sentinelx-cloud-core (this repo) | /opt/sentinelx-cloud-core on your host | Receives MCP tool calls from the hub, executes them locally, returns output |
| Hub | mcp.sentinelx.app (operated by Pensa) | Auth, multi-host routing, MCP transport |
| Config | /etc/sentinelx/config.yaml | Allowlist: which commands, services, and paths the agent will accept |
| Identity | /etc/sentinelx/identity.json | The agent's enrollment JWT, used to authenticate the WebSocket handshake |
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.
The agent exposes its host's operations as MCP tools to your LLM via the hub:
| Tool | What it does |
|---|
sentinel_exec | Run an allowlisted shell command |
sentinel_script_run | Run a one-off bash or python3 script |
sentinel_edit | Structured file edit (replace, regex, replace-block, write, append, prepend) |
sentinel_edit_upload_* | Three-step upload for large file edits |
sentinel_move | Move/rename a file or directory |
sentinel_copy | Copy a file or directory |
sentinel_delete | Delete a file or directory |
sentinel_chmod | Change file permissions |
sentinel_chown | Change file owner/group |
sentinel_service | systemctl start/stop/restart/reload/status |
sentinel_restart | Shortcut for sentinel_service with action=restart |
sentinel_upload_file | Single-shot file upload to the host |
sentinel_upload_* | Three-step chunked upload for large files |
sentinel_read | Read a file's contents, with optional line-range slicing |
sentinel_list | Structured directory listing (name, type, size, mtime) |
sentinel_search | Recursive content search with regex and glob filters |
sentinel_local_api | Allowlisted actions on host-local structured endpoints: a unix socket (HTTP or JSON-RPC) or a declared binary over stdio (JSON-RPC, MCP servers included). Only when the host declares local_apis |
sentinel_capabilities | Host policy/capabilities; optional bounded summary projection |
sentinel_help | Rich orientation/help; optional topic/path/single-playbook projections |
sentinel_state | Internal agent state, for debugging |
sentinel_ping | Cheap connectivity check |
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:
allowed_commands:
- uptime
- df -h
- free
- systemctl
- sudo systemctl
- journalctl
services:
nginx:
actions: [status, start, stop, restart, reload]
docker:
actions: [status, restart]
sentinelx-cloud-core:
actions: [status, restart, is-active, is-enabled]
playbooks:
health:
description: "Show system health summary"
commands:
- "uptime"
- "df -h /"
- "free -m"
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_commands with sentinel_edit (sudo, validator_preset=yaml)"
- "Restart the agent: sentinel_service restart sentinelx-cloud-core"
- "Verify with sentinel_capabilities"
log:
path: /var/log/sentinelx/core.log
level: INFO
security:
trusted_fetch_hosts:
- drop.pensa.ar
- get.sentinelx.app
file_url_timeout_seconds: 15
file_ops:
paths:
- path: /etc/nginx
access: r
- path: /var/log
access: r
- path: /home/youruser/projects
access: rw
max_read_bytes: 65536
max_list_entries: 1000
max_search_results: 200
In the default exec_mode: allowlist, the agent runs a command line only if
every command in it matches allowed_commands as a whole word (agent
0.23.22+). So allowing git lets the LLM run git status and
git log -1 && git status; allowing ls covers ls -lah /var/log but not
lsof. Read-only filters after a pipe (| grep x, | head) and shell
grammar (for, if, ...) need no entry. An entry like bash or python3
allows anything, since bash -lc '...' is one argument. exec_mode: strict
also refuses newlines, substitutions and redirections; exec_mode: unrestricted runs anything under the agent's identity, for trusted
development hosts. Out of the box the config is restrictive โ see
config.example.yaml for the full starter list and the three modes.
There are two independent allowlists, and they protect different ops:
allowed_commands gates exec (per exec_mode). It does NOT gate
script_run, which runs any script as the agent's user; turn it off with
disabled_ops: [script_run] where that matters.
file_ops.paths gates every filesystem primitive โ the read-only ones
(sentinel_read, sentinel_list, sentinel_search) on any r or rw
entry, and the writing ones (sentinel_edit, sentinel_move,
sentinel_copy, sentinel_delete, sentinel_chmod, sentinel_chown)
only on rw entries.
So a directory listed as r lets the LLM inspect it but not modify it; a
directory listed as rw allows both. A directory in neither is invisible to
all the filesystem primitives (the LLM would have to fall back to exec,
which is governed by allowed_commands instead).
One deliberate exception: sentinel_edit with sudo=true is not gated
by file_ops.paths. The trust boundary for sudo'd edits is the operator's
sudoers policy, not the path allowlist โ this is what lets the
add_allowed_command playbook edit the root-owned config. Path
canonicalization still runs (no traversal/symlink bypass); only the
rw-membership check is waived for the sudo path. This carve-out and its
residual risk are documented in THREAT_MODEL.md
(ยง4.2.1).
Security model
- No inbound ports. Only an outbound WebSocket to the hub.
- JWT-bound identity.
identity.json is signed by the hub at enrollment.
Compromising one host doesn't grant access to others.
- Allowlist-gated. Anything not in
config.yaml returns
command_not_allowed. The agent won't synthesize new commands. This is
the actual security boundary โ not the unix user, not sudo policy.
When a command is rejected, the agent returns a classified error
(multi-line input, bash keyword, shell pipeline, or simply not in the
allowlist) that points the LLM at the right tool instead of guessing.
- Path-allowlisted filesystem primitives. Every structured filesystem
op only touches paths under
file_ops.paths. Read-only ops (sentinel_read,
sentinel_list, sentinel_search) work on r and rw entries; writing
ops (sentinel_edit, sentinel_move, sentinel_copy, sentinel_delete,
sentinel_chmod, sentinel_chown) require an rw entry. Paths are
canonicalized โ symlinks resolved, .. collapsed โ before the prefix
check, so neither path traversal nor a symlink pointing outside the
allowlist can escape it. Empty allowlist = the primitives are disabled.
Writing ops that overwrite or delete an existing target back it up first
(timestamped .bak). sudo=true on sentinel_edit does not lift the rw
check: it only changes which user performs a write the policy already
allows โ see THREAT_MODEL.md ยง4.2.1.
- Unprivileged user with passwordless sudo. The agent runs as
sentinelx,
not as root. By default the installer grants sentinelx passwordless sudo
so it can manage services and edit system files โ but it can still only
invoke what's in your allowlist. To run with no sudo, set
SENTINELX_SKIP_SUDO=1 during install.
- SSRF-defended
file_url. When upload_file is called with a URL, the
agent validates the hostname against security.trusted_fetch_hosts,
resolves it to an IP, and rejects loopback / RFC1918 / link-local addresses
(so an attacker can't pivot to cloud metadata services or LAN-internal
hosts). Redirects are disabled, https only, default timeout 15s. The
allowlist defaults to empty โ file_url is effectively disabled until
the operator opts into specific hosts.
- Path-traversal-defended uploads. All
target_path arguments are
resolved under upload_base via safe_path_under(); .. and absolute
paths that escape are rejected up front.
- No telemetry. The agent reports nothing about your host or activity to
anyone but the hub you're explicitly connected to.
For a deeper view, see THREAT_MODEL.md (assets,
adversaries, trust boundaries, per-threat mitigations) and
SECURITY.md (vulnerability reporting + disclosure
policy).
Local development
git clone https://github.com/pensados/sentinelx-cloud-core
cd sentinelx-cloud-core
python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
pytest
To run the agent against a hub other than the production one (the hub's base URL,
http(s):// or ws(s)://; the agent adds /agent/connect itself):
SENTINELX_HUB_URL=https://localhost:8000 \
python3 -m sentinelx_core --identity-file /tmp/dev-identity.json
Vendored: pensa-safe-edit
The actual file mutation for sentinel_edit is done by a small stdlib-only
module vendored at src/sentinelx_core/vendored/pensa_safe_edit.py. The handler
runs it as a helper process (python -m sentinelx_core.vendored.pensa_safe_edit,
under sudo for sudo=true) from an argv list, never through a shell, so there
is no shell=True anywhere in the edit path. The process boundary is deliberate:
a cancelled or timed-out edit kills the helper and any validator it started
(through run_process, like every child the agent starts), so it can't still
commit afterwards; an edit running in a thread inside the agent couldn't be
stopped that way. It does its work via temp files +
atomic rename, makes a timestamped backup before mutating, preserves file
metadata, and can run an optional pre-commit validator
(json/yaml/toml/python/sh/nginx/systemd presets) โ if validation fails the
original file is left untouched. It is still also registered as a pip
console-script entry point for standalone/manual use.
License
Apache License 2.0 โ see LICENSE.
What exec_mode: allowlist promises
The allowlist is a guardrail for a well-meaning assistant: it keeps it from running
what the host owner didn't authorize, by mistake or by a wrong turn of reasoning. Every
command in a chain must be allowed, substitutions are checked, and the variables that
decide which program runs (PATH, HOME and every other exported variable) are read-only
while the chain runs.
It is not a sandbox against someone deliberately trying to escape. A full shell has
more ways to change its own behaviour than any checker can model. If the assistant, or
whoever can steer it, must not be able to affect the host at all, give it a host of its
own: a disposable VM (the compute tools create and enroll one; with grant_sudo it gets
root on a machine with nothing on it you care about).