--- title: "Connecting to a virtual desktop" slug: "connecting-to-virtual-desktops" source: "https://app.cloudpe.com/help/connecting-to-virtual-desktops" updated: "2026-08-30T19:03:44.471Z" --- # Connecting to a virtual desktop ## Overview VDI gives you a Windows desktop that runs on CloudPe and opens in your browser — there is no RDP client to install. This article covers connecting to a desktop that already exists: finding it in the dashboard, launching the viewer, signing in with the session's RDP credentials, and sharing the public link with someone who does not have a CloudPe account. VDI is in beta. The **VDI** area is marked as beta in the dashboard navigation, and behaviour may change between releases. ## Before you start - Permissions — you need `vdi_sessions:read` to list a session, view its detail page and launch the desktop viewer. Sharing the public link requires `vdi_sessions:share`; extending an expiring session requires `vdi_sessions:extend`. - A provisioned session — the desktop must already exist and have finished provisioning. A session can only be launched from the `ready` or `active` state. See [Creating a VDI session](/help/vdi-sessions-provisioning) if you do not have one yet. - Region — the session's region must be VDI-enabled by the platform. If it is not, the launch call fails rather than the connect step. - Organization membership — VDI sessions belong to an organization, not a project. Any member of the owning organization who holds the relevant `vdi_sessions:*` permission can connect to the session, not just the person who created it. - Browser access — the desktop is streamed through a WebSocket-based RDP viewer, so the browser must be able to reach the workspace domain. ## Steps 1. In the dashboard sidebar, open **VDI** under **COMPUTE**. The **VDI Sessions** page opens on the **Sessions** tab and lists the sessions your organization owns. ![](/kb/vdi/connecting-to-virtual-desktops-01-sessions.png) 2. Check the session's status badge. A session that is still provisioning or booting cannot be connected to yet — use **Refresh** to re-read the list while it settles. 3. Select the session to open its detail page. The **Overview** tab shows the session's status, its expiry, and the RDP username and password used to sign in to Windows. 4. Click **Open Desktop**. The browser RDP viewer loads and connects to the desktop. ![](/kb/vdi/connecting-to-virtual-desktops-02-open-desktop.png) 5. Sign in at the Windows lock screen with the RDP username and password from the **Overview** tab. The password is shown once when the session is created; afterwards retrieve it from the session's credentials on the detail page. 6. If the viewer does not connect, use **Refresh status** on the detail page to re-read the session state from the workspace server, then try **Open Desktop** again. 7. To let someone else connect without signing in to CloudPe, use **Copy Link**. This copies the session's public share URL, which is keyed on a unique per-session slug. Anyone holding the link can reach the desktop and its credentials, so treat it as a secret. ## API The following operations are available on the public API. Authenticate with an API key. List the sessions your organization owns: ```bash curl https://app.cloudpe.com/api/v1/vdi/sessions \ -H "Authorization: Bearer " ``` Read one session, including its status and connection details: ```bash curl https://app.cloudpe.com/api/v1/vdi/sessions/ \ -H "Authorization: Bearer " ``` Launch the desktop on the workspace server (the session must be `ready` or `active`): ```bash curl -X POST https://app.cloudpe.com/api/v1/vdi/sessions//launch \ -H "Authorization: Bearer " ``` The share link resolves against two endpoints that require no authentication — this is why the link must be distributed carefully: - `GET /api/v1/vdi/public/{slug}` - `GET /api/v1/vdi/public/{slug}/credentials` ## Limits & billing - A session has an expiry. The default lifetime is 24 hours and the maximum configured lifetime is 720 hours; an extension that would push the total past that maximum is rejected. Once a session has expired it stops accepting connections and is queued for deletion. - Concurrent sessions per user are capped at 30, and session creation is rate limited to 60 per hour. - VDI is billed hourly for as long as the session exists, whether or not anyone is connected. The hourly rate is a component total: compute (flavor), storage (volume), operating-system licence, floating IP where one is attached, and the VDI management fee. Delete a desktop you no longer need rather than leaving it idle. ## Troubleshooting | Error | What it means | What to do | |---|---|---| | `Session is not ready for connection` | The session is not in a state that accepts a connection. | Wait for the status to reach `ready` or `active`, then retry. Use **Refresh status** on the detail page. | | `Session is not yet provisioned on the workspace server.` | The desktop has not been handed off to the workspace server yet. | Wait for provisioning to complete and retry. If it never leaves `provisioning`, contact support. | | `Session cannot be launched in '{…}' status. Must be 'ready' or 'active'.` | You tried to launch from a state such as shelved, stopped or failed. | Unshelve or start the session first, then launch. | | `Session has expired.` | The session passed its expiry time. | Extend the session before it expires (requires `vdi_sessions:extend`), or create a new one. | | `Session IP not yet assigned` | The desktop has no address yet, so the viewer cannot reach it. | Wait for the status sync to complete and retry. | | `VDI workspace returned an error launching the session.` | The workspace server rejected the launch. | Retry; if it persists, raise a support ticket with the session ID. | | `Workspace server is temporarily unavailable. Please try again.` | The workspace server is not reachable. | Retry shortly. | | `VDI is not enabled for this region` | The session's region does not offer VDI. | Create the desktop in a VDI-enabled region. | | `VDI credentials not configured for region {…}. Contact administrator.` | The region is missing its VDI workspace credential. | Contact your administrator or CloudPe support. | | `VDI session not found` | The session ID does not exist, or it is outside your organization. | Confirm the session ID and that you are working in the owning organization. | ## FAQ **Do I need to install an RDP client?** No. The desktop streams into the browser through the built-in viewer. **Where do I find the desktop password?** It is returned once when the session is created and afterwards available from the session's credentials on the detail page. **Can a colleague connect to a desktop I created?** Yes. Any member of the owning organization with `vdi_sessions:read` can open and connect to the session. **Does the public share link require a login?** No. The slug-based URL and its credentials endpoint work without authentication, which is what makes anonymous sharing possible — only distribute the link to people who should have full access to the desktop. **Is the desktop still billed if I close the browser tab?** Yes. Billing runs while the session exists, not while the viewer is open. Delete or shelve the desktop to stop consuming resources. ## Related - [Creating a VDI session](/help/vdi-sessions-provisioning) - [VDI desktop groups](/help/vdi-desktop-groups)