Skip to content
Portal

Installing the VDI Agent

The VDI Agent is a small local application used for VDI profiles in Agent connection mode. It runs a background service on your machine, establishes the WireGuard VPN tunnel to your cloudspace, and starts the RDP connection to your virtual desktop. If your VDI profile uses RD Gateway mode instead, you don't need the agent — see RD Gateway or Linux VDI RD Gateway.

Getting to the Download Page

  1. Your Pilvio.pro customer administrator shares a link with you — the profile's Agent Landing Page.
  2. Open that link in your browser. It detects your operating system automatically and shows a status banner:
    • "No agent has been detected yet" — you need to install it.
    • "VDI agent detected!" — you're ready to start a session.
    • "New agent version vX.X.X is available" — an upgrade is available.
    • "The <OS> agent isn't available yet, but it's on the way!" — no build exists yet for your operating system.
    • "Agent not authorized for this browser and/or Pilvio.pro" — reinstall the agent and retry.
  3. If an install or upgrade is needed, click Download Agent (or Upgrade Agent to vX.X.X).

Windows

  1. Run the downloaded installer and follow the on-screen instructions.
  2. Once installed, run the agent from your applications.

macOS

  1. Open your Downloads folder and double-click the downloaded file to unpack it.
  2. Drag the unpacked agent into your Applications folder.
  3. Double-click the agent icon to run it, then follow the on-screen instructions.

Linux

  1. Open a terminal in your Downloads folder.

  2. Make the downloaded file executable:

    sudo chmod +x vdi-agent_linux_amd64_<version>.run

  3. Install it:

    sudo ./vdi-agent_linux_amd64_<version>.run -- --install

Starting a Session

Once the landing page shows the agent is detected and ready, click Start Session. The page walks you through connection progress ("Warming things up…", "Preparing your desktop…", "Getting everything in place…", "Your session is ready!") and then hands off to the agent automatically — no manual configuration is needed.

Windows: existing WireGuard sessions

On Windows, the landing page checks whether another active WireGuard/VPN session overlaps with your cloudspace's network range before letting you start. If it finds one, it shows the conflicting networks and a Re-check button — disconnect the other WireGuard tunnel from your system tray first, then click Re-check to continue.

How the VDI Agent Connects

The agent runs a small local service that the landing page talks to directly on your machine — this is separate from your Pilvio.pro portal login:

  1. As soon as the landing page detects the agent is running, it requests an auth token from it.
  2. When you click Start Session, the landing page asks the agent for its WireGuard public key, then requests a session from the portal, passing that public key along.
  3. Once the session is ready, the landing page sends the WireGuard peer configuration and RDP target details to the local agent, which brings up the tunnel and starts the RDP connection.
  4. RDP traffic is routed through the encrypted WireGuard tunnel to your virtual desktop.

Tip

The VDI Agent must be running for the entire duration of your VDI session. Closing it disconnects the session.

Troubleshooting

Landing page shows "No agent has been detected yet" after installing: - Make sure the agent application is actually running (check for its tray/menu-bar icon). - Wait a few seconds — the landing page automatically re-checks for the agent every 5 seconds.

"Agent not authorized for this browser and/or Pilvio.pro": - Reinstall the agent and try again.

Start Session is disabled on Windows: - You likely have another WireGuard/VPN session active that overlaps with your cloudspace's network. Disconnect it from the Windows system tray, then click Re-check on the landing page.

Slow or choppy desktop: - Check your local internet connection speed. - Close bandwidth-intensive applications on your local machine.