Repository navigation
Fleet Dashboard
The Fleet Dashboard is the main screen of Veyport. It shows all the servers that have been registered with your Hub.
Admin vs Viewer: All users can view the Fleet Dashboard, search/filter servers, and click into server details. Only admins can add, edit, or unregister servers.
Each server is displayed as a row in the fleet table showing:
- Server name - the label you gave it when adding it
- Status indicator - a coloured dot showing whether the server is reachable
- Hostname and IP address - populated automatically when the agent registers
- Operating system - detected by the agent
- Agent version - the version last reported by the Veyport agent. Blank or missing versions show Not reported; an offline server continues to show its last reported version.
- Last seen - when the Hub last received a heartbeat from the agent
| Colour | Meaning |
|---|---|
| Green | Online - the agent is connected and responding |
| Red | Offline - the agent was previously connected but is no longer reachable |
| Amber / Yellow | Pending - the server record has been created but the agent has not registered yet |
| Amber / Yellow | Pending re-enrollment - the agent's certificate expired while offline; the node is awaiting admin approval to rejoin |
A server stays in initial "pending" state until you run the install command on that machine. Once the agent runs and calls home, the status moves to "online."
When a server shows Pending re-enrollment, its agent certificate has expired and the agent has phoned home to request a new one. The server row shows the node's hostname and IP address. Click its name to open the Server Detail page for more information.
Only admins can approve or deny re-enrollment. Click the server name to open the Server Detail page, where the approve/deny controls are located. Approval requires a TOTP step-up. Once approved, the node reconnects automatically with the same server identity — no ghost records, no path reassignment needed.
Use the status filter buttons at the top of the dashboard to quickly narrow the view:
- All - Shows every server regardless of status
- Online - Shows only servers with an active agent connection
- Offline - Shows only servers that have lost their agent connection
- Pending - Shows only servers awaiting agent registration
The active filter is highlighted. The count next to each filter label updates in real time.
The table shows up to 25 servers per page. Use Previous page and Next page to move through the filtered results. The select-all checkbox selects rows on the current page only; changing pages, filters, or the search clears the selection.
The search bar at the top of the dashboard filters servers by name as you type. The search is debounced - there is a short delay after you stop typing before results update. This keeps the interface responsive when you have a large fleet.
You can combine the search bar with the status filters. For example, type "prod" and select "Online" to find all online servers with "prod" in their name.
Only admins can add servers.
-
Click the Add Server button in the top-right corner of the dashboard.
-
The Add Server modal will appear.
-
Enter a Name for the server (this is just a label - it does not have to match the actual hostname).
-
Optionally add Labels to help you organise servers (e.g.
env:production,region:eu-west). -
Click Add Server.
-
Veyport creates the server record and generates a one-time install command. It will look something like:
curl -fsSL https://veyport.example.com/install.sh | bash -s -- --token <token> -
Copy the command and run it on the target server as root (or with
sudo). The script downloads and installs the Veyport agent, then registers the server with the Hub using the embedded token. -
Once the agent connects, the server row changes from amber (Pending) to green (Online) automatically - no page refresh needed.
The registration token is single-use and expires after a short period. If you do not run the command in time, delete the server and add it again to get a fresh token.
Any user (admin or viewer) can install the vey command-line client from the dashboard.
-
Click the Install CLI button in the top-right corner of the dashboard, next to Add Server.
-
The Install CLI modal shows a one-line install command pre-filled with this Hub's address:
curl -fsSL https://veyport.example.com/install/cli.sh | sh -
Copy it and run it on your own machine (Linux or macOS). It detects your platform, verifies the download's checksum, and installs
veyto/usr/local/binor~/.local/bin. No root is required. -
Then run the pre-filled sign-in command from the modal, e.g.
vey --hub https://veyport.example.com login.
After signing in, run vey servers list, then vey ssh-cert and vey ssh <server-name-or-id>
to open an interactive shell on an online server. Some released CLI builds omit these SSH commands
from vey --help; they can still be run directly. See CLI for the connection quick start,
full command reference, and manual install path, and SSH Gateway for gateway requirements.
The Fleet Dashboard polls the Hub every 10 seconds and updates all server rows in place. You do not need to reload the page to see status changes.
Polling pauses when the browser considers the tab hidden. A stalled request can also block later polls. Signed-in pages send separate, throttled session checks after recent keyboard, pointer, input, touch, or scroll interaction in a visible tab. This includes the Add Server dialog and works independently of a stalled server-list query. These checks stop in hidden or unattended tabs; see Logging In and Troubleshooting for session limits and network failures.
Click a server name to open the Server Detail page for that server. From there you can browse the remote filesystem, tail logs, and upload files.
Admins can update an eligible enrolled agent from the Agent Version cell in its server row. The Hub reports Update available when a newer supported agent release is ready, or Up to date when there is no newer release. Older agents that need the direct-SSH bootstrap show Manual upgrade required; installations the updater cannot support show Update unsupported. These checks use the Hub's verified distribution and do not query GitHub directly.
To update, choose Update available for one row. Review the node, current and target versions, and restart warning, then click Update agent to confirm. The dialog shows reported operation stages and the final result. It monitors for up to 150 seconds while open; close and reopen it or click Refresh status to continue checking. There is no bulk update action.
When a verified operation finishes, the dashboard automatically refreshes the reported agent version, update availability, and dialog check. After a successful update, the row shows the version reported by the agent and Up to date when the Hub has no newer artifact. Closing the dialog still lets the regular fleet polling refresh the version and recheck availability when that version changes; availability also refreshes every 60 seconds while the tab is visible. A request whose response was lost continues to show Inspect update until you reopen the dialog to reconcile its operation status.
The agent must be idle. The Hub blocks new work during the update and refuses to start while tracked file, log, terminal, command, or other agent work is active or cannot be confirmed idle. Let that work finish and retry later. A successful result is recorded only after the agent reconnects and confirms the exact target version and artifact. If you close the dialog, reopen the action for that server to retrieve its operation status. After a full page reload, open that server's Agent Version action to retrieve the latest operation, even while the node is offline. An interrupted request alone does not establish success or failure. Checking or refreshing status does not restart an update. An unknown outcome remains blocking until it is reconciled; follow the documented CLI or direct-SSH recovery procedure before creating another update. Review a failed operation and confirm the node is ready before trying again.
The Fleet Dashboard action uses the standard update flow documented in Deployment#update-the-cli-and-enrolled-agents. It requires a live interactive administrator session and a Standard installation. Older agents that require a one-time preserving bootstrap still need the direct-SSH process there, including the operator's idle confirmation where required; the dashboard does not assert that a legacy node is idle on the operator's behalf.
Click the checkbox on any server row to select it. A toolbar will appear above the table showing how many servers are selected and offering bulk actions:
- Unregister Selected - Removes all selected servers from the Hub (admin only). You will be asked to confirm before proceeding.
Select the top-level checkbox (in the toolbar header) to select or deselect all visible servers at once.
Only admins can unregister servers.
Warning: Unregistering a server is permanent. The server record is deleted from the Hub database and cannot be recovered. If the agent is online, it will be automatically uninstalled from the remote machine. To re-add the server later, you must go through the full add-and-install process again.
Single server: Click Unregister in the server row's Actions column.
Multiple servers: Select the servers you want to remove using the checkboxes, then click Unregister Selected in the bulk action toolbar.
When you unregister a server, the Hub sends a cleanup command to the agent on that machine. The agent will:
- Stop the
veyport-agentsystemd service - Remove the agent binary
- Remove the configuration file (
/etc/veyport/agent.conf) - Remove the dropzone staging directory
Once cleanup is confirmed, the server record is deleted from the Hub database.
If the agent is offline (unreachable at the time of unregistration), the Hub skips the remote cleanup step and deletes the server record from the database only. You will need to clean up the agent files on that machine manually if desired.
The unregister action is recorded in the Audit Logs as server.unregistered.