Using Spaces
Creating a Space
Spaces is designed to be simple to use. To use Spaces,
open a terminal and type arch, fedora, ubuntu, or kali.
These commands alias to:
spaces enter <space> # arch/fedora/ubuntu/kali
When running spaces enter if the Space is not installed,
a dialog will open for you to set it up. To re-enter this
dialog afterwards to recreate the space, type:
spaces create <space>
Typing spaces create after installing allows you to recreate the space
while keeping your Space's home data.
Spaces will guide you through a permissions dialog and finally have you select between OS versions (for Ubuntu, Fedora) and customizations (yay, Shelly for Arch).
There are two permissions presets: basic for basic applications
that do not modify system settings, and development which allows
you to install VPNs, docker, VMs, and get raw access to devices.
You can instead choose custom, and fine tune every single permission.
By default, your ~/Downloads directory is mounted in Spaces,
and in development Spaces ~/Projects is added for you to store your
development code. Development Spaces also forward your GPG, SSH, .gitconfig
(for your Git name and email), .ssh/config for your SSH hosts, .bashrc,
and .zshrc for your terminal customizations. In custom mode, you can
mount any visible home directory you wish.
The rest of your files, your SSH keys and your GPG keys remain private, so they cannot be exfiltrated, and your keys are additionally protected by SELinux. By default, Anatase sets up your SSH agent when you log in with the id_rsa/id_ed25519 keys. You will need to add the rest of your keys to your SSH agent manually, although it is recommended to only use a single key, which is the one you also enroll in services like Github.
Using Spaces
You can open a Space using the commands ubuntu, fedora, arch, and kali
or the underlying spaces enter <space> command.
Once in a Space, you can run any command you are used to in the respective distribution, follow documentation about that distribution verbatim, and have it work the same way as that distribution. Any deviations should be reported as bugs in the Anatase issue tracker or Discord.
For development, install the IDE of your choice in a Space. For example, you can follow the Linux instructions of VS Code to install it. Installing your IDE in a Space allows it to natively integrate its terminals, debugger and run commands into that distribution. You can also install IDEs into any Spaces you use for development (e.g., both Fedora and Ubuntu). Please do not install flatpak versions of IDEs.
Spaces automatically exports the desktop shortcuts of any applications you install to your main desktop environment, and you can choose to select any of them as default apps as well.
A Space is installed with the minimal packages required for desktop
integration to function. However, packages are not perfect, and sometimes
miss dependencies. For example, in Ubuntu, installing NordVPN requires
libgtk-3-0, and libgles2, which are not included in its dependencies.
When you encounter a missing dependency, take note of it and create a bug
report, so we can begin collecting them. You can run the package command
in a terminal to infer missing packages from its errors (e.g.,
nordvpn-gui for NordVPN) and install missing dependencies until it runs.
Modifying permissions
If you want to change Space permissions after creating it, you can run:
spaces configure <space>
The permissions dialog will open again and you can make arbitrary changes. On submission of the dialog, your Space will shutdown and when you launch it again, your changes will be applied.
Deleting a Space
If a Space is taking up too much Space, you can run:
spaces delete <space>
Starting and stopping Spaces
Spaces are implemended as normal system systemd services with the following
syntax: spaces@<space>. Spaces also provides a --user service variant
thats enabled by default for your user once you create a Space. This way,
a Space only starts when you log in to ensure that your files are mounted
when your services start. All the user variant does is start the system
service. In addition, spaces enter <space> and its aliases autostart
the Space if it is not already started.
Here are some commands you can use with Spaces:
# Enable the space to start on boot
# This way, Tailscale works before you log in.
sudo systemctl enable --now spaces@ubuntu
# Undo the previous enable
sudo systemctl disable --now spaces@ubuntu
# Enable your user logging in starting a space (default)
systemctl --user enable --now spaces@ubuntu
# Disable your space starting when your user logs in
systemctl --user disable --now spaces@ubuntu
# Stop your space
sudo systemctl stop spaces@ubuntu
# Start your space manually
sudo systemctl start spaces@ubuntu
# Restart your space
sudo systemctl restart spaces@ubuntu
# View the systemd journal of your space
journalctl -u spaces@ubuntu
Deleting the Spaces home files
Spaces uses a separate home directory to store system configuration that is particular to your Spaces. This way, application configuration is kept separate from your host data preventing conflicts and you can be in control of the folders that are exposed in the Space.
By default, when recreating or deleting Spaces, your Space home data is
kept. You should never need to purge your Space home data typically.
Only do it if there is stale configuration in home you want to purge as
well. To delete the Space's home data, you can append --purge to
spaces create/delete.
# Create or recreate a space with a fresh home directory
spaces create --purge <space>
# Delete a space with its home data and permissions configuration
spaces delete --purge <space>
Your host home data is never modified when running Spaces commands.
Using GPG keys in Spaces
Using GPG keys is a bit unintuitive. You first need to create a GPG key using a host terminal. Then, you can export it as follows.
First, you need to list your GPG keys and get their IDs. Let's use mine as an example.
$ gpg --list-secret-keys
sec ed25519 2024-07-31 [SC]
4DBB5595849C1C4EF1117688EF34000BBBE32D2A
ssb cv25519 2024-07-31 [E]
This is not private information, and as you note, most commits in Anatase are signed by the key above.
Once you have your key ID, in this case 4DBB5595849C1C4EF1117688EF34000BBBE32D2A,
you export the public version as an armor file, and reimport it in the
Space you want. For example, Fedora:
gpg --armor --export 4DBB5595849C1C4EF1117688EF34000BBBE32D2A > ~/Projects/public.asc
fedora
gpg --import ~/Projects/public.asc
Now, you can run the same command inside the Space to verify GPG forwarding works.
$ gpg --list-secret-keys
[keyboxd]
---------
sec ed25519 2024-07-31 [SC]
4DBB5595849C1C4EF1117688EF34000BBBE32D2A
ssb cv25519 2024-07-31 [E]
You can add the following to ~/.gitconfig in your host's home folder to
force GPG signing for your commits (~/.gitconfig is forwarded):
[commit]
gpgsign = true