Skip to content

# Web Dashboard

The Web Dashboard lets you monitor and control your virtual machines from any browser on your local network — no VirtualProg app window required. Access it from another Mac, iPad, or any device connected to the same network.

## 🔧 Enabling the Dashboard

Before using the Web Dashboard, enable the CLI Server in VirtualProg:

1. Open VirtualProg → Settings → CLI
2. Enable CLI Server
3. Enable External Access to allow connections from other devices on your network
4. Note your token — you will need it to log in

## 🌐 Accessing the Dashboard

Open a browser and navigate to:

    http://<your-mac-ip>:<port>/dashboard

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:

    http://127.0.0.1:<port>/dashboard

## 🖥️ 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. Enter the token from Settings → CLI 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.

## 🌙 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.

### 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

1. Open Dashboard Settings (gear icon) and go to Security.
2. Click Set up 2FA.
3. Scan the QR code with your authenticator app (Google Authenticator, Authy, 1Password, etc.).
4. Enter the 6-digit code from your app and click Verify & Enable.

#### 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.

## 📚 Related

- Virtual Machines
- Snapshots
- Templates
- Networks
- Image Catalog
- Logs
- Web CLI Terminal
- Web Console
- Connect
- Command Line Interface (vpvm)