Arcane — The PowerShell Remote Desktop
Introduction
Arcane is a remote desktop application that stands out as the first and currently the only fully functional remote desktop solution coded entirely in PowerShell. The PowerShell server is comprised of a single module file that encapsulates all functionalities, making it easy to import and use without requiring additional, cumbersome dependencies or configurations.
The server is inherently compatible only with Microsoft Windows operating systems (tested on Windows 10 and 11, both 32-bit and 64-bit versions, as well as Windows 11 ARM). However, the client, also known as the viewer, is cross-platform and can run natively on Windows, macOS, and Linux desktop distros (x86 and ARM).
This project is entirely open-source and free to use. You can access the source code on the following GitHub repository.
If you’re eager to start experimenting right away, feel free to skip ahead to the “Let’s Play” chapter.
I. The Foundations
Before being renamed to Arcane, the project was originally called PowerRemoteDesktop. As the name suggested, the project was initially coded entirely in PowerShell, including the client/viewer. The name was later changed to Arcane to give the project a more distinctive and unique identity. Additionally, the client was fully ported to Python, using PyQt6 as its graphical engine, which allowed the application to become cross-platform.
The original motivation behind creating PowerRemoteDesktop was to demonstrate the versatility of PowerShell and to show that it is possible to develop nearly any kind of application, including complex ones, using only PowerShell.
PowerRemoteDesktop is now deprecated and has been completely replaced by Arcane. However, you can still access the original project through its original and official GitHub repository:
II. Capabilities Tour
Desktop Streaming
What makes Arcane a true remote desktop application is its efficient approach to screen sharing. Instead of sending the entire screen to the client — an approach that, while simple, would be slow and require significant bandwidth and CPU resources — Arcane only transmits the portions of the screen that have changed. This is accomplished through a special algorithm that compares the current screen with the previous one, sending only the differences. As a result, the application is exceptionally fast and consumes minimal bandwidth.
How does it work? The remote screen is divided into fixed-size squares, typically 64x64 pixels by default. Each square is compared with the corresponding area on the previous screen. If a square has changed, it is marked as a “dirty” square. Once the entire screen is scanned and all dirty squares are identified, the server sends the client the largest rectangle that encompasses all the changes, using the top-left and bottom-right dirty squares to define this “dirty rectangle.”
Some remote desktop protocols use different methods, such as sending dirty squares individually or dividing the screen into lines or columns. However, I chose this method because it is the most efficient and delivers the best performance for most remote desktop use cases. While streaming full-screen video or video games might perform better with a different approach, that is not the primary purpose of Arcane.
Even though the application relies on the CPU to calculate dirty rectangles rather than the GPU, it remains highly efficient, even at 4K resolutions. Ideally, leveraging the GPU would offer even better performance, but since PowerShell does not natively support GPU usage — at least not without complex and potentially unreliable hacks — using the CPU is the most practical solution.
Security
Arcane was designed with security as a top priority. All traffic between the client and server is encrypted using TLS, with support for a minimum of TLS v1.2 up to the latest version. Even though the traffic is encrypted, password is never transmitted directly over the network. Instead, password authentication uses a challenge-based mechanism, where each challenge is used only once per client/server connection, not per session. This means that even if someone eavesdrop for a valid and active session token, they would still need to authenticate using a new challenge along with the session token which is impossible without the password.
In future versions, Arcane will also support client certificates for authentication, further enhancing security.
As of August 2024, Arcane is in beta, and server fingerprint validation has not yet been implemented. This feature was available in PowerRemoteDesktop but has not yet been ported to Arcane.
Multi-Screen
If the remote computer has multiple screens connected, Arcane will offer the option to choose which screen to display and control after the connection is established.
You can also launch two instances of the Arcane Viewer to connect each instance to a different screen, allowing you to seamlessly drag and drop windows between the two instances.
In the future, there are plans to support displaying multiple screens within a single instance of Arcane.
Mouse Synchronization (Native-Reflection)
One feature commonly found in advanced remote desktop applications is the ability to synchronize the mouse cursor between the remote computer and the viewer’s virtual desktop, providing a better user experience and a more immersive feel.
To achieve this in Arcane, I use a hacky technique that involves enumerating cursor handles, with each handle representing a different mouse state. The technique regularly polls the current cursor information using the GetCursorInfo Windows API, which returns the current cursor handle within its structure. By comparing this value with the collected handles, we can determine which cursor is currently being displayed and update the viewer accordingly.
For those not interested in diving deep into the Arcane Server code, I’ve published a small snippet of this technique on my Gists, which you can find here.
Session Concurrency
Finally, Arcane Server supports concurrent sessions, enabling multiple users to connect to the server simultaneously from different locations. This feature not only allows the display of all available screens at once but also facilitates collaboration by allowing multiple users to access and control the remote desktop concurrently.
Chapter Conclusion
We’ve covered the most important features currently available in Arcane, but there’s still more to discover that we haven’t touched on. Please note again that Arcane is currently in beta. One feature, Clipboard Synchronization, is already implemented on the server side but has not yet been integrated into the client. Rest assured, future releases will include a fully functional Clipboard Synchronization feature, similar to what was available in the former PowerRemoteDesktop project.
III. Let’s Play
If you’re eager to give Arcane a try, you’re in the right place. The prerequisites are minimal. For the client/viewer, you’ll need Python installed on your local machine with a minimum version of 3.8. For the server, PowerShell is required on your Windows machine with a minimum version of 5.1. Additionally, make sure a screen, a dummy HDMI dongle, or an active Virtual Desktop is in use; otherwise, you might encounter a black screen. As long as PowerShell 5.1 or higher is available, any Windows version newer than XP is supported.
Install Client / Viewer
Arcane Viewer is available on PyPI.org, and the easiest way to install it is by using pip:
pip install arcane-viewer
I always recommend using a Python virtual environment to segregate the dependencies of different projects. Here are the steps to install Arcane in a virtual environment:
# Python virtualenv must be installed on your local system
python -m venv venv
source venv/bin/activate
(venv) pip install arcane-viewerYou can now launch the viewer using the following command:
arcane-viewer
Installing the Server
The easiest way to install Arcane Server is by using the PowerShell Gallery with the Install-Module command (Your need to be administrator):
Install-Module -Name Arcane_Server
You can now open another terminal, either with or without administrative privileges, and run the following command to bypass the PowerShell execution policy:
powershell.exe -executionpolicy bypassNext, import the module and launch the server with the default configuration. By default, this will generate a strong password and create a self-signed certificate, which will be stored in the local user certificate store. Nothing else is required — it’s very easy!
Import-Module Arcane_Server
Invoke-ArcaneServer
You can now connect to the newly created remote server using the viewer by entering the server’s IP address, port, and password. Enjoy the immersive experience of a tangent universe!
Arcane Viewer : Kali Linux
On certain Linux distributions, you might need to install additional dependencies before using Qt. For example, on Kali Linux, to use Arcane Viewer, you must first install the following package:
sudo apt install libxcb-cursor-dev
IV. Other Installation Methods
Here, you’ll find a non-exhaustive list of alternative methods for using both the viewer and server beyond the straightforward and traditional approach.
Client / Viewer
If you prefer not to rely on PyPI.org to install the package, you can download the built package from the official repository releases section. You can then use either the .whl or .tar.gz file to install the package with pip.
pip install arcane_viewer-1.0.0b1.tar.gzYou can also build your own package using the build.sh script located in the root folder of the arcane_viewer Python project.
Please note that to use build.sh, you must have the following dependencies installed on your system:
If you prefer, you can skip the tox and flake8 checks by using the --skip-tox and --skip-flake8 switches when running the build.sh script.
./build.sh [--skip-tox] [--skip-flake8]After the build process, if successful, both the .tar.gz and .whl files will be located in the dist folder within the root directory of the package.
Finally, you can also run the application directly by navigating to the project’s root directory and executing the following command:
git clone https://github.com/PhrozenIO/Arcane.git
cd Arcane
pip install -r requirements.txt
python -m arcane_viewer.mainServer
Installing the server using the PowerShell Gallery is the most straightforward and recommended method. However, depending on your environment, needs, and use case, it might not always be ideal. There are several methods available to install a new PowerShell module or script in your environment.
The great thing about Arcane Server is that it can be used either as a PowerShell module or as a standalone script.
Below are some examples of how to implement the server as a script and make it available to the current terminal session:
# Implement from local file
IEX (Get-Content .\Arcane_Server.psm1 -Raw)
# Or
# Implement from remote location
IEX (New-Object Net.WebClient).DownloadString('http://<ip>/Arcane_Server.psm1')
# Invoke-ArcaneServer should now be available
Invoke-ArcaneServerYou can also manually install Arcane Server as a module in one of PowerShell’s module directories.
Please note that depending on your system and configuration, you may need to adjust the execution policy to allow the script to run or make necessary changes to your system configuration (with caution).
It is highly recommended to read the README file from the repository to familiarize yourself with all available parameters. In some cases, it may be necessary to use your own certificate (either encoded or as a file) to launch the server.
V. Known Issues
(Windows) Closing the desktop window can causes the viewer window to freeze.
In some circumstances, closing the virtual desktop window can cause the viewer window to freeze on Windows. This issue arises from an ineffective connection closure, which prevents the thread’s wait signal from being released. I’m currently investigating this problem and will provide a fix as soon as possible.
Window Placement Issues on Wayland
On the Wayland display server protocol, Qt applications often experience window placement issues. This is a well-known problem that is not caused by Qt itself. I will explore possible workaround techniques to address this issue.
Black Screen
A black screen indicates that no desktop is currently available for capture. Arcane Server relies on the user’s ability to capture the desktop via standard Windows APIs. This requires a valid desktop to be present in the current session, which can be achieved by having a physical monitor connected, an active RDP session, or by using an HDMI dummy plug when no monitor is connected.
LogonUI
PowerRemoteDesktop provided a way to capture secure desktops, including UAC prompts, the CTRL+ALT+DEL screen, and the user logon UI. This feature is planned for Arcane but has not been implemented yet. When available, it will require the Arcane Server to run as a SYSTEM user. Currently, to control a remote desktop, an active user session must be open.
Keyboard Improvements
Remote keyboard control will be enhanced in future releases. On some systems, like macOS, you may encounter issues using certain special characters, particularly with specific keyboard layouts. This issue requires careful attention and will be addressed in upcoming updates.
VI. Conclusion
Arcane is a promising project that is still in its early stages, but you can expect it to grow rapidly (depending on my available free time). My priority is to ensure everything runs smoothly across different operating systems before adding new features. Stay tuned for updates, and feel free to star the repository to show your support.
If you’re curious to see how it works, you can watch the video below that demonstrates Arcane in action:
