How to use disposables
A disposable is a stateless qube, it does not save data for the next boot. These qubes can serve various uses cases that require a pristine environment:
View untrusted files without other trusted files on the same system;
Visit untrusted websites in a web browser without previous authentication cookies present;
Sanitize untrusted PDFs or images and retrieve a safe-to-view image;
Connect untrusted devices without other trusted devices or files on the same system;
Fresh environment 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, named disposable and unnamed disposables. When there is need to customize the files of a disposable, it must be done on the disposable template or the template itself to be reflected in every new disposable based on that template. By default, Qubes OS creates the default-dvm disposable template, we will use it as an example on this page, but you can create as many disposable templates as you’d prefer. Disposable customization is outside of the scope of this page.
Named disposable
Named disposables are built upon disposable templates, but they have a fixed name. The named disposable seems to behave like an ordinary app qube, the qube doesn’t shutdown when you close the initial application, every application you open will start in the same qube, and you need to manually shutdown the qube. But when you shutdown, any changes you made in the named disposable will be lost. 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.
Unnamed disposable
Unnamed disposables are built upon disposable templates, they don’t have a fixed name and are deleted from the system after the initial application opened in them is terminated. The Qubes Devices widget doesn’t connect to an initial application when creating a disposable, therefore it must be manually turned off. You would probably use the default-dvm disposable template to, for example, create an unnamed 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. Therefore, any changes you made in the named disposable will be lost.
How to create disposables
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 unnamed disposables
Unnamed disposables can be created with , select the application you wish to launch in a new unnamed disposable and one will 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 unnamed disposable.
After the qube is created, you can access it via other tools using its disp1234 name, Qubes Domains widget, Qubes Manager, , qvm-copy, qvm-ls etc.
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 default-dvm qube derives a disposable to open the browser.
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 work qube default disposable template derives a disposable to open the PDF viewer.
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), open the sanitized file 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.
Currently, supports file types for conversions are images and PDFs. Sanitized images and PDFs will be converted to RGBA bitmap (a raster image where pixels are stored in Red, Green, Blue and Alpha). 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.
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 an unnamed 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> dettach <ATTACH_OPTIONS> -- "$disp"
[user@dom0 ~] $ qvm-kill -- "$disp"
Retrieve unnamed disposables faster (preloaded disposables)
Disposable qubes can take some time to boot. It is possible to queue several unnamed disposables, guaranteeing a faster workflow.
Preloaded disposables are started in the background and kept hidden from the user when not in use. They are interrupted (paused or suspended, as appropriate) and resumed (transparently) when a disposable qube is requested by the user.
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
Configuring system’s default disposable template setting is very useful when you use this disposable template a lot. The system setting applies to whichever disposable template currently is the system’s one, so if you change it, the preloaded disposables will be updated accordingly.
Preloading from the system’s default disposable is possible with the and choose a small number such as 2 for testing, end with Apply Changes and Close.
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
Configuring per disposable template setting is very useful when the disposable template is intended for specific workflows:
default-mgmt-dvmserves as a management qube, used for Salt and Debug Console.qubes-builder-dvmserves as a 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 an application exits, the unnamed 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.