--- title: "Using the Workspot Linux Agent" slug: "using-the-workspot-linux-agent" tags: ["Linux", "Templates", "Workspot Linux Agent", "wscompletesetup", "wsrunonce"] updated: 2026-04-15T20:30:05Z published: 2026-04-15T20:30:05Z --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.workspot.com/llms.txt > Use this file to discover all available pages before exploring further. # Using the Workspot Linux Agent This document describes how to create a Workspot Linux desktop template that not only includes the Workspot Linux Agent but the packages that turn Linux into an RDP-enabled Workspot desktop. See [Workspot Linux Desktop](/v1/docs/workspot-linux-desktops-and-apps) for more general information about Linux desktop support. Installation is divided into four major steps: 1. Creating VMs on AWS EC2, Azure, or GCP. 2. Configuring the template VM. 3. Registering the VM with Control. 4. Testing. Additional sections cover special configuration, management tasks, and troubleshooting. ## **1.0 Create Linux VMs** You must first create the VMs that will form the base of the templates visible in Workspot Control. In general, choose the same VM parameters (RAM, vCPUs, etc.) for these VMs that you expect to use for the desktops built from the template. - For AWS EC2, follow the steps in [Creating an Ubuntu Linux Template on Amazon AWS](/v1/docs/creating-a-linux-template-on-amazon-aws). - For Azure or GCP, follow the steps in [Creating Linux VMs on Azure and GCP](/v1/docs/creating-linux-vms-on-azure-and-gcp). ## **2.0 Configure the Template VM** Now that we have a base image, we need to log into it and install not only the Workspot Linux Agent but also the software packages that turn our generic image into an RDP-enabled graphical Linux desktop. These are done at the same time with a script provided by Workspot. Follow the steps in the following article to configure the Template VM: [Configuring the Template VM With the Workspot Linux Agent](/v1/docs/configuring-the-template-vm-with-the-workspot-linux-agent) ## **3.0 Register the Template with Workspot Control** ### **3.1 Azure Registration** **Step 1.**Stop the VM from the Azure portal. **Step 2.**In Control, go to “Setup > Cloud > *azure_cloud_name*” and click on “Register Template.” Choose respective resource group and give respective VM name, click on the Search button. Your new template should be listed. **Step 3.**Select your template VM and Click on “Save.” **Step 4.**You successfully added Azure Linux Template to Control. It will be in Published mode. ![](https://cdn.us.document360.io/ad9153e1-c8de-4f56-94f2-b717a1fc3a68/Images/Documentation/417b852b-f304-44fe-b732-108539ae98fb.png) ### **3.2 GCP Registration** Unlike Azure, GCP requires additional steps before registering with Control. GCP Console Pre-Registration. #### **GCP Console Pre-Registration** **Step 1.**Create a new intermediate image under the images tab in the GCP portal using the VM instance disk you created earlier. **Step 1a.**Select a name for this intermediate instance. It can be anything acceptable to GCP (lowercase letters, numerals, and hyphens). **Step 1b.**Select as the “source disk” the VM instance on which we just installed the Linux agent. **Step 1c.**Leave “Location” as “Multi-Region.” ![](https://cdn.us.document360.io/ad9153e1-c8de-4f56-94f2-b717a1fc3a68/Images/Documentation/a0ea799a-9a76-4e0a-abc4-358a9868799f.png) **Step 2.**Now we (finally) create an installable template. Go to “Instance template” and click “Create Instance Template.” **Step 2a.**Give it a name you can live with: This name will be imported into Control as the template name and will be listed with your other templates. ![](https://cdn.us.document360.io/ad9153e1-c8de-4f56-94f2-b717a1fc3a68/Images/Documentation/68c832fc-0e67-4a10-abc6-0de0e00a8674.png) **Step 2b.**Choose the same machine configuration as you used for the original VM instance. ![](https://cdn.us.document360.io/ad9153e1-c8de-4f56-94f2-b717a1fc3a68/Images/Documentation/eda12a51-f9c0-402c-ad15-3575bfc9ae58.png) **Step 2c.**Under Boot disk, choose the “custom image” that matches the name of our original Linux VM (not the instance we created a minute ago). ![](https://cdn.us.document360.io/ad9153e1-c8de-4f56-94f2-b717a1fc3a68/Images/Documentation/eb7539b7-10d9-456b-b5ee-d5815f19970c.png) **Step 2d.**Select/keep the same network configuration as we chose in the beginning. ![](https://cdn.us.document360.io/ad9153e1-c8de-4f56-94f2-b717a1fc3a68/Images/Documentation/e6a7c393-0b78-48be-858c-2ef417b57c6f.png) **Step 2e.**Create the Instance Template. #### **Register the GCP Template with Control** **Step 3.**Go to “Control > Setup > Cloud > *gcp_cloud_name”*and click “Register Template.” Type the template VM name (“**tdevjubuntudemo**” in the screen shots above) into Search box and click “Search.” ![](https://cdn.us.document360.io/ad9153e1-c8de-4f56-94f2-b717a1fc3a68/Images/Documentation/24af1c9b-c5e0-4f93-9c5c-7dd8de37f573.png) **Step 4.**Select your Template VM and Click “Save.” **Step 5.**The template is now published in Workspot Control. ### **3.3. AWS Registration** This should already have been done in [Step 1](/v1/docs/using-the-workspot-linux-agent#10-create-linux-vms). If not, follow the registration steps in [Creating a Linux Template on Amazon AWS EC2](/v1/docs/creating-a-linux-template-on-amazon-aws). ## **4.0 Testing** **Step 1.**Using your new template, create a desktop pool with at least one desktop, assign yourself to the pool, and launch your new Linux desktop via any Workspot Client. **Step 2.**You should see your Linux GNOME desktop, which uses X Windows as its graphical interface and xRDP for network transport. By using RDP, your Linux desktop interacts with Workspot gateways and Clients like a Workspot Windows desktop. ## **File Locations** - Agent files are in **/var/opt/workspotagent**. - Scripts are in **/var/opt/workspotagent/config/workspotscripts**. - Log files are in **/var/log/workspotagent**. - Scripts have their own log directory: **/var/log/workspotagent/scriptlogs.** Access the files by signing in as root: `$ Su` `$ enter root user password :` `$ cd /var/log/workspotagent` `$ ls -al` ## **Setup Scripts** Workspot Agent uses XML files and Bash scripts to control initialization and operation. See the [Workspot Agent Scripts](/v1/docs/workspot-desktop-agent-installation-and-configuration#workspot-agent-scripts) section of [Workspot Desktop Agent Installation and Configuration](/v1/docs/workspot-desktop-agent-installation-and-configuration) for more information. ### **Setup Complete Script** The Workspot Agent runs the **wssetupcomplete.bsh** script immediately after the VM is cloned and registered with Workspot Control, but *before* the domain is joined. It is not run on subsequent restarts. This script will be run whether or not domain joining is enabled. It is used to install or configure software on the VM’s first boot. It is especially useful if the domain will not be joined, or is joined by other means than that provided by Workspot, since the other script, **wsrunonce.bsh**, is only run on domain-joined VMs. The script does not exist by default. For information about Agent’s scripts and the associated XML files, see the [WsSetupComplete.cmd Script](/v1/docs/workspot-desktop-agent-installation-and-configuration#wssetupcomplete-script) section of [Workspot Desktop Agent Installation and Configuration](/v1/docs/workspot-desktop-agent-installation-and-configuration). **Usage:** - Create the file here: `/var/opt/workspotagent/config/wssetupcomplete.bsh`. - **Wssetupcomplete.bsh** must be a Linux-formatted text file (that is, newlines are LF, where in Windows they are CR/LF and on Mac they are CR). - It must start with `#!/bin/bash` and contain valid shell commands. - For example, the following script restarts the Apache service after waiting two seconds: `#! /bin/bash` `echo "wsSetupComplete script is triggered"` `sleep 2` `sudo systemctl restart apache2` - Make it executable with `sudo chmod +x /var/opt/workspotagent/config/wssetupcomplete.bsh` - Make sure that any packages you refer to in your script are available when the VM is created (that is, when the script is run) or are downloaded by the script. ### Run Once Script The **wsrunonce.bsh** script is run after domain join. As its name implies, it runs just once, when the Agent is run for the first time, and never again. If domain-joining is not enabled, the script is not run. For information about Agent’s scripts and the associated XML files, see the [WsRunOnce.cmd Script](/v1/docs/workspot-desktop-agent-installation-and-configuration#wsrunonce-script) section of [Workspot Desktop Agent Installation and Configuration](/v1/docs/workspot-desktop-agent-installation-and-configuration). **Usage:** - Create the file here:` /var/opt/workspotagent/config/wsrunonce.bsh`. - It must be a Linux text file with **#!/bin/bash** as its first line, followed by commands. - *Sample code:* This code will echo text to the log, wait for two seconds, then restart the ssh service. `#! /bin/bash` `echo "wsRunonce script is triggered"` `sleep 2` `sudo systemctl restart ssh` - Give execute permission to the script: `$ sudo chmod +x  /var/opt/workspotagent/config/wsrunonce.bsh` ## **Miscellaneous Tasks** ### **Re-Register the Agent with a Pool Token** This operation requires a Pool Token from Workspot Control. See [Reregistering VMs and Templates Using an Agent Token](/v1/docs/workspot-desktop-agent-installation-and-configuration#reregistering-vms-and-templates-using-an-agent-token). When logged into the desktop VM as a domain administrator or as root, go to **/var/opt/workspotagent/config/workspotscripts** and run the **wsactl** commands: `sudo bash wsactl -–unregister sudo bash wsactl -–re-register tokenid` ### Reconfigure the Agent with New Domain Details, etc. To reconfigure domain join details (like domain name, OU, domain username, password), run the following command: `sudo bash workspot_installer.sh –reconfigure` ### **Uninstall the Agent** This uninstalls the Agent and all its configuration. **Debian and Ubuntu** `sudo apt purge workspotagent` **CentOS and RHEL** `sudo rpm erase workspotagent` ### **Install the Agent in Silent Mode** To install in silent mode, run: `sudo bash workspot_installer.sh --silent` ### **Upgrade Agent Manually** If Workspot provides a link to an update file in **.tar.gz** format, install it as follows: On a Linux VM on which you will install the update, go to **/var/opt/workspotagent/config/workspotscripts/** Download the update with: `curl -O URL` where “URL” is provided by Workspot and starts with https:// and ends with a filename with a **.tar.gz** extension. Install the update with: `./autoupgrade filename.tar.gz  ./upgrade.log` Verify the upgraded agent version as described in “Check the Agent Version” below. ### **Start, Stop, etc. The Agent Service** - `sudo systemctl status workspotagent.service` - `sudo systemctl restart workspotagent.service` - `sudo systemctl start workspotagent.service` - `sudo systemctl stop workspotagent.service` - `sudo systemctl disable workspotagent.service` - `sudo systemctl enable workspotagent.service` ### **Check the Agent Version** **Debian and Ubuntu** `sudo apt-cache policy workspotagent` **CentOS /RHEL** `sudo yum info workspotagent` ### **Check Workspot xRDP Version** **Debian and Ubuntu** `sudo apt policy xrdp-workspot` **CentOS /RHEL** `sudo yum info xrdp-workspot` ## **Troubleshooting** ### **Can’t Log in via RDP/Remote Desktop on GPU-equipped VMs** 1. Use ssh as described in [Using a Jump Server](/v1/docs/configuring-the-template-vm-with-the-workspot-linux-agent) to log into the template VM. 2. Run this command: ```bash sudo bash /var/opt/workspotagent/config/workspotscripts/setup_gpu.bsh ``` 1. Try to connect to the Linux VM via Remote Desktops.