Wasabi Setup in Virtual Machines

A step by step guide on how to use Wasabi Wallet in virtual machines like Qubes OS or VirtualBox. This is the Wasabi documentation, an archive of knowledge about the open-source, non-custodial and pri

[[toc]]

Benefits of Virtual Machines

Virtualization allows you to create and run as many virtual machines (VMs) on a single computer at one time as desired. The only constraints are the amount of RAM and hard disk space available on the host computer.

Each VM is isolated from the host machine. Therefore, such things as corrupted files, configuration errors, malware, etc., encountered during the use of a VM do not affect the host computer.

If you are a developer, using virtual machines gives you several powerful features. You can easily:

  • Create snapshots of a VM's state at any time. These snapshots can be restored later if a problem or undesired condition arises in the current state of the VM.

  • Set up a template VM with a desired development environment or configuration, and then quickly create lightweight, disposable clones of the template for specific tests.

  • Develop and/or test applications in Windows, Linux, and macOS at the same time, on the same computer. You can link them together in a customizable internal network if desired.

For developers, the use of virtual machines offers some of the basic version control features of git but applied to operating systems rather than files or projects.

Qubes

Qubes is a free and open-source security-oriented operating system meant for single-user desktop computing. Qubes OS leverages xen-based virtualization to allow for the creation and management of isolated virtual machines (VMs) called qubes. This is valuable for users of high security software like Wasabi Wallet, and especially useful for testers of cutting edge developer branches. There is a separation of the virtual machines running Wasabi on testnet, and those running on mainnet with valuable private keys. If a reviewer compiles a malicious developer branch, then his mainnet private keys are secure in a different qube.

This is a step-by-step guide on how to properly compile Wasabi Wallet from source in independent qubes. For tutorials on how to download and install Qubes, please see their exhaustive documentation.

Generate Template VM

The dependencies to compile Wasabi from source will be downloaded and installed in a new template VM, which is generated by cloning the Debian template from the dom0 terminal.

[user@dom0 ~]$ qvm-clone debian-12-xfce template-wasabi

Install Dependencies

Start the gnome-terminal of template-wasabi.

[user@dom0 ~]$ qvm-run -a template-wasabi gnome-terminal

Update the template-wasabi.

[user@template-wasabi ~]$ sudo apt update
[user@template-wasabi ~]$ sudo apt upgrade
[user@template-wasabi ~]$ sudo apt dist-upgrade

Install .NET ${dotnetVersion} SDK for "Build apps" in template-wasabi.

:::tip Optional for privacy You can disable .NET's telemetry, which is sending some usage information to Microsoft:

[user@template-wasabi ~]$ export DOTNET_CLI_TELEMETRY_OPTOUT=1

To make this persistent, add DOTNET_CLI_TELEMETRY_OPTOUT=1 to the /etc/environment file.

:::

If you need to update .NET, then do it in this VM. Now shut down template-wasabi.

[user@dom0 ~]$ qvm-shutdown template-wasabi

Generate App VM

Create a new App VM source-wasabi which is based on template-wasabi. This qube will be used to download, compile and run the Wasabi source code. This way you can create multiple App VMs for different testing purposes. All these App VMs will be updated when you update template-wasabi.

[user@dom0 ~]$ qvm-create source-wasabi --template template-wasabi --label red

Ensure the VM has at least 5GB of disk available for the upcoming build (default is 2gb).

Compile and Run Wasabi

Start the gnome-terminal of source-wasabi.

[user@dom0 ~]$ qvm-run -a source-wasabi gnome-terminal

Clone & run Wasabi.

[user@source-wasabi ~]$ git clone https://github.com/zkSNACKs/WalletWasabi.git
[user@source-wasabi ~]$ cd WalletWasabi/WalletWasabi.Fluent.Desktop
[user@source-wasabi ~]$ dotnet run

To check out a developer branch:

[user@source-wasabi ~]$ git remote add nopara73 https://github.com/nopara73/WalletWasabi
[user@source-wasabi ~]$ git fetch nopara73
[user@source-wasabi ~]$ git checkout <development branch>

Pull the latest commits.

[user@source-wasabi ~]$ git pull

Install Package in App VM

Alternatively, you can also install the package in a new App VM, this is a stable version suitable to use on mainnet and is separated from the development App VM. There are no additional dependencies required, so the App VM can be based on debian-12-xfce directly.

[user@dom0 ~]$ qvm-create package-wasabi --template debian-12-xfce --label red
[user@dom0 ~]$ qvm-run -a package-wasabi gnome-terminal

Download, verify and install the latest Wasabi-${currentVersion}.deb package in package-wasabi, then start Wasabi.

[user@package-wasabi ~]$ wassabee

VirtualBox

VirtualBox is a lightweight, powerful free and open-source virtualization tool that allows you to run one or more independent operating systems as "virtual machines" (VMs) on your computer. The computer on which VirtualBox is installed is referred to as the "host" machine, and the VMs that are created are referred to as "guests".

Presently, VirtualBox runs on Windows, Linux, Macintosh, and Solaris hosts and supports a large number of guest operating systems including, but not limited to Windows (NT 4.0, 2000, XP, Server 2003, Vista, Windows 7, Windows 8, Windows 10), DOS/Windows 3.x, Linux (2.4, 2.6, 3.x and 4.x), Solaris and OpenSolaris, OS/2, and OpenBSD.

You can download the latest Virtualbox binary for your host OS here.

Make sure that you also download the VirtualBox Extension Pack, shown just below the links for downloading the binary installation files. This package will add several useful capabilities to VirtualBox.

Detailed instructions for installing VirtualBox on your host computer can be found here.

If you run into trouble or have special requirements, the complete User Manual can be found here.

Create Your First Virtual Machine

Detailed instructions for creating various types of virtual machines can be found here.

Things to Note:

  • For each operating system version that you wish to use in a VM, you will need an .iso installation file for that particular OS.

  • During the installation process for whatever OS you have chosen for your VM, you will likely see references to your hard disk and/or Master Boot Record. Be assured that those references are pertaining to your "virtual" hard drive and/or boot records that are a part of the VM. They are NOT referring to your computer's physical drive or boot records.

Other than the creation of a folder which holds the data for each VM that you may create, your physical hard drive and/or boot records will not be altered or harmed by the installation of an OS inside the VM.

  • Optional, but strongly recommended: Enable the built-in "Guest Additions" functions of Virtualbox. This step will give you a full-sized display, and make the usage of your mouse seamless when switching between different VMs that are running at the same time. Instruction for enabling "Guest Additions" can be found here.

Generate a Template VM

It's now time to start customizing your development templates! Make sure that you have run any needed updates for your VM.

Next, the dependencies to compile Wasabi from source will be downloaded and installed in a new template VM, which can be based on your preferred OS.

With VirtualBox, you can create separate templates based on Windows or any Linux distribution. Finally, you can add any other tools that you prefer, such as Visual Studio / Visual Studio Code, Atom, etc..

Install Required Dependencies

Start your template VM and open a terminal window.

Install .NET ${dotnetVersion} SDK for "Build apps".

:::tip Optional for privacy You can disable .NET's telemetry, which is sending some usage information to Microsoft. In your terminal window, run:

your@vm:~$ export DOTNET_CLI_TELEMETRY_OPTOUT=1

:::

If you need to update .NET, do it in this VM.

Now, shut down your template VM.

Cloning a Virtual Machine

At this point, you should have a Template VM set up with your preferred tools and environment.

Now the real fun begins, and you will be rewarded for all of your hard work to get to this point!

VirtualBox will allow you to make as many lightweight, or "linked" clones from a template as you may need. "Linked" means that the vast majority of the system files are borrowed from the template VM while the clone is running, so that the clone takes up much, much less hard drive space.

Any changes to the clone VM, constructive or destructive, do not affect the template VM. You may think of a linked clone as a "disposable" copy of your template. Perfect for experimentation, with no risk to your template or your computer!

How to Create a Linked Clone

Instructions on how to create linked clones in VirtualBox can be found here.

Compile and Run Wasabi in Your VM

Start your cloned VM, and open a terminal window.

Clone & run Wasabi.

your@vm:~$ git clone https://github.com/zkSNACKs/WalletWasabi.git
your@vm:~$ cd WalletWasabi/WalletWasabi.Fluent.Desktop
your@vm:~$ dotnet run

Check out a developer branch.

your@vm:~$ git remote add nopara73 https://github.com/nopara73/WalletWasabi
your@vm:~$ git fetch nopara73
your@vm:~$ git checkout <development branch>

Pull the latest commits.

your@vm:~$ git pull

If you are comfortable with Git, you can now have several versions of Wasabi running for testing purposes, at the same time, on the same computer.

Install Latest Package

Alternatively, you can also install the package in a new VM. This is a stable version suitable to use on mainnet and is separated from the development VM. There are no additional dependencies required to run this version.

Download, verify and install the latest Wasabi-${currentVersion} package in your VM, then start Wasabi.

Have fun, and please consider contributing to the Wasabi project!

Last updated