Remote Qubes User Testing (Running Qubes in the Browser)

Testing Qubes OS is not an easy task. It’s not like you can run Qubes on the browser… or can you?!

That’s what we’re about to find out…


What you’ll need

  • a random test laptop running Qubes 4.1
  • internet connection

:warning: A word of caution

This setup involves completely invalidating the security properties of your Qubes installation. Do this only on a device used exclusively for testing.

Additionally, participants will have access to the device as though they were next to you. If you connect the device to you home’s WiFi, you should consider the risk of them being able to see its password or even find your home’s physical address by your home network’s name or the ones around.


We have two devices: the participant’s, which just needs to run Tor Browser and the UX Person’s, which is running Qubes.

:see_no_evil: Limitations

  • 2-20 seconds input delay - can be improved if you use DNS instead of onion services. It really depends on your Tor circuit. I have been able to use with 2-4 seconds.

1. Create qube: remote-admin

Create a new qube called remote-admin with the following settings:

Type StandaloneVM
Template debian-11 (:warning: debian 10 won’t work)

:information_source: Advanced: for simplicity of software installation and persistence we create a standalone qube. Advanced users can probably figure out how to do the same with templates and app qubes.

2. Install remote screen sharing software in dom0:

:information_source: instructions borrow from here (in case they break check there).

Run the following in a dom0 terminal:

# install the qubes contributor's repository
sudo qubes-dom0-update qubes-repo-contrib

# install the remote-desktop software
sudo qubes-dom0-update qubes-remote-desktop

# set "VNCPASS" as the password

#enable the qubes-x0vncserver (for some reason)
qvm-service --enable dom0 qubes-x0vncserver

:arrows_counterclockwise: and then start the dom0 VNC service

systemctl start qubes-x0vncserver@$(whoami)

2. Configure policy dom0 ↔ remote-admin

In dom0’s terminal type the following:

echo "qubes.ConnectTCP +5900 remote-admin @default allow target=dom0" | sudo tee /etc/qubes/policy.d/30-remote-admin.policy

3. (optional) Check that you have dom0 access from remote-admin

In remote-admin:

  1. :arrows_counterclockwise: open a terminal and run qvm-connect-tcp 5900:@default:5900

:information_source: Good point to test
At this stage you can check if you are correctly getting. You can install a VNC viewer like remmina and connect to Then it will ask the password VNCPASS (you set it earlier).

:hammer_and_wrench: Troubleshooting

  • vnc connection failure: too many security failures
    Just restart the vnc server in dom0 systemctl restart qubes-x0vncserver@$(whoami)

4. Install the guacamole server (vnc to web)

:information_source: Guacamole essentially allows users to connect via their web browser to a VNC server.

Still in the remote-admin qube

  1. You install it like this:
sudo apt install -y guacd libguac-client-vnc0
sudo apt install -y tomcat9 tomcat9-admin tomcat9-common tomcat9-user
  1. Download the latest guacamole .war from Apache Guacamole™: Release Archive

  2. Verify the file integrity with the sha256 hashes on the website
    (can save you some troubleshooting time in case your download breaks)

  3. Copy the downloaded file onto /var/lib/tomcat9/webapps/guacamole.war (may need sudo)

  4. restart tomcat for the newly installed .war
    sudo systemctl restart tomcat9

  5. Edit the file /etc/guacamole/user-mapping.xml (you may need to create /etc/guacamole/)

    <authorize username="user" password="pass">
        <param name="hostname"></param>
        <param name="port">5900</param>
        <param name="password">123456</param>
  1. Restart guacamole to apply the changes: sudo systemctl restart guacd.

  2. Open firefox on the webpage:

    You should see a login page. Your credentials are:
    user: user
    pass: pass

:partying_face: Hurray!
Now you have a functioning dom0 remote access via the web browser.

But this is not super useful since it is just local access and you can’t give that address for a user to test. In the next section, we’ll show you how you can generate an address where your users can test your system.

4. Create a .onion address for it

  1. sudo apt install tor
  2. edit the file /etc/tor/torrc and add the following text at the end and save it:
HiddenServiceDir /var/lib/tor/guacamole_vnc
HiddenServicePort 80
HiddenServiceVersion 3
  1. restart Tor to apply the changes
    sudo systemctl restart tor

  2. Obtain your .onion address
    sudo cat /var/lib/tor/guacamole_vnc/hostname

    :information_source: Save this link as that will be what you share with your participants.
    Just be aware that they have to install the Tor Browser in order to access it.

  3. Grab some tea :tea: while the onion address propagates through the Tor network. (max 10 mins)

5. Share the link with your participants

  1. Send yoursite.onion/guacamole with participants
  2. Tell them to log in with:
    user: user
    pass: pass

When you restart your computer

Everything with :arrows_counterclockwise: you have to run every time you restart your computer / remote-admin qube.

Tips & Tricks

:ghost: Hiding remote-admin qube

Because an extra qube is running it could interfere with a user’s experience (e.g. they will see it in the qube domains widget). To hide it, you can delete sys-whonix or sys-usb and rename remote-admin to either one. An unsuspecting users won’t see any difference.

Making this faster

See this related discussions.


  • @fepitre for putting together qubes-remote-desktop and pointing me to it

  • Inspiration from this guide and this discussion.

  • byzanz developers, which made a tool that can be installed in dom0 through the repos and allows for creating gifs from dom0.


Just fixed some typos through @Rnd3sB3g13rng’s attempt at running the guide. Thanks!

1 Like

Is it risky if I have installed this in my personal Qubes

Well, if you do this on your personal computer, of course you increase the risks of someone else accessing it remotely. But it can also be convenient.

With onion v3 addresses (the ones used) unless you share the .onion address with someone or enter it in a computer you don’t trust, then nobody should be able to guess it. But you should consider further hardening it by using authenticated onion services.

You can read more about this topic on the whonix wiki:

Personally, I wouldn’t do this on my personal computer, nor recommend anyone do it.

You can also look into GitHub - QubesOS/qubes-remote-support documented here.

1 Like

Thanks, that is helpful .

1 Like

Hello I get

user@remote-admin:~$ sudo apt install -y guacd libguac-client-vnc
Reading package lists... Done
Building dependency tree       
Reading state information... Done
E: Unable to locate package guacd
E: Unable to locate package libguac-client-vnc

Edit: Did you mean (Debian -- Details of package libguac-client-vnc0 in bullseye)?

It will be more fun if you can Install Qubes as VM and use it from the browser in another VM :stuck_out_tongue: Xzibit style :stuck_out_tongue:

“Sup dawg, I herd you like QubesOS, so We put an QubesOS in your QubesOS VM so you can use QubesOs from the browser while you use QubesOS”

1 Like

Yes. That’s probably it. Thanks for catching the typo.

You might find this related: Qubes Air: Generalizing the Qubes Architecture | The Invisible Things

This is really awesome.
I don’t think I’ll ever have a use-case in my personal or professional life for it, but it is very cool.

1 Like

Just added a link to a discussion about making setups like this faster.


Do I have to enable a special repository? My last question was a bit misleading, I guess. Both of
guacd and libguac-client-vnc0 are not available in the debian-10 template.

sudo apt install -y guacd libguac-client-vnc0
Reading package lists... Done
Building dependency tree       
Reading state information... Done
E: Unable to locate package guacd
E: Unable to locate package libguac-client-vnc0

Not available in debian-10
Both available in current stable debian-11

Thanks @Rnd3sB3g13rng and @unman for the feedback. Actually I had tested on debian-11 and not debian-10.

I just updated the instructions to reflect this:

Do you mean tomcat9-admin?

I have set up tomcat and tor and when I enter my .onion address I get
It works !

If you’re seeing this page via a web browser, it means you’ve setup Tomcat successfully. Congratulations!

This is the default Tomcat home page. It can be found on the local filesystem at: /var/lib/tomcat9/webapps/ROOT/index.html

Tomcat veterans might be pleased to learn that this system instance of Tomcat is installed with CATALINA_HOME in /usr/share/tomcat9 and CATALINA_BASE in /var/lib/tomcat9, following the rules from /usr/share/doc/tomcat9-common/RUNNING.txt.gz.

You might consider installing the following packages, if you haven’t already done so:

tomcat9-docs: This package installs a web application that allows to browse the Tomcat 9 documentation locally. Once installed, you can access it by clicking here.

tomcat9-examples: This package installs a web application that allows to access the Tomcat 9 Servlet and JSP examples. Once installed, you can access it by clicking here.

tomcat9-admin: This package installs two web applications that can help managing this Tomcat instance. Once installed, you can access the manager webapp and the host-manager webapp.

NOTE: For security reasons, using the manager webapp is restricted to users with role “manager-gui”. The host-manager webapp is restricted to users with role “admin-gui”. Users are defined in /etc/tomcat9/tomcat-users.xml.

How do I access guacamole?

Yes, probably.

You need to go to /guacamole. Have you done it?

1 Like

Yes, that did it! Thanks for the great guide.

1 Like

You’re welcome! Thanks for trying it out and giving feedback!