How to use disposables
A disposable is a stateless qube, which does not save data between reboots. These qubes can serve various uses cases that require a pristine environment:
Viewing untrusted files without other trusted files on the same system;
Visiting untrusted websites in a web browser without authentication cookies from previous session;
Sanitizing untrusted PDFs or images and retrieving a safe-to-view image;
Connecting untrusted devices in isolation from trusted devices or files;
Fresh environment for build systems (for technical users).
Disposables can be launched either directly from GUI domain’s app menu or terminal window, or from within app qubes. Disposables are generated with names like disp1234, where 1234 is a random number. Below is an example of disposable workflow benefits:
Example of how disposables can be used to safely open untrusted links and attachments in disposables
In the work-email qube, the user clicks on a link. This link is opened in a new disposable (through the qrexec protocol qubes.OpenURL). The link contains some kind of malware that infects the disposable qube, but it is harmless for the work-email qube, as the links was opened in a separate environment from the mail client, the mail box is safe. The disposable is later destroyed.
In that same work-email qube, the user now opens a PDF attachment. Using the qrexec protocol (qubes.OpenInVM), the PDF is opened as in a new disposable qube, this time, the file looks clean, but as we can never be sure, the user prefers to default to open files in disposables. The disposable is later destroyed.
This diagram provides a general example of how disposables can be used to safely open untrusted links and attachments in disposables. You may find more on why one would want to use a disposable on the first disposable qube article. Please note that the blog post is dated and some of the information it presents are not accurate anymore.
Disposable types
Disposable template
Disposable template is not a disposable in itself, but a special template that can create different disposable types: normal disposables and named disposables. If you need to have a persistent changes in disposable files (e.g. configuration files), do them in the disposable template. If you need certain programs to be available in the disposable, you can install them in the disposable template’s own template. By default, Qubes OS creates the default-dvm disposable template. It will be used it as an example on this page. You can create as many disposable templates as you’d prefer. Disposable customization is outside of the scope of this page.
Disposable qube
Disposables are spawned from disposable templates. They don’t have a fixed name and are deleted from the system after the closing of the initial application opened in them. Therefore, any changes you made in the disposable will be lost.
For example, you can use the default-dvm disposable template to create a disposable qube to browse the internet. Every time you launch an application using this disposable template as base, a new disposable qube named disp1234 (where 1234 is a random number) starts and launches the chosen application. If you close the application window, the disp1234 qube shuts down and vanishes from your system.
Disposables spawned through the Devices widget’s Attach to new in disposable feature don’t have a set initial application - they must be manually turned off when no longer needed.
Named disposable
Named disposables are built upon disposable templates, but they have a fixed name. The named disposable behaves like an ordinary app qube - it doesn’t shutdown when you close the initial application, every application you open will start in the same qube, and you need to manually shut it down. However, when it is shutdown, any changes you made in the named disposable will be lost - as in any other disposable.
If you have selected during installation to use disposable service qubes, your sys-net, sys-usb and sys-firewall are examples of named disposables based on the default-dvm disposable template.
How to create disposables
How to launch new disposables based on existing template
Disposables can be started with 
. Select the application you wish to launch in a new disposable, and one will be created for you. Notice that the application was not opened in the disposable template default-dvm: instead, it opens in a disp1234 qube. This is because applications from a disposable template listed in the APPS tab will open in a new disposable.
After the qube is created, you can access it via other tools using its disp1234 name, for example in Qubes Domains widget, Qubes Manager, , qvm-copy, qvm-ls etc.
How to create named disposables
Named disposables can be created with , choose a name, configure according to your needs and click on Create.
If you create the qube with the name test-disp, you can open applications on it using and selecting the application you wish to open in the named disposable.
How to create new disposable templates
First, create a normal application qube (using Create New Qube GUI tool or qvm-create. Customize it according to your needs. Then, in Qube Settings, check the Advanced -> Disposable template checkbox on this qube.
In action
Open an application in a disposable (from GUI domain)
Sometimes it is desirable to open an instance of Firefox in a new fresh disposable. This can be done easily using the app menu: just go to . Wait a few seconds until the web browser starts.
It is possible to do the same as above using the command line:
user@dom0:~$ qvm-run --dispvm=default-dvm --service -- qubes.StartApp+firefox
The browser is opened from a disposable based on the default-dvm qube.
Open a file in a disposable (from app qube)
In an app qube’s file manager, right click on the file you wish to open in a disposable, then choose Edit/View in disposable qube. Wait a few seconds and the default application for this file type should appear displaying the file content. This app is running in its own dedicated qube, a disposable created for the purpose of viewing or editing this very file. If you have edited the file and saved the changes, the changed file will be saved back to the original app qube, overwriting the original.
It is also possible to do the same from the command line using qvm-open-in-dvm:
[user@work ~]$ qvm-open-in-dvm -- 'apple-sandbox.pdf'
[user@work ~]$ qvm-open-in-dvm --view-only -- 'apple-sandbox.pdf'
The PDF viewer is opened in a disposable based on the work qube default disposable template.
Sanitize a file in a disposable (from app qube)
There is a nice security property in the system that allows transforming untrusted files into trusted files, this process is called sanitization. A sanitized file, presumably, leaves no room to malicious code, therefore, you can safely open the sanitized file in the qube itself (doesn’t need to view in disposable anymore), in a viewer outside of Qubes OS, or send the sanitized file to someone that doesn’t use Qubes OS and can’t make the conversion themselves without compromising them..
Only supported file types for conversions are images and PDFs. The untrusted files will be converted to RGBA bitmap. On conversion, the original untrusted files will be moved to ~/QubesUntrustedPDFs or image.png-untrusted (location depends on the file type) while the sanitized file will be created with the same location and name by reconstructing the received data. As the output is an image, the sanitized files are a bit bigger, searching strings without OCR will not be possible anymore.
If you’d like to sanitize a file, in an app qube’s file manager, right click on the file (image or PDF) you wish to sanitize in a disposable, then choose Convert in disposable qube. Wait a few seconds for the conversion. This conversion runs on its own dedicated qube, a disposable created for the sole purpose of sanitizing this very file.
It is also possible to do the same on the command line using qvm-convert-img and qvm-convert-pdf.
Connect a device to a disposable (from GUI domain)
Sometimes you have a device which you don’t trust, therefore you decide to leverage disposables for the task. To attach a device to a disposable, go to .
Note
No application will launch by default and the disposable will continue running, that is expected, no application request was made. Also notice that opening and closing the first (or any other) application opened in the disposable will not turn it off, this is also expected, you must shutdown disposables created by the Qubes Devices widget manually.
The same can be done from the command line, although more difficult:
user@dom0:~$ disp_template="default-dvm"
user@dom0:~$ disp="$(python3 -c "import qubesadmin; \
app = qubesadmin.Qubes(); \
appvm = app.domains['$disp_template']; \
disp = qubesadmin.vm.DispVM.from_appvm(qubesadmin.Qubes(), appvm); \
disp.start(); \
print(disp.name)
")"
user@dom0:~$ qvm-device <DEVICE_CLASS> attach <ATTACH_OPTIONS> -- "$disp" <BACKEND:DEVICE_ID>
user@dom0:~$ # Do your tasks.
user@dom0:~$ qvm-device <DEVICE_CLASS> detach <ATTACH_OPTIONS> -- "$disp"
user@dom0:~$ qvm-kill -- "$disp"
Faster disposable startup (preloading)
Disposable qubes can take some time to boot; preloading speeds this process up.
Preloaded disposables are a type of disposables started in the background, waiting to be used when needed. They are hidden from most graphical applications by using the internal flag. For most intents and purposes, using a preloaded disposable is indistinguishable from using normal disposable qubes, just faster.
It is possible to preload from any disposable template as long as it supports qrexec, except Qubes Windows Tools (QWT) which isn’t feature complete yet.
Preload disposables from the system’s default disposable template
The system setting applies to whichever disposable template is the system default, so if you change the default, the preloaded disposables will be updated accordingly.
Preloading from the system’s default disposable is possible with the . You can start with a small number of qubes to preload, for example 2, and use Apply Changes and Close to save the changes.
This can also be changed from the command line from the GUI domain, with qvm-features targeting dom0:
user@dom0:~$ qvm-features dom0 preload-dispvm-max 2
Preload disposables from a specific disposable template
You can also preload disposables from other disposable templates. This can be useful when the disposable template is intended for specific workflows:
default-mgmt-dvm: management qube, used for Salt, Ansible and Debug Console.qubes-builder-dvm: Qubes Builder V2 Executor qube
To configure, for example, the default-mgmt-dvm qube using the app menu and qube manager, as it is an internal qube, first we need to make it visible, in the . After this step is completed, , choose a number such as 2 and click OK to apply and save changes.
Note
You may deselect Show internal qubes to hide them again after making the changes.
This can also be changed from the command line from the GUI domain, with qvm-features targeting default-mgmt-dvm:
[user@dom0 ~]$ qvm-features default-mgmt-dvm preload-dispvm-max 2
Call to the application succeeds but disposable exits too soon
When the main process of the initial application used to start the disposable exits, the disposable is removed. Some applications, such as GNOME Terminal (show on the app menu as Terminal, do not wait for the application to close before the main process exits.
These cases requires wrappers to keep the application running. Qubes provides a wrapper for this particular case, qubes-run-gnome-terminal, which will be used automatically by qubes-run-terminal or application Run Terminal if GNOME Terminal happens to be the preferred terminal for the disposable template.