Skip to content

🔗 URL Scheme Automation

Control VirtualProg from anywhere on your Mac using custom URLs.

The virtualprog:// URL scheme lets you start, stop, and control virtual machines directly from tools like Raycast, Alfred, Shortcuts, shell scripts, or any app that can open a URL — without using the terminal or the GUI.

🚀 Overview

With the VirtualProg URL scheme you can:

  • Start, stop, pause, resume, restart, and suspend virtual machines with a single URL
  • Integrate with Raycast and Alfred for instant keyboard-driven VM control
  • Trigger VM actions from macOS Shortcuts, Focus Modes, and automations
  • Script VM control from any language or tool that can call open

📋 URL Reference

General Format

virtualprog://<action>?name=<VMName>
URL Action
virtualprog://control/start?name=Ubuntu Start the VM (also resumes a paused or suspended VM)
virtualprog://control/stop?name=Ubuntu Force stop the VM
virtualprog://control/shutdown?name=Ubuntu Gracefully shut down the VM
virtualprog://control/pause?name=Ubuntu Pause the VM
virtualprog://control/resume?name=Ubuntu Resume a paused or suspended VM
virtualprog://control/restart?name=Ubuntu Restart the VM
virtualprog://control/suspend?name=Ubuntu Suspend the VM to disk

Note: <VMName> must exactly match the name shown in the VirtualProg Control Center. Names are case-sensitive.

🖥️ Using from the Terminal

Use macOS's built-in open command to trigger any URL:

# Start a VM
open "virtualprog://control/start?name=Ubuntu"

# Graceful shutdown
open "virtualprog://control/shutdown?name=Ubuntu"

# Suspend to disk
open "virtualprog://control/suspend?name=Ubuntu"

⚡ Raycast Integration

  1. Open Raycast → Extensions → Script Commands (or use a Quicklink).

  2. Create a Quicklink with the URL, for example:

    virtualprog://control/start?name=Ubuntu

  3. Assign a keyword (e.g., start-ubuntu) and an optional hotkey.

  4. Trigger it from the Raycast search bar or with your hotkey.

You can create one Quicklink per VM action for a full keyboard-driven VM control panel.

🔍 Alfred Integration

  1. Open Alfred Preferences → Features → Web Search (or create a Workflow).

  2. For a simple one-action trigger, create a Custom Web Search or a Workflow with a URL action:

    virtualprog://control/start?name=Ubuntu

  3. For dynamic VM names, use an Alfred Workflow with a Script Filter or Open URL action and pass the VM name as a query argument.

🔧 macOS Shortcuts

  1. Open the Shortcuts app.
  2. Create a new shortcut and add the Open URLs action.

  3. Enter your URL, for example:

    virtualprog://control/start?name=Ubuntu

  4. Run it from Spotlight, Siri, the menu bar, or a Focus Mode trigger.

Example automation: Automatically start your development VM when your "Work" Focus Mode activates.

📝 Shell Scripting

#!/bin/bash
# Start all development VMs

VMS=("Ubuntu" "Debian" "Fedora")

for vm in "${VMS[@]}"; do
    echo "Starting $vm..."
    open "virtualprog://control/start?name=$vm"
    sleep 2
done

echo "All development VMs started."

⚠️ Error Handling

If the VM name does not match any virtual machine in VirtualProg, an alert dialog will appear:

Virtual Machine 'Ubuntu' does not exist

Check that the name matches exactly (including capitalisation) with the name shown in the Control Center.

🔄 App Launch Behaviour

  • App already running: The URL is handled immediately. No new window is opened.
  • App not running: VirtualProg launches automatically, then performs the requested action once ready.

💡 Tips

  • VM names with spaces: Encode spaces as %20 in URLs, or wrap the argument in quotes when using the open command: 
    open "virtualprog://control/start?name=My%20Ubuntu%20VM"
  • start and resume are equivalent: The start action automatically resumes a paused or suspended VM — no need to use a different URL.
  • Combine with the CLI: For more advanced scripting and remote control, see the Command Line documentation.

📬 Support