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:
- Open VirtualProg → Settings → CLI
- Enable CLI Server
- Enable External Access to allow connections from other devices on 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:
🔐 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.
🖥️ Virtual Machines
The Virtual Machines tab is the default view. It shows all your VMs as cards.
Summary Bar
At the top, four summary tiles show the total count of VMs in each state at a glance:
- Total — all VMs
- Running — currently active
- Stopped — powered off
- Paused / Suspended — frozen or saved to disk
Search, Filter & Sort
Above the VM grid, a toolbar lets you narrow down the list:
- Search — type any part of a VM name to filter cards instantly
- State pills — click All, Running, Stopped, or Paused to show only VMs in that state
- Sort — choose Name A–Z, Name Z–A, or By State
Filters and sorting are preserved during auto-refresh.
Grid and List View
Use the ⊞ / ≡ toggle buttons in the toolbar to switch between the default card grid and a compact table view. The table view shows all VMs in a single scrollable list with columns for name, distro, status, CPU/RAM, and uptime — useful when you have many VMs. Your preference is saved and remembered across sessions.
VM Cards
Each card shows the VM name, OS/distro, current state, CPU, and memory. Action buttons are shown directly on the card and update based on the VM state:
| State | Available Actions |
|---|---|
| Stopped | ▶ Start, 🗑 Delete |
| Running | ■ Shutdown, ⏻ Stop, ⏸ Pause, ↺ Restart, 💾 Suspend |
| Paused / Suspended | ▶ Resume |
Running VMs show ▶ Running for Xh Ym on the card so you can see at a glance how long a VM has been up.
Bulk Actions
You can act on multiple VMs at once:
- Hover a card to reveal its checkbox, then check the VMs you want to select. In list view, checkboxes are always visible.
- A bar slides up from the bottom showing how many VMs are selected, with Start, Shutdown, Stop, and Clear buttons.
- Actions are smart — Start only applies to stopped or suspended VMs; Shutdown and Stop only apply to running VMs.
VM Detail Panel
Click any VM card to open the detail panel on the right. It shows full configuration and hardware details, uptime statistics, and snapshot management.
From the detail panel you can also:
⚙️
| Action | Description |
|---|---|
| 📦 Create Template | Save a stopped VM as a reusable template |
| 🧬 Clone | Duplicate a stopped VM under a new name |
| ✏️ Rename | Rename the VM — enter the new name in the dialog |
| ⚙️ Configure | Configure CPU and memory of the VM |
| 🖥 Connect | Remote Control the VM from your browser |
Snapshots
The detail panel includes a Snapshots section. You can:
- View all existing snapshots
- Create a new snapshot by entering a name and clicking + Create
- Restore or delete any snapshot
Console Ports
If a VM has one or more serial ports configured in Console mode, a Console Ports section appears in the detail panel. Each port shows an Open Web Console button that launches the browser-based terminal for that port.
To configure a serial port as a console port, open the VM configuration in the VirtualProg app, go to Serial Ports, and set the mode to Console.
Auto-Refresh
The dashboard refreshes automatically in the background. Use the ↺ Refresh button in the header to refresh immediately.
To change the refresh interval, click the ⚙ icon in the header and choose from 5 seconds up to 5 minutes, or select Manual only to disable auto-refresh entirely. Your preference is saved across sessions.
📦 Templates
The Templates tab shows all your saved VM templates as cards.
Each card shows the template name, OS/distro, CPU, memory, and creation date.
Use the search bar to filter templates by name, or the sort dropdown to order by Name A–Z, Name Z–A, Newest first, or Oldest first. Use the ⊞ / ≡ toggle to switch between card grid and list view.
Click a template card to open the detail panel, which shows the full template configuration including source VM, OS, and hardware specs.
Template Actions
| Action | Description |
|---|---|
| + Create VM | Create a new virtual machine from this template |
| 🗑 Delete | Permanently delete the template |
🌐 Networks
The Networks tab shows all custom networks configured in VirtualProg.
Each card shows the network name, type, enabled/disabled status, subnet, and MTU.
Use the search bar to filter networks by name, or the sort dropdown to order by Name A–Z, Name Z–A, By Type, or By Status. Use the ⊞ / ≡ toggle to switch between card grid and list view.
Click a card to open the detail panel showing the full network configuration including subnet, mask, MTU, IPv6, and IPv6 prefix.
Networks are read-only in the dashboard. To create or modify networks, use the VirtualProg app.
📋 Logs
The Logs tab is available in the dashboard when Logs is enabled in Settings → Advanced → Logs. If the setting is off, the tab is not shown.
The tab provides a unified view of all log entries written by VirtualProg — both application-level events and per-VM activity — in one place.
Selecting a Source
Use the source dropdown at the top of the toolbar to choose which logs to display:
- VirtualProg — general application events (server start/stop, settings changes, network activity, and other system-level messages)
- VM name — events specific to that virtual machine (start, stop, pause, resume, errors, and other VM-level activity)
Switching the dropdown immediately fetches and displays the selected source's log entries.
Filtering Logs
| Filter | Description |
|---|---|
| Search | Type any text to filter entries by message content — results update as you type |
| Info / Error | Toggle checkboxes to show or hide entries of each severity |
| From / To | Date range pickers — only entries within the selected window are shown. Defaults to the last 7 days |
All filters work together on the already-fetched data — no extra network request is needed when changing filters.
Log Entries
Each entry shows:
- A coloured dot indicating severity — blue for info, red for error
- The log message
- The timestamp — formatted as date and time (e.g. Apr 19, 2025 at 2:34:56 PM)
Entries are displayed newest first.
Refreshing
Click ↺ Refresh to re-fetch the latest entries for the currently selected source.
Logs are only written when Settings → Advanced → Logs is enabled. If log entries are missing, verify the setting is on.
🖥️ Web Console
The Web Console lets you interact with a VM's serial console directly from your browser — no SSH, no app window required. It uses xterm.js for full terminal emulation with ANSI colour support, connected over WebSocket.
Requirements
- The CLI Server must be running (Settings → CLI → Enable CLI Server)
- The VM must have at least one serial port configured in Console mode
Opening the Console
- Open the Web Dashboard in your browser
- Click any running VM card to open the detail panel
- Scroll to the Console Ports section
- Click Open Web Console next to the port you want
The console opens in a small popup window (720 × 520 px). Each serial port gets its own button and its own popup — you can open multiple consoles simultaneously.
Terminal Features
| Feature | Detail |
|---|---|
| Terminal emulator | xterm.js 5.3 — full VT100/xterm with ANSI colours |
| Scrollback | 5 000 lines |
| Keyboard input | Fully supported — type commands, use arrow keys, Ctrl+C, etc. |
| History replay | The last 64 KB of VM output is delivered immediately on connect, so the login prompt appears without waiting |
| Font | Menlo / Courier New, 14 pt |
Connection Status
A status badge in the toolbar shows the current state:
| Badge | Meaning |
|---|---|
| Connecting… (amber) | WebSocket handshake in progress |
| Connected (green) | Live session — output and input are flowing |
| Disconnected (red) | Connection dropped unexpectedly — auto-reconnects in 3 seconds |
| VM stopped (red) | The VM was shut down — the connection closed cleanly and will not reconnect |
Multiple Connections
Several browser tabs or devices can connect to the same serial port at the same time. All connections receive the same VM output independently; keyboard input from each connection is forwarded to the VM.
When the VM Stops
When the VM shuts down or is stopped from the dashboard, the console displays:
The connection closes cleanly and the console does not attempt to reconnect.
🖥 Connect
Remote Control of running VM's graphical display directly in your browser, with mouse and keyboard input forwarded back to the VM — no VNC, no additional setup required.
Note: It works well for mouse interaction and simple text input. for Modifier key combinations (such as Cmd+Space, Ctrl+Alt+Del, or Alt+F4) use the keys panel in the VM window.
Requirements
- The CLI Server must be running (Settings → CLI → Enable CLI Server)
- The VM must be running — the button is not shown for stopped or paused VMs
- The VM window must be open in the VirtualProg app for live capture and input; if the window is closed, the last captured frame is shown and input is not forwarded
Opening Remote Control
- Open the Web Dashboard in your browser
- Click a running VM card to open the detail panel
- Click 🖥 Connect
The viewer opens in a new popup window (1024 × 768 px, resizable). Each VM gets its own named window — clicking the button again brings the existing window to the front rather than opening a duplicate.
Viewer Controls
| Control | Description |
|---|---|
| VM action buttons | Control the VM directly from the toolbar — buttons change based on the current VM state (see below) |
| Refresh rate selector | Choose how often the display is refreshed: 1, 3, 5, 10, 15, 30 fps |
| Quality selector | Set the JPEG capture quality — High (1.0), Medium (0.8), Low (0.6). Use a lower setting on slow networks to reduce bandwidth |
| 🔒 Lock Mouse | Captures the mouse pointer inside the viewer for smooth, uninterrupted mouse control — press Esc to release |
| ⛶ Fullscreen | Enter or exit fullscreen mode |
| Keys | Send special key combinations to the VM window |
VM Action Buttons
The toolbar shows action buttons that update automatically based on the VM's current state:
| VM State | Buttons available |
|---|---|
| Running | ■ Shutdown, ⏻ Stop, ⏸ Pause, ↺ Restart, 🌙 Suspend (Apple Silicon only) |
| Paused / Suspended | ▶ Resume |
| Stopped | ▶ Start |
Mouse & Keyboard Input
Click anywhere inside the viewer to focus it and start sending input to the VM:
- Mouse — move, left/right click, scroll, and drag all work as normal
- Keyboard — standard keys and text input work; for modifier key combinations use the keys panel in the VM window
- Pointer lock — click 🔒 Lock Mouse to capture the pointer inside the viewer for precision mouse work; press Esc to release
Connection Status
A dot in the top-left of the toolbar shows the state of the connection to VirtualProg:
| Dot | Meaning |
|---|---|
| Green | VM is running; live display active |
| Amber (pulsing) | Refreshing display, or VM is paused / suspended |
| Red | VM is stopped or display unavailable |
VM State Changes
The viewer continues checking the VM state even when it is paused, suspended, or stopped. The display area shows a status message and the toolbar updates to show the appropriate action buttons. When the VM resumes or starts again, the viewer automatically detects the change and resumes live display — no need to reopen the window.
🌙 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
| Shortcut | Action |
|---|---|
/ or Cmd+K |
Focus the VM search box |
R |
Refresh immediately |
Esc |
Close any open panel or dialog |
🔒 Sign Out
Click Sign out in the top-right corner to end your session. Your token is cleared from the browser.