## `default` realm

One realm is always selected to be the `default` realm.  The default realm
starts automatically when the system boots.  The `realms` utility can be used
to change which realm is the default realm. Switching the default realm changes 
the symlink `/realm/default.realm` to point to a different realm instance directory.

    citadel:~# realms default
    Default Realm: main

    citadel:~# realms default project
    [+] default realm changed from 'main' to 'project'

    citadel:~# realms default
    Default Realm: project

## `current` realm

If any realms are running, then one realm is always the `current` realm. The current
realm is a realm that is being monitored by the `citadel-desktopd` daemon.  This
daemon is responsible for safely copying application `.desktop` files from the running
realm instance to a temporary directory where they will be read by the GNOME desktop to
to display a menu of applications that can be launched.

Changing the `current` realm, changes the set of applications which are visible to 
gnome-shell to only the applications installed in this realm.  Also, any applications 
started by gnome-shell will run in the `current` realm.

    citadel:~# realms 
    Current Realm: main
    
## Realms base directory layout

The realms base directory is stored on the storage partition at `/storage/realms` and is bind mounted to `/realms` on the root filesystem for convenience.

    /realms
        config
        /Shared
        /skel
        /default.realm -> realm-main
        /realm-main
        /realm-project
        /realm-testing

### `/realms/config` file

This file is a template of the configuration file for individual realms.  When a new realm is created this file in copied into the new realm instance directory.  By modifying this file, the default configuration for new realm instances can be changed.

### `/realms/Shared` directory

This directory is bind mounted to `/home/user/Shared` of each running realm that has the option `use-shared-dir` enabled.  It's a convenient way to move files between different realms and between citadel and realms.

### `/realms/skel` directory

Files which are added to this directory will be copied into the home directory of any newly created realm.  The directory is copied as a tree of files and may contain subdirectories.  

### `/realms/default.realm`

A symlink which points to a realm instance directory of the default realm.  The default realm is the realm which starts when the system is booted.
 
### `/realms/realm-$name`

This is a realm instance directory, for a realm with $name as the realm name.

    /realm-main
        config
        /home
        /rootfs

 * `config`  : configuration file copied from `/realms/config`
 * `/home`   : directory mounted to `/home/user` in the realm, populated from `/realms/skel`
 * `/rootfs` : btrfs subvolume clone (snapshot) of an application image.
    

### Realm instance directory layout

    /realm-main
        config
        /home
        /rootfs