X-Git-Url: https://git.ralfj.de/bubblebox.git/blobdiff_plain/9f759e738ebda4bc95c177c3d2206bb5481483bc..8805de02dfd6fab4240022e3da5f0bb988de58d2:/README.md?ds=sidebyside

diff --git a/README.md b/README.md
index e63c4e2..32aa2ec 100644
--- a/README.md
+++ b/README.md
@@ -6,10 +6,13 @@ This is the documentation of [BubbleBox](https://www.ralfj.de/projects/bubblebox
 tool to easily sandbox Linux applications.
 
 The primary use-case for BubbleBox is running applications that you do not trust enough
-to give them full access to hour home directory, and in particular the secret keys stored there.
-In this regard it is similar to [firejail] and [bubblejail], but less powerful and in exchange hopefully easier to configure.
+to give them full access to your home directory, and in particular the secret keys stored there.
 BubbleBox is based on [bubblewrap] and [xdg-dbus-proxy] which do all of the heavy lifting.
 
+The goals of this project are similar to [firejail], but I found firejail's configuration to be extremely hard to maintain and debug.
+BubbleBox is meant for people that are comfortable editing its Python source code to adjust it to their needs;
+if you are looking for something with a more out-of-the-box experience, try [bubblejail].
+
 [firejail]: https://firejail.wordpress.com/
 [bubblejail]: https://github.com/igo95862/bubblejail
 [bubblewrap]: https://github.com/containers/bubblewrap
@@ -26,8 +29,7 @@ in a BubbleBox checkout with contents like this:
 from bubblebox import *
 
 bubblebox(
-  profiles.DEFAULT,
-  profiles.DESKTOP,
+  profiles.DESKTOP("gamejail"),
   dbus_proxy_flags("--own=com.steampowered.*"),
 
   home_access({
@@ -53,18 +55,21 @@ The `profiles.py` file contains some useful directives that are needed by most a
 - `profiles.DEFAULT` adds the basic flags to isolate the sandbox from the environment
   by unsharing all namespaces except for the network.
   This profile gives access to `/usr`, `/sys`, and `/etc` and also creates a
-  stub file system inside the sandbox that is basically always required. It
-  assumes a merged-usr setup, e.g. it will add `/bin` as a symlink to
-  `/usr/bin`. It also gives read-only access to some files in the home directory
-  that are often needed to make a basic shell work: `.bashrc`, `.bash_aliases`,
-  `.profile` and the `bin` directory.
-- `profiles.DESKTOP` is intended to make GUI applications work. It provides
-  access to DRI, X11, ALSA, Wayland, and PulseAudio. Furthermore, some GUI
-  configuration files (`.XCompose`, fontconfig, and default mime-type
-  associations) are made available to the sandbox. This also sets up the D-Bus
-  proxy and gives the application access to notifications, screen saver control,
-  status icons, and the flatpak portals (however, actually using these portals
-  is untested and would likely require further integration). Finally, it makes
+  stub file system inside the sandbox that is basically always required, such as
+  an empty folder to serve as XDG_RUNTIME_DIR. It assumes a merged-usr setup,
+  e.g. it will add `/bin` as a symlink to `/usr/bin`. It also gives read-only
+  access to some files in the home directory that are often needed to make a
+  basic shell work: `.bashrc`, `.bash_aliases`, `.profile` and the `bin`
+  directory.
+- `profiles.DESKTOP("name")` is intended to make GUI applications work. It
+  extends `DEFAULT` by providing access to DRI, X11, ALSA, Wayland, and
+  PulseAudio. Furthermore, some GUI configuration files (`.XCompose`,
+  fontconfig, and default mime-type associations) are made available to the
+  sandbox. The `"name"` is used to create an XDG_RUNTIME_DIR that will be shared
+  among all instances of this sandbox. This also sets up the D-Bus proxy and
+  gives the application access to notifications, screen saver control, status
+  icons, and the flatpak portals (however, actually using these portals is
+  untested and would likely require further integration). Finally, it makes
   clicking on links inside the sandbox work properly if your default browser is
   Firefox.
 
@@ -77,10 +82,7 @@ own sandboxes. Here are the key directives to use:
   to the home directory.
 - `bwrap_flags` allows passing flags directly to `bwrap`. This is rarely needed.
 - `dbus_proxy_flags` allows passing flags directly to `xdg-dbus-proxy`.
-  This is the typical way to provide access to given D-Bus names.
-- `shared_runtime_dir("name")` ensures that all instances of the sandbox with this
-  name have a shared XDG_RUNTIME_DIR. This is needed e.g. for VSCodium instances
-  to find each other. This must be declared *before* `profiles.DESKTOP`.
+  This is the typical way to provide access to additional D-Bus names.
 
 ## Source, License