VPS Guardian

Read Git working-tree changes and diff statistics without modifying the project.

Return a compact timeline of Guardian actions and important journal events.

Evaluate active resource watches once and return current threshold alerts.

Show the active low-resource profile and limits VPS-Guardian applies on this host.

Return the active safety mode, confirmation policy, TTL, and audit destination.

Retrieve a complete system health snapshot of the Linux VPS. Returns a JSON string containing: - CPU: overall percentage, per-core breakdown, core counts, 1/5/15m load averages. - RAM & Swap: total, used, available, percentage. - Disk: root partition usage, read/write I/O counters. - Network: sent/received bytes, packets, and error counts. - Uptime: boot timestamp and human-readable duration (e.g. '12d 4h 32m 10s').

Retrieve the top resource-consuming processes running on the VPS. Args: sort_by: Metric to rank processes by ('cpu' or 'memory'). Default: 'cpu'. limit: Number of top processes to return (1 to 50, default: 10). Returns: JSON string listing process PID, name, user, CPU %, RAM %, RSS memory, and command summary.

Inspect the status and active filtering rules of the UFW firewall. Returns: JSON string containing UFW active state, default incoming/outgoing policies, and all active firewall rules.

Map websites, reverse proxies, Compose projects, containers, ports, and databases. The map is read-only and excludes configuration content, environment values, and credentials. Use it before diagnosing an application whose location on the VPS is unknown.

Verify one website end to end: public HTTPS response, local Nginx host, and certificate. Returns a single diagnosis identifying whether an issue is public availability, virtual-host configuration, or the matching TLS certificate.

Return concise health, resource, container, and matching SSL state for one workload.

Leave a concise handoff note so another agent can continue without rediscovery.

Return Docker Compose service topology, images, ports, dependencies, and healthchecks.

Deep inspection of container networks, volume mounts, restart policy, healthcheck, and masked env vars. Args: container_name: Name or short/full ID of the target container. Returns: JSON string detailing full container architecture and runtime state.

Inspect an approved project: stack markers, Git branch/commit, and dirty state.

List active shared agent sessions; expired sessions are marked automatically.

Discover conventional Docker Compose files in an authorized directory tree.

Discover all scheduled cron jobs on the Linux system. Audits /etc/crontab, /etc/cron.d/, /etc/cron.* periodic scripts, and user crontabs. Returns: JSON string containing scheduled jobs with user, schedule expression, human-readable timing explanation, and command.

Inspect file and directory structures within authorized administrative paths. Permitted directories: /etc/nginx/, /etc/mysql/, /etc/postgresql/, /etc/docker/, /etc/caddy/, /var/www/ Args: dir_path: Path to the directory to inspect. max_depth: Exploration depth (1 to 3, default: 1). Returns: JSON string with item list (names, types, sizes, modification dates).

List Docker containers with their status, image, port bindings, volumes, and health. Args: all: Set to True to list all containers (running and stopped), False for running only. Returns: JSON string with list of containers, port forwards, and mount mappings.

List active maintenance windows, or include closed and expired history.

List command-free agent runbooks built from existing guarded MCP tools.

List active agent runbooks, with optional completed history.

List stored VPS state snapshots without exposing their collected content.

Audit active and pending systemd timers via 'systemctl list-timers'. Returns: JSON string with timer unit names, next execution time, countdown, and target services.

Inspect active Nginx virtual hosts, listening ports, SSL, and reverse proxy targets. Returns: JSON string with parsed virtual hosts from /etc/nginx/sites-enabled/ and conf.d/.

Reserve a workload briefly so concurrent agents do not make conflicting changes.

Open an expiring workload watch. Use get_event_watch later to retrieve new events.

Validate and preview an Nginx config or Caddyfile deployment. The candidate is staged outside the live path, syntax-checked, and shown as a bounded unified diff. No live configuration is modified. Nginx configs under /etc/nginx and Caddyfiles under /etc/caddy are supported. Args: file_path: Target config path under /etc/nginx or /etc/caddy. content: Complete proposed UTF-8 configuration (at most 200,000 bytes). service_name: Optional matching service name (nginx or caddy). Returns: JSON plan with validation output, diff, expiry, and a confirmation token in controlled mode.

Create an evidence-backed repair plan without changing the VPS.

Show secret-redacted diffs and request one confirmation for a ChangeSet.

Show secret-redacted source diff and obtain one confirmation token for a patch.

Read one non-binary project file without following symlinks; redact common secrets.

Safely fetch and optionally filter recent log lines for a service or Docker container. Args: service_name: Target unit (e.g. 'nginx', 'systemd:cron', 'docker:my_container'). lines_count: Number of recent lines to retrieve (default: 50, maximum: 1000). grep_filter: Optional case-insensitive keyword to filter lines (e.g. 'ERROR', '403', 'denied'). Returns: JSON string containing the extracted log lines and matching statistics.

Save one bounded, secret-redacted finding or decision to an active agent session.

Run only fixed safe checks: Git whitespace validation or bounded Python syntax parsing.

Bounded literal code search with ignored dependency folders and redacted output.

Set a safe web-readable mode (0644 or 0640) for a static file under /var/www. The content is untouched; arbitrary chmod modes and paths outside /var/www are rejected. Controlled mode requires a confirmation token.

Stage one Nginx configuration change; content is not applied yet.

Stage one source-file replacement in an active project patch without applying it.

Create an expiring, secret-safe shared task context for agents working on this VPS.

Open a bounded agent runbook; it never runs commands or bypasses confirmation.

Benchmark outbound network connectivity and latency using direct Python sockets. Measures DNS resolution latency, TCP handshake time, and TLS handshake latency without shell ping. Args: target_host: Destination hostname or IP address (e.g. 'api.github.com' or '8.8.8.8'). port: Destination port (1-65535, default 443). timeout_seconds: Network socket timeout (0.5 to 30.0 seconds, default 5.0). Returns: JSON string with stage latency breakdown, resolved IP addresses, and TLS session details.

Test Nginx configuration for syntax errors ('nginx -t') without reloading. Returns: JSON string indicating syntax validity, exit code, and syntax error messages.

Record the outcome of one runbook step after its separate guarded tool call.

Verify a Guardian tar.gz archive without extracting it. Only regular archives within the isolated Guardian backup directory are accepted. Very large member counts return a bounded partial result.

Safely read the content of an authorized configuration or web file. Permitted directories: /etc/nginx/, /etc/mysql/, /etc/postgresql/, /etc/docker/, /etc/caddy/, /var/www/ Strictly protected against path traversal attacks. Args: file_path: Canonical path or relative path to the configuration file. max_bytes: Maximum bytes to return (default: 50,000, capped at 200,000). Returns: JSON string with file content, size, and modification timestamp.

Create an expiring CPU, memory, swap, or disk threshold watch. The watch has no background worker. Call get_resource_alerts to evaluate it on demand, which is safe for small VPS instances.

Atomically write or update a configuration file within authorized directories. Creates an automatic timestamped backup (.bak.<timestamp>) before overwriting. Permitted directories: /etc/nginx/, /etc/mysql/, /etc/postgresql/, /etc/docker/, /etc/caddy/, /var/www/ Args: file_path: Path to the target configuration file. content: Text content to write. backup: Create a backup file before writing (default: True). confirmation_token: Single-use token returned by the preceding plan call. Returns: JSON string indicating write status and backup location.