VPS Guardian

Audit kernel logs for hardware failures, storage I/O errors, or application segfaults. Args: limit: Maximum number of error entries to retrieve (1 to 50, default 20). Returns: JSON string with categorized kernel errors, root causes, and critical issue counters.

Inspect kernel logs for Linux Out-Of-Memory (OOM) Killer invocations. Surfaces terminated processes, PIDs, and consumed RSS memory at time of termination. Args: limit: Maximum number of recent OOM events to return (1 to 50, default 10). Returns: JSON string with detected OOM incidents and diagnostic summary.

Check the operational status of a systemd service unit. Args: service_name: Name of the system service (e.g. 'nginx', 'mysql', 'postgresql', 'ufw', 'docker'). Returns: JSON string with active state ('active', 'inactive', 'failed'), enabled state, and recent status logs.

Audit SSL/TLS certificates configured on the host (Let's Encrypt / Certbot). Returns: JSON string listing domains, expiration dates, days remaining, and warning flags.

Audit system-wide and user limits: file descriptors, max PIDs, virtual memory, socket backlogs. Returns: JSON string comparing allocations to kernel limits and highlighting threshold warnings (>80%).

Audit available operating system package updates and pending security patches. Checks reboot requirements (/var/run/reboot-required), total upgradable packages, and security CVE patches. Cached for 5 minutes to minimize CPU and disk usage. Args: force_refresh: Set to True to bypass the 5-minute cache and query package managers directly. Returns: JSON string with update counts, security status, reboot flag, and recommended recovery action.

Lease one dependency-ready task to an active agent session.

Safely reclaim disk space by pruning dangling images, stopped containers, unused volumes, and networks. Args: prune_type: Category to prune ('containers', 'images', 'volumes', 'networks', 'all'). Default is 'all'. confirmation_token: Single-use token returned by the preceding plan call. Returns: JSON string detailing deleted items and total disk capacity reclaimed.

Close a checkpoint with a secret-redacted change outcome.

Close a session with an outcome; historical records remain secret-redacted.

Close a maintenance window with a secret-redacted outcome note.

Compare a checkpoint to current state and return a confirmation-gated rollback plan.

Compare two snapshots and rank configuration or infrastructure drift by risk. Flags new exposed ports, failed units, cron changes, Docker drift, and configuration-hash changes. Both snapshots must be from the same host.

Compare a saved workload baseline with the current workload state.

Token-confirmed Docker Compose up, restart, or stop for selected project services.

Create a dedicated, locked OS account. Only the operator helper calls this.

Capture a bounded pre-change system or workload observation; no changes are made.

Persist a bounded, read-only Agent Job. Checks: system_health, runtime_budget, workload_brief, event_delta, service_logs, service_status.

Add a bounded task to the shared agent queue; no server action is executed.

Create a compressed tar.gz archive of an authorized website or configuration directory. Archives are saved into an isolated backup repository (/var/backups/vps-guardian/). Permitted source locations: /var/www/, /etc/nginx/, /etc/mysql/, /etc/postgresql/, /etc/docker/, /etc/caddy/ Args: backup_type: Identifier label for the archive (e.g. 'site', 'config', 'data'). source_path: Target directory to archive. confirmation_token: Single-use token returned by the preceding plan call. Returns: JSON string with archive file path, size, file count, and duration.

Create an expiring maintenance window for agent coordination. A window records intent and timing; it never bypasses the active safety mode or grants permission for VPS changes.

Copy selected protected source files into a bounded Mission proposal; [] starts a new-files-only draft.

Save a privacy-preserving, read-only VPS state baseline. Records ports, failed units, cron/timers, Docker inventory, and optional configuration file hashes. It never stores config content or cron commands. Snapshot storage is configurable with VPS_GUARDIAN_SNAPSHOT_DIR.

Save a secret-free known-good workload baseline for later drift comparison.

Commit a validated configuration plan, reload its service, and auto-rollback on failure. Args: deployment_id: Short-lived identifier returned by plan_config_deployment. confirmation_token: Required only in controlled mode; bound to this plan. Returns: JSON outcome with atomic-write, reload, health-check, and rollback details.

Scan system process table for defunct/zombie processes and identify non-reaping parents. Returns: JSON string reporting detected zombies, parent PIDs, and remediation advice.

Return bounded direct-dependency/lockfile issues and runtime mismatch evidence; unchanged fingerprints suppress repeated reports.

Gather bounded read-only logs, OOM, kernel, and health evidence for a workload.

Find bounded Git/application projects in configured VPS project roots.

Safely execute lifecycle operations (start, stop, restart, pause, unpause) on a container. Args: container_name: Name or short/full ID of the target Docker container. action: Desired action ('start', 'stop', 'restart', 'pause', 'unpause'). timeout: Stop/restart timeout in seconds before forcible kill (default: 10). confirmation_token: Single-use token returned by the preceding plan call. Returns: JSON string detailing previous status, new status, and action outcome.

Execute a proposed restart through the existing safety-mode confirmation gate, then require verification.

Execute an emergency recovery operation from a strictly whitelisted list. Allowed actions: - 'restart_service': Restarts a systemd service (requires target=service_name, e.g. target='nginx'). - 'clean_docker_cache': Deep prune of unused containers, networks, images, and volumes. - 'clean_system_logs': Prunes journal logs older than 3 days and rotated archives in /var/log. - 'kill_process': Terminates a runaway process by PID (requires target=PID, e.g. target='12345'). - 'restart_nginx': Restarts Nginx web server (legacy alias for restart_service target='nginx'). - 'vacuum_systemd_journal': Tr…

Find Python symbol-use candidates, distinguishing import aliases from name-only matches; never executes code.

Find an application by domain, container, Compose service, port, or path fragment.

Record the agent's conclusion after all checks or recovery verification.

Complete or fail an owned task and retain a bounded, redacted result.

Generate one prioritized, read-only VPS incident report. Args: include_updates: Include operating-system patch and reboot status. include_security: Include SSH hardening assessment. include_network: Include listening ports; disabled by default to keep reports compact. Returns: JSON string with severity-ranked findings and the underlying diagnostic sections.

Get job progress and compact results; use after_revision to receive only new steps.

Read a session's objective, findings, handoff note, and expiry state.

Return recent redacted audit events for state-changing operations. Args: limit: Number of newest events to return (1-500, default 50).

List isolated Guardian backups with sizes and creation times, without reading contents.

Show what a prospective restart, stop, config deployment, or update may affect. This tool never executes the action and does not issue a confirmation token.

Discover running databases and verify responsiveness, latency, and socket states. Detects Redis, PostgreSQL, MySQL/MariaDB, and SQLite databases in application directories. Returns: JSON string with operational state, socket accessibility, and ping latency for each engine.

Safely read stdout/stderr logs from a specific Docker container. Args: container_name: Container name or container short/full ID. lines_count: Number of recent log lines to retrieve (default: 50, max: 1000). Returns: JSON string containing the container logs.

Retrieve live resource utilization metrics for all running Docker containers. Provides real-time CPU %, Memory %, Network I/O, and Block I/O (equivalent to `docker stats`). Returns: JSON string listing resource metrics per running container.

Retrieve events seen since an active event watch was opened; this does not push notifications.

Check Fail2ban status, active protection jails, and currently banned IP addresses. Returns: JSON string detailing active jails and banned IP addresses.

Find all degraded or failed systemd services across the entire system. Returns: JSON string with list of failed units ('systemctl --failed') and overall health indicator.

Return normalized UFW, firewalld, or nftables firewall state and rules.

Report whether this Guardian runs through SSH/stdio, systemd, or a container and how to reload it.

Recover a mission goal, linked IDs and next state; an unchanged revision returns a tiny status reply.

Discover all listening network ports (TCP and UDP) and identify bound processes. Returns: JSON string listing open ports, protocols (TCP/UDP), binding addresses (IPv4/IPv6), and process names/PIDs.

Read shared operation metadata, bounded timeline and outcome after reconnect; never executes or approves anything.

List available updates via APT, DNF, YUM, Pacman, or Zypper without changing state.

Detect package, firewall, service-manager, and Docker Compose backends on this host.

In-depth diagnostics for a specific PID: hierarchy, threads, memory, open files, sockets, I/O. Args: pid: The target process ID to inspect (positive integer). Returns: JSON string detailing process tree, memory breakdown, sockets, files, and sanitized env.

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

Read a bounded, secret-redacted Git diff for a project or one file.

Map bounded local Python import candidates; unresolved modules and partial scans are explicit.

Map Python classes and functions to line ranges without returning their bodies.

Bundle a Python definition, use-site fragments and test candidates; mask literals/comments and cap output.

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.

Return only server events after the supplied cursor, with a bounded response and next cursor.

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').

Inspect local Docker and resource prerequisites for isolated project checks.

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.

One compact, selectable workload report; request full detail only when needed.

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

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

Extend a task lease while its owning agent session is still working.

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.

Inspect Python venv/package metadata and a running systemd MainPID without executing project code.

List active pre-change checkpoints and optional completed history.

List persistent job summaries without returning step outputs.

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

List prioritized tasks and release expired leases on demand.

List this Mission worker's private operator assignments; no automatic model or production execution.

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.

Recover private workspace IDs and candidate hashes after reconnecting, without source output.

List shared persistent drafts/history and Agent Jobs; metadata only, no source or tokens. Paginate drafts/history with next_before.

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.

Prepare reviewed runtime/dependency metadata for a capsule image; this does not build, download or verify the image.

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 mod…

Plan an environment repair without installing packages, changing service units or restarting applications.

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.

Apply the exact capsule-tested candidate using existing preview, confirmation and backup rules.

Propose one systemd-service restart after job checks; this does not execute it.

Read a bounded candidate fragment and hashes; resume via next_byte_offset.

Read up to 200 candidate lines/24 KB with this file's hash only; never execute code or authorize stale apply.

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

Read later lines or bytes of a large project file within a per-call limit; returns a file hash and continuation.

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.

Return an owned task to the queue with a secret-redacted reason.

Report working/blocked/needs_review with optional submitted workspace and unverified Job ID; never approve or finish.

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.

Replace a private candidate using its current SHA-256; production remains unchanged.

Propose deleting a selected candidate with a current hash; operator apply retains a private baseline backup.

Edit inclusive candidate lines; end_line=start_line-1 inserts, including at EOF. No production write.

Propose creating a 0644 source file under an existing protected parent; independent operator apply required.

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

Stage only changed lines in a bounded project patch; preview and confirmation are still required.

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.

Freeze a proposal for independent operator review; this does not grant permission to apply.

Group repeated service log lines into a short report; return unchanged for a known fingerprint.

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.

Test staged code in one temporary, networkless, resource-limited Docker capsule; controlled mode requires confirmation.

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

Read service health after a job restart; never restart or roll back automatically.

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.