Guest row routing and direct-agent authority
TvRMM can show a VM or container in more than one way. The row you use determines whether an action is relayed through the parent host or sent to a real agent installed inside the guest.
Use this page when a Proxmox VE or Unraid host reports guests, containers, or Docker workloads and you need to decide which row owns an action.
Row types and authority
| Portal row | What remains visible | Authority path | Use it for |
|---|---|---|---|
| Unlinked host-observed guest | Hidden from the default endpoint list unless host-observed guest stubs are enabled. The parent host inventory table can still link to the guest context. | Parent host relay, only for supported guest actions. | Host-observed state, host power/lifecycle actions shown by the portal, host-relay terminal where supported, host-relay patch scan/install where supported. |
| Linked host-observed guest | The direct in-guest agent remains the normal endpoint-list row. The linked guest stub is suppressed from the default list and remains reachable as linked guest context from the direct agent or host inventory. | Direct workflows use the linked in-guest agent. Host power/lifecycle actions still relay through the parent host. | Direct audit, patching, agent update, terminal, scripts, logs, performance, and remote access through the linked real agent when other gates pass. |
| Direct in-guest agent | Normal direct endpoint row. If it is linked to a host-observed guest, that direct row is the visible/canonical endpoint row in the current endpoint list. | Real TvRMM agent installed inside the guest. | Standard endpoint management, including direct patching, scripts, terminal, agent update, cleanup, and remote desktop where supported. |
Linking is metadata-only. TvRMM does not install an agent inside the guest during linking. Install the regular agent in the guest OS first, wait for it to enroll, then link the host-observed guest to that enrolled agent.
Roles
- Viewer can read visible endpoint state.
- Operator can run endpoint actions such as patch scan/install, agent update, scripts, terminal, reboot, and supported host-relayed guest actions when policy and endpoint support allow them.
- Admin is required to link or unlink a host-observed guest and an in-guest agent.
- Operating-as can lower your effective role. If your effective role is capped below operator or admin, the corresponding controls stay unavailable.
For linked guest actions, TvRMM also checks operator authority on the linked in-guest agent. A user who can see the host-observed guest but cannot operate the linked agent cannot run linked-agent actions.
Expected behavior by action
| Action | Unlinked host-observed guest | Linked guest | Direct in-guest agent |
|---|---|---|---|
| Patch scan | Relays through the parent host where the portal exposes support. Proxmox LXC and QEMU paths use host-side guest execution. Unraid Docker reports running image details. Unraid VM host-relay patching is not supported. | Queues a normal patch scan to the linked real agent and records the linked guest context. | Queues a normal patch scan to the real agent. |
| Patch install | Relays through the parent host only for supported Proxmox LXC and QEMU guests. Running services may restart. Unraid Docker image pulls remain in Unraid-native workflows; Unraid VM host-relay patch install is not supported. | Queues a normal patch install to the linked real agent and records the linked guest context. | Queues a normal patch install to the real agent. |
| Agent update | Requires a linked or direct real agent. | Queues the update to the linked real agent and records the linked guest context. | Queues the update to the real agent. |
| Reboot | Uses the host-relayed guest action when the portal exposes the action for that guest type. | Direct reboot actions use the linked real agent; host power/lifecycle controls still use the parent host. | Uses the real agent. |
| Scripts | Requires a linked or direct real agent. | Uses the linked real agent. | Uses the real agent. |
| Terminal | Opens a host-relay terminal where supported by the guest type and parent host configuration. | Uses the linked real agent for direct terminal workflows. Host-relay terminal can still be available from guest context where shown. | Uses the real agent. |
| Remote desktop | Not available. Remote desktop requires a direct or linked real agent with helper, policy, license, role, and relay gates satisfied. | Open the linked real agent endpoint to use Remote. | Uses the real agent when all Remote tab gates pass. |
| Performance | No live direct-agent performance feed. Host-observed facts can still appear from host inventory. | Uses direct-agent metrics when the linked agent reports them. | Uses direct-agent metrics. |
| Logs | Host-observed entries can appear when the parent collector attributes logs to the guest. | Direct-agent entries and linked guest context appear when collection attributes logs to the guest. | Uses direct-agent logs and collected-log policy. |
Online and freshness
An unlinked host-observed guest is online only when the parent host is fresh and the guest's host-reported state is running-like. If the parent host is stale, the guest state is stale too.
A linked guest or direct in-guest agent uses the direct agent's heartbeat and status for online/freshness. A stopped VM on a healthy host can still appear offline before an in-guest agent reports directly.
Unlinked host-observed guest stubs are hidden from the default endpoint list. Enable the host-observed guest-stub view only when you need to inspect or link those rows.
Link, unlink, and recovery
To link a guest:
- Install the regular TvRMM agent inside the VM or container.
- Confirm the new direct agent checks in under an organization you administer.
- Open the host-observed guest context from the parent host inventory or guest-stub view.
- Use Link managed agent and select the enrolled in-guest agent.
The portal can auto-link only when there is exactly one safe same-tenant name match. Ambiguous matches are ignored so the wrong guest is not linked.
To unlink a mistaken link, use Unlink managed agent from the guest context with an admin effective role. After unlinking, the host-observed guest returns to host-relay behavior and the real agent remains a normal direct endpoint row.
Escalate to support when the parent host inventory, guest row, and direct in-guest agent cannot be matched safely, when a link option is missing from an organization you administer, or when an action result appears under the wrong row.