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.

## 📚 Related Documentation

- Command Line (vpvm)
- App Shortcuts
- Web Dashboard
- Control Center

## 📬 Support

- Email: support@makeprog.com
- Mac App Store