Web Dashboard
The Web Dashboard lets you monitor and control your virtual machines from any browser — on your local network or over the internet — with no VirtualProg app window required. Access it from another Mac, iPad, or any device that can reach your Mac.
🔧 Enabling the Dashboard
Before using the Web Dashboard, enable the CLI Server in VirtualProg:
- Open VirtualProg → Settings → CLI
- Enable CLI Server
- Enable External Access to allow connections from other devices — on your network, or from the internet (see Accessing from Outside Your Network)
- Note your token — you will need it to log in
🌐 Accessing the Dashboard
Open a browser and navigate to:
To find your Mac's IP address, go to Settings → CLI — the full address is shown there.
If you are accessing from the same Mac:
Accessing from Outside Your Network
The dashboard works anywhere your browser can reach the Mac. Use the address your Mac is reachable at instead of its local IP:
| Option | How it works |
|---|---|
| Direct connection | Forward the CLI Server port (default 49152) on your router to the Mac and enable HTTPS with an SSL/TLS certificate, then open https://<your-address>:<port>/dashboard. |
| VPN | Use a VPN such as Tailscale or WireGuard and open the dashboard on the Mac's VPN address. Nothing is exposed to the public internet. |
| Reverse proxy or tunnel | Put the Mac behind your existing homelab setup — Nginx, Traefik, or a Cloudflare Tunnel — and open that address, normally over HTTPS. |
Security: When the Mac is reachable from the internet, always use HTTPS, prefer a scoped token over the master token, and turn on two-factor authentication. A VPN or tunnel is the safest choice. HTTPS also unlocks the H.265 / H.264 video options in Remote Control.
🖥️ Server Mode
When controlling VMs remotely from the dashboard, macOS alert dialogs on the host Mac can pause the browser session until dismissed. Server Mode prevents this by suppressing informational and error alerts — instead logging them silently — so the dashboard stays responsive at all times. macOS notifications are also suppressed while Server Mode is active.
To enable Server Mode:
- Tools menu → Server Mode, or
- Status bar icon → Server Mode
A checkmark indicates it is active. Click again to disable it.
When Server Mode is enabled, the Control Center (main application window) is automatically hidden so the host Mac presents no visible UI. When you disable Server Mode, the Control Center window is restored to the screen automatically.
Note: Confirmation dialogs (such as those asking you to confirm stopping or restarting a VM) are always shown, regardless of this setting.
🔐 Login
On first visit, you are prompted for your token. Two token types are accepted:
- Master token — full access to all VMs and settings. Found in VirtualProg → Settings → CLI.
- Scoped token — limited access to specific VMs and operations. Created in the dashboard's Tokens tab using the master token. See Access Tokens for details.
Enter your token and click Sign In. The token is saved in your browser — you will not need to enter it again unless you sign out or clear your browser data.
When signed in with a scoped token, an amber pill in the header shows the access level (Operator or Admin). Tabs and actions outside the token's permissions are hidden automatically.
⚙️ Dashboard Settings
Dashboard Settings is divided into Dashboard and Mac Server tabs. Dashboard preferences such as auto-refresh and remote-screen quality remain local to the browser. The Mac Server tab shows server-wide settings, including Screenshot Background, and applies changes when you click Save. Only the master token can edit these values; scoped tokens see them read-only.
Screenshot Background controls screenshot capture for VMs, snapshots, and templates on the Mac. Server Mode changes require confirmation because they hide the Mac Control Center and suppress informational and error alerts. Window Border adds a tag-colored border to the streamed live screen whenever it is visible on the Mac VM window. If a setting is unavailable, update the Mac server to a version that supports remote settings.
🌙 Dark & Light Theme
The dashboard follows your device's appearance setting by default. Use the 🌙 / ☀️ button in the header to switch between dark and light themes manually. Your preference is saved and remembered across sessions.
🟢 Connection Status
A small dot in the header shows the state of the connection to VirtualProg at a glance:
| Dot | Meaning |
|---|---|
| Green | Last refresh succeeded |
| Amber (pulsing) | Refresh in progress |
| Red | Last refresh failed — check that VirtualProg is running |
⌨️ Keyboard Shortcuts
Press ? anywhere in the dashboard to open the built-in keyboard shortcut reference panel, or click the keyboard icon in the header toolbar.
| Shortcut | Action |
|---|---|
? |
Open keyboard shortcuts reference panel |
Ctrl+/ |
Focus the VM search box |
R |
Refresh immediately |
Ctrl+`` ` |
Toggle the Web CLI Terminal panel |
Esc |
Close any open panel or dialog |
⚙️ Settings
Click the Settings (gear) icon in the top-right toolbar to open the Dashboard Settings dialog. Changes take effect when you click Save.
Mac Server Features
Favorites, Tag Colors, Groups, Server Mode, and Window Border show the current values from the connected Mac and apply to everyone using that server. Changes are sent when you click Save. Only the master token can edit them; scoped tokens see read-only values. Disabling Favorites, Tag Colors, or Groups hides its controls but keeps existing data.
Enabling Server Mode hides the Mac Control Center and suppresses informational and error alerts; changing it requires confirmation. Window Border adds the VM's tag-colored border to the streamed live screen whenever it is visible on the Mac VM window. If a value is unavailable, update the Mac server to a version that supports remote settings.
Auto-Refresh
Controls how often the dashboard automatically polls VirtualProg for updated VM state.
| Option | Interval |
|---|---|
| Manual only | No automatic refresh — use the Refresh button |
| 5s – 5m | Refresh every 5 seconds, 10 s, 15 s, 30 s, 1 min, 2 min, or 5 min |
Remote Screen
Default display settings applied every time you open a VM's remote control screen. You can always adjust these live in the remote control toolbar without affecting the saved default.
| Field | Description | Default |
|---|---|---|
| FPS | How many times per second the screen is refreshed. Auto (recommended) adjusts FPS automatically based on connection quality — it starts conservatively and ramps up as conditions allow, then drops back when congestion is detected. Fixed options: 1, 3, 5, 8, 10, 15, 20, 25, 30 fps. | 10 fps |
| Quality | Controls how the screen is streamed to your browser. See the options below. | Medium |
Quality Options
| Option | Best for |
|---|---|
| H265 ⭐ | The best overall experience — the smoothest, most responsive display with the lowest bandwidth. Recommended for most users. Automatically enables Auto FPS when selected. |
| H264 | Excellent quality and low bandwidth. A great choice if your browser does not support H265. Automatically enables Auto FPS when selected. |
| Best (PNG) | Pixel-perfect image quality. Uses more bandwidth — best for inspecting fine detail. |
| High | High image quality with reasonable bandwidth. Good for local network use. |
| Medium | Balanced quality and bandwidth. Suitable for most situations. |
| Low | Reduced image quality. Useful on slow or limited connections. |
Tip: For the best experience, use H265 with Auto FPS. H265 delivers a smoother, more responsive display than H264 at the same or lower bandwidth. The viewer adapts the frame rate to your connection automatically — no manual tuning needed. On a fast local network it ramps up to 25 fps; on a slower connection it settles at a lower rate.
If H265 is not available in your browser, H264 is an excellent alternative. If neither codec is available, Medium quality at 10 fps is a good fallback.
Accent Color
Changes the highlight colour used for buttons, active states, and focus rings throughout the dashboard. Nine colours are available: Indigo, Purple, Blue, Cyan, Teal, Green, Orange, Rose, Slate. Your choice is saved per browser.
🔐 Two-Factor Authentication (2FA)
The Security section lets you add an extra layer of protection to your dashboard login. When enabled, signing in requires both your token and a 6-digit code from an authenticator app. After a successful login, you stay signed in for 7 days without being asked again.
Setting up 2FA
- Open Dashboard Settings (gear icon) and go to Security.
- Click Set up 2FA.
- Scan the QR code with your authenticator app (Google Authenticator, Authy, 1Password, etc.).
- Enter the 6-digit code from your app and click Verify & Enable.
- Save the 8 recovery codes that appear — store them somewhere safe (password manager, printed copy). Each code can only be used once.
Recovery Codes
Recovery codes let you sign in if you lose access to your authenticator app. At the login screen, click Use a recovery code instead and enter one of your saved codes. Using a code burns it — it cannot be used again.
After signing in with a recovery code, a banner appears at the top of the dashboard prompting you to take one of two actions:
- Re-enroll authenticator — scan a new QR code with your new phone or app. This replaces the old secret and generates 8 fresh recovery codes.
- Regenerate codes — keep the same authenticator app but issue a new set of 8 recovery codes. Requires your current 6-digit TOTP code to confirm.
The remaining recovery code count is shown in Dashboard Settings → Security. When 2 or fewer codes remain, the count is highlighted in amber as a reminder to regenerate.
Disabling 2FA
In Dashboard Settings → Security, click Disable and confirm. You will be signed out of the dashboard immediately.
If you are signed in with a scoped token, 2FA applies to that token only. See Access Tokens for details.
🔒 Sign Out
Click Sign out in the top-right corner to end your session. Your token is cleared from the browser.