1 Preface

We have created this handbook as an instructional manual on how to use the Subgraph operating system. This handbook also introduces various security and privacy enhancing technologies that we have developed at Subgraph.

We wrote this book for new users of Subgraph OS. Whether you are new to Linux or coming from another Linux-based operating system, we want to ease your transition to Subgraph OS.

In the first section, we describe how to perform common tasks such as installing Subgraph OS and using the various applications that are included. Start here to get up and running with Subgraph OS as quickly as possible.

The next section describes the various features of Subgraph OS that distinguish it from other operating systems. Users can refer to this section to learn the various security and privacy features. Advanced users will find this section useful for configuring operating system features and Subgraph applications.

2 Subgraph OS

2.1 What is Subgraph OS?

Subgraph OS is an adversary resistant computing platform.

Subgraph OS empowers people to communicate, share, and collaborate without fear of surveillance and interference. We designed it so that our users can safely perform their day-to-day tasks securely and privately.

In some ways, Subgraph OS is like other operating systems -- it is derived from Debian GNU/Linux. It provides the familiar GNOME desktop environment as its graphical user interface. Subgraph OS includes applications found in other Linux distributions. These similarities make Subgraph OS easy to adopt, especially for users with prior Linux experience.

Subgraph OS also has key differences from conventional Linux operating systems. In particular:

  1. Subgraph OS anonymizes Internet traffic by sending it through the Tor network
  2. Security hardening makes Subgraph OS more resistant to security vulnerabilities
  3. Subgraph runs many desktop applications in a security sandbox to limit their risk in case of compromise

2.2 What do we mean by security and privacy?

People attach different meanings to the words security and privacy. In computer security, a secure system is one that assures the confidentiality, integrity, and availability of information it stores, processes, or communicates.

Confidentiality assures that information is not revealed to anybody who is not authorized

Integrity assures that information cannot be modified or tampered with by anybody who is not authorized

Availability assures that information can be reliably accessed by those who are authorized

Privacy is similar to confidentiality. Privacy also relies heavily on the integrity of communications. Our computers and other devices gather a great deal of information about our thoughts, our lives, and our social networks. They transmit this information over the Internet without our knowledge and consent. We have no way to trust the systems and networks that relay our communications over the Internet.

We designed Subgraph OS with these concerns in mind. We did this because we believe people should be able to communicate with each other privately. We also believe that people should not be required to reveal information about themselves or their social network without explicit consent.

2.3 What is adversary resistant computing?

We designed Subgraph from the ground up to defend against threats to security and privacy. We aim to provide our users with a computing platform that is adversary resistant.

We when use the term adversary, we are referring to an actual or hypothetical threat to the confidentiality, integrity, and availability of information.

Hackers who exploit software vulnerabilities are a type of adversary. This is an actual and often active threat to security and privacy.

Adversaries present passive or indirect threats as well. An adversary may be passively gathering network traffic to conduct surveillance on users.

Lastly, adversaries may present theoretical or impractical threats. For example, a cryptography algorithm may have a theoretical weakness. At the time the weakness is discovered, the threat may not practical in the real world. As technology and attack methods improve, the weakness ceases to be theoretical and real world attacks emerge.

We use the term adversary to cover all of the above possibilities.

Secure systems should be resistant to all of these types of threats.

While no computing platform can anticipate and defend against all possible threats by all possible adversaries, we aspire to make such attacks extremely difficult for adversaries. By making these attacks difficult, they also become more expensive for adversaries. Adversaries must bear the cost at scale if a large number of users deploy strong security and privacy defenses. Through Subgraph OS, we aim to make these defenses freely available and easy to deploy.

Some of our users have critical security and privacy needs. Subgraph OS grants them strong security and privacy to conduct their activities safely. Casual users also gain the same security and privacy benefits without having to sacrifice usability and maintainability.

This is adversary resistant computing.

2.4 Getting help with Subgraph OS

We hope to address most concerns with this handbook. If you have questions that are not addressed in this handbook, you can contact us through other means.

Contacting Subgraph

Email: Our email address is info <at> subgraph.com

IRC: You can join our IRC channel #subgraph on the OFTC network

Our IRC channel is also available through webchat at:


Twitter: Our Twitter is @subgraph, send us a message

We are also involved in running the Secure Desktops mailing list. This discussion group covers the topic of Secure Desktop operating systems such as Subgraph OS, Qubes OS, and Tails. Developers from these projects participate in the mailing list.

Further information about Secure Desktops can be found here:


2.4.1 Reporting bugs

If you find a bug in Subgraph OS, you can report it to us on Github.

Our issue tracker for Subgraph OS is:


You can also find our individual software repositories at:


2.4.2 Getting the Subgraph OS Handbook

Up-to-date versions of this handbook can be found on the following page:


The PDF can be downloaded here:


Subgraph OS will also include versions of this handbook in different formats.

3 Installing Subgraph OS

3.1 System requirements

Subgraph OS runs on Intel 64-bit computers. These are the system requirements:

3.2 Downloading and verifying the Subgraph OS ISO

Subgraph OS can be downloaded from our website:


The Subgraph OS download page always has the most up-to-date download links and instructions. You can download the ISO directly from the website or over a Tor hidden service.

You should always verify that the ISO you downloaded is the official version. To verify the ISO, we have included a checksum that is cryptographically signed by our developers.

What is a checksum?

A checksum (or hash) is a string that uniquely identifies some piece of data as being different from another piece of data. It is computed using a special hash algorithm (SHA256 in our case). When data is passed to the hash algorithm, the algorithm will return a shortened string (the checksum) that uniquely identifies the data. Checksums are often used to ensure the integrity of a file. Integrity in this case means that the file has not been corrupted or tampered with during the download.

What is a cryptographic signature?

A cryptographic (or digital) signature is a method of authenticating a piece of data. Data is signed with the private signing key of a person who has created or is sending the data. The signature can then be verified by the recipient using the public key of the sender. If the verification is successful, this ensures that the data was created or sent by the person who signed it and not somebody else. This authenticates the identify of the creator or sender.

Why do we cryptographically sign the checksum?

The checksum is used to verify the integrity the ISO you have downloaded. However, how do you verify that the checksum on our website was provided by us? By cryptographically signing the checksum with our private key, you can verify the authenticity of the checksum.

3.2.1 Verifying the ISO on a Linux computer

To verify the ISO on a Linux computer, you will need to download the ISO, SHA256 checksum, and the signature for the checksum.

The first step is to download our public key, Our public key can be downloaded with the following command:

$ gpg --recv-key B55E70A95AC79474504C30D0DA11364B4760E444

The second step is to verify the authenticity of the signature for the checksum. Run the following command to verify the signature (note: replace the filenames with the names of the files you downloaded):

$ gpg --verify subgraph-os-alpha_2016-06-16_2.iso.sha256.sig \

After running this command, you should see a Good Signature message. If you have seen this message then you can proceed to the next step.

The third step is to verify the integrity of the ISO using the SHA256 checksum. Run the following command to verify the checksum (note: replace the filenames with the names of the files you downloaded):

$ sha256sum -c subgraph-os-alpha_2016-06-16_2.iso.sha256

After running the command, you should see:

subgraph-os-alpha_2016-06-16_2.iso: OK

Congratulations, you have now downloaded and verified the Subgraph OS ISO. You are now ready to try it out!

3.3 Installing from a USB drive on a Linux computer

This section describes how to create a USB installer using Linux. One of these methods will work on any Linux computer (even on Subgraph OS). To create an installer you will need a USB drive with a capacity a 2GB or more.

3.3.1 Creating a USB installer using Gnome Disks

If you have a Linux computer that is running the Gnome Desktop, you can use the Gnome Disks application to create a USB installer.

The following steps show how to make a USB installer using Gnome Disks:

  1. Insert a USB drive into your Linux computer

  2. Open the Gnome Disks application

  3. Select your USB drive

Gnome Disks - select USB drive

Gnome Disks - select USB drive

  1. Select the Format Disk option in the top right corner of Gnome Disks
Gnome Disks - Format Disks... option

Gnome Disks - Format Disks... option

  1. Format the USB drive
Gnome Disks - Format dialog

Gnome Disks - Format dialog

  1. Select the Restore Disk Image option in the top right corner of Gnome Disks
Gnome Disks - Restore Disk Image... option

Gnome Disks - Restore Disk Image... option

  1. Choose the ISO file you want to restore (copy) to the USB drive

  2. Restore the ISO to the USB drive

Gnome Disks - Restore dialog

Gnome Disks - Restore dialog

It should take a few minutes to copy the ISO to the USB drive.

3.3.2 Creating a USB installer using dd

If your Linux computer is not running Gnome Desktop or you want to create the installer from the command-line, you can use the dd utility.

The following steps show how to make a USB installer using dd:

  1. Insert a USB drive into your computer

  2. Open a terminal and run the following command to identify the name of the USB drive:

    $ lsblk

    NOTE: You should see a name such as /dev/sdx for your drive, for example: /dev/sdb. It is important to use only the name without the partition number. If you see something like /dev/sdb1, you can omit the 1 at the end. The dd command uses the name without the partition number.

  3. In the same terminal, run the following command:

    $ dd bs=4M if=subgraph-os-alpha_2016-06-16_2.iso of=/dev/sdx \
    status=progress && sync

    NOTE: Replace the path of the ISO with the path of the ISO you have downloaded and verified. Replace /dev/sdx with the name of your USB drive, for example: /dev/sdb.

Copying the ISO to the USB drive should take a few minutes.

3.4 Booting from a USB drive (Live mode)

Subgraph OS also features a 'live' mode. Subgraph OS live mode runs in memory, directly from the USB drive. While running in live mode, nothing will be saved to your hard-drive. When the live session ends, any data created during your session will disappear, leaving no traces behind on the hard-disk.

People normally run in live mode for the following reasons:

  1. They want to demo Subgraph OS
  2. They want to test Subgraph OS with their particular hardware
  3. They want to perform certain tasks with extra security and privacy but do not want a permanent installation of Subgraph OS

When the Subgraph OS ISO starts, you will be presented with different options. To start the live mode, select Live (amd64).

Subgraph OS boot screen

Subgraph OS boot screen

Please note that the user password on the live image is: live.

4 Everyday usage

Subgraph OS comes with a number of applications that may already be familiar. We have also added newer alternatives that may be less familiar. This chapter shows you how to use these applications to perform everyday tasks.

Subgraph OS is also unique because the applications we have included are run inside of a security sandbox. We call this sandbox Oz. Oz helps protect the operating system and your personal files in case an application is compromised by a security vulnerability.

Each application described in this chapter runs inside an Oz sandbox. This means that they can only access the files and directories that they need to. Each of the applications is isolated from each other. They are also isolated from the system itself. Because the applications are isolated, they cannot access common directories such as Pictures or Downloads in the usual way. This chapter shows you how to manage your files in Oz, with some examples for each application.

4.1 Browsing the Web with Tor Browser

Tor Browser is the default web browser of Subgraph OS. It has a number of security and privacy advantages over other browsers.

The security and privacy features include:

The Tor Browser runs inside a security sandbox, managed by Subgraph Oz. Web browsers represent some of the most complex software available. With complexity comes increased risk to security and privacy. This is what we call the attack surface of an application. Tor Browser is no different than other browsers in that it has a lot of attack surface. A successful compromise of Tor Browser could let an attacker gain access to things such as SSH keys, GPG encryption keys, personal files, email, etc. Our security sandbox technology helps to mitigate these risks.

4.1.1 Configuring the Tor Browser security slider

The Tor Browser includes a security slider that lets users choose the security and privacy features they want to enable. If they enable all of the security and privacy settings, some websites may be slower or may not work as expected. However, the security slider lets them instantly lower the settings if they need a particular website to work better.

We recommend setting the security slider to Medium-High or High. For websites you trust, you can lower the settings to make the website perform better.

We advise against lowering the security slider for any websites that are not accessed over HTTPS. HTTPS helps to make sure that the traffic between the Tor Browser and the website has not been tampered with. This is what we refer to as the 'integrity' security property. If you cannot verify the integrity of the traffic originating from a website by using HTTPS, it may be dangerous to visit the website using lowered security and privacy settings.

4.1.2 Downloading and saving files in the Tor Browser

The Tor Browser runs inside of Oz, our application sandbox. When files are downloaded by a sandboxed application such as the Tor Browser, they are saved within the sandbox. When you close the Tor Browser, Oz will cleanup the sandbox, causing files saved in the sandbox to be destroyed.

To allow the Tor Browser to download that can persist after the application is closed, Oz makes a special exception. This special exception is a shared directory where files can be saved and retrieved later, without being destroyed when Tor Browser is closed. Shared directory, in this case, means a directory that is shared inside and outside of the Oz sandbox. Oz sets up the the following shared directory for saving downloaded files:


The shared directory name may be localized depending on the language settings on your computer. In the case of French, the shared directory would be:


Files downloaded to the shared directory will persist after closing the Tor Browser.

4.1.3 Uploading files in the Tor Browser

When the Tor Browser starts, the Oz sandbox limits its access to files and directories on the computer. For example, a photo from the Pictures directory will not be visible in the sandbox by default. If you want to upload a photo from this directory, you must use the Oz menu to add it to the Tor Browser sandbox. The Oz menu is denoted by the little zebra icon at the top-right corner of the screen.

Oz menu - icon The following actions may be performed using the Oz menu:

  • Add files to sandbox

  • Open terminal in sandbox

  • Shutdown sandbox

Click on the little zebra and then click Add file....

Oz menu - Add file

Oz menu - Add file

You may add more than one file at a time. You may also choose to make these files read-only, meaning that they can only be read and not written to while in the sandbox.