VPS Guardian MCP

VPS Guardian is a secure Model Context Protocol server for AI agents that work with Linux VPSs. It replaces an unrestricted “run this command and paste the result” loop with named, structured and safety-checked operations.

An agent can inspect a workload, collect bounded diagnostics, preview the impact of a change, and request an exact confirmation for a mutation. The server never exposes a general-purpose shell tool.

Explore the project: capabilities · agent workflows · security model · tool catalogue · release notes

Quick start

VPS Guardian has two parts:

• The Python MCP server runs on the VPS.
• The small npm launcher runs on the computer where Codex, Claude, Cursor or another AI client is installed. It opens an SSH stdio connection and never uploads the private key.

What you need

• A Linux VPS reachable via SSH.
• An SSH key for that VPS.
• Python 3.10+ on the VPS and Node.js 16+ on the AI client's computer.
• A verified SSH host key. Password-based SSH is intentionally unsupported by the launcher.

Optional: local MCP access panel

The English-language panel runs on your computer, not on the VPS or this project's website. Its main screen manages agent permissions: pause/resume MCP calls, cap the safety mode, allow individual tools and set project roots. A collapsed server overview provides optional read-only monitoring. The npm package remains the MCP launcher; the panel comes with the Python package.

With uv installed on your computer:

uvx --from vps-guardian-mcp==0.32.1 vps-guardian-panel

Without uv, install in a local virtual environment. Windows PowerShell:

py -m venv .guardian-panel
.\.guardian-panel\Scripts\python.exe -m pip install vps-guardian-mcp==0.32.1
.\.guardian-panel\Scripts\python.exe -m src.local_panel

Linux/macOS:

python3 -m venv .guardian-panel
.guardian-panel/bin/pip install vps-guardian-mcp==0.32.1
.guardian-panel/bin/vps-guardian-panel

The browser opens automatically. Enter the VPS address, SSH user, port and path to your local key, not its contents. Leave the key field empty to use ssh-agent; load encrypted keys into the agent beforehand. Advanced settings accept the Guardian executable path on the VPS and an optional local known_hosts file. Access management requires Guardian 0.30.0+ on the VPS; Projects and Limits require 0.31.0+, Operations requires 0.32.0+, with the adjacent vps-guardian-access executable from the same installation. Older compatible installations can show monitoring only, with an upgrade warning. No server-side web service is installed.

To upgrade an existing pip installation on the VPS:

/opt/vps-guardian-mcp/.venv/bin/pip install --upgrade vps-guardian-mcp==0.32.1

Upgrade any other Guardian environments used by your agents, then reconnect all agents once so they start the policy-aware server. Subsequent permission changes affect new calls in those sessions without a restart. In-flight operations are not cancelled, and cached client tool lists may still show disabled tools; calls to those tools are rejected.

Use Apply permissions to save a shared per-SSH-user policy on the VPS at ~/.local/share/vps-guardian-access/policy.json. Connection settings stay in local RAM, but the access policy persists across panel/server restarts. Reload policy fetches the current server values; concurrent edits are rejected rather than overwriting another operator's changes. No policy means the existing launch settings remain in force. Invalid or unsafe stored policies fail closed and pause normal MCP access; get_safety_status remains available for recovery. Unsafe file ownership, permissions or symlinks require manual repair by the operator.

• Allow agent access: pause/resume normal MCP tool and resource entry points. The separate operator helper remains reachable over SSH so you can restore access.
• Maximum safety mode: the effective mode is the stricter of the agent's launch mode and this cap. Setting controlled cannot elevate a client launched as read-only. Confirmation tokens are the existing same-caller mechanism, not independent human approval.
• Allowed tools: allow all installed/future tools, or uncheck that option and choose an explicit allowlist. New tools are denied by default in an explicit allowlist. get_safety_status cannot be disabled. Read-only mode can still create bookkeeping records; use tool permissions when you also need to block those entry points.
• Project roots: inherit each process's VPS_GUARDIAN_PROJECT_ROOTS, or replace it with up to 16 absolute VPS directory paths, one per line. An empty custom list blocks project workspaces. Filesystem roots and symlink roots are rejected. This controls project tools, not the separate fixed configuration-file directory whitelist.

The operator helper is not registered as an ordinary agent tool. Tools and the three read resources enforce access restrictions on the server. Policies apply to upgraded Guardian processes under the same SSH user, not to individually authenticated agent identities. An agent with independent root SSH access, the same account's shell, or permission to change Guardian's code can bypass this MCP boundary. For stronger separation use a restricted dedicated OS account; do not treat the panel as a sandbox or independent approval service.

Projects and live Limits

The Access, Projects and Limits sections require the current Python package on your computer. Projects and Limits additionally require Guardian 0.31.0+ on the VPS. A 0.30.0 server can still manage Access, but cannot enforce these new limits. Upgrade every server environment used by your agents and reconnect once; changing saved limits afterwards does not require another restart.

In Projects, click Find projects for a bounded metadata scan inside the current roots (at most 1,000 entries, 100 directories, 50 projects and a cooperative two-second deadline). Select a project or enter an absolute VPS path and click Inspect metadata. The panel shows top-level file/directory metadata, OS readability and policy decisions for common project tools, without reading source, invoking Git or executing project code. Links and sensitive/hidden names are excluded. Missing projects can be outside the roots, lack recognized markers or exceed the scan budget. When roots are inherited, the helper's launch defaults may differ from an agent's environment; use explicit managed roots for a shared boundary.

Use as the only project root only prepares a draft in Access. Review and click Apply permissions to replace the current roots with that single project. Browsing alone never grants or changes agent access. Policy allowance is not a guarantee that an agent's launch mode, roots or OS permissions permit an operation.

In Limits, choose Auto, Small VPS, Standard or Custom, then Apply limits. Values persist in the same private operator directory as limits.json, separately from policy.json. Revision checks reject concurrent edits. Auto and Standard currently request the same normal budgets; both retain automatic host guards. Small VPS requests smaller reads/searches, one-file patches and no Test Capsules. Custom accepts only the displayed integer ranges; it cannot disable guards or exceed hard ceilings. Reload live limits fetches a fresh server snapshot; it asks before discarding a local draft.

The table distinguishes Requested values from Effective on VPS values. Orange effective values have been reduced by host protection. The applied settings, not an unsaved draft, determine effective limits. Available memory below 512 MiB or one logical CPU reduces several budgets; below 384 MiB capsules are disabled; below 256 MiB additional critical-load restrictions apply. These are cooperative per-operation budgets, not a global CPU/RAM quota or OS sandbox. They do not cancel already running work. Every upgraded process under the same SSH user reads shared settings for subsequent operations. Invalid/unsafe limits use conservative Small VPS defaults and show an error; unsafe ownership/permissions or links may need manual repair.