coredesktop/README.md

Federated CoreDesktop

Introduction

This is not a distribution. Most of the heavy-lifting is accomplished by Arch Linux and to that distribution we send much gratitude. Arch Linux is a wonderful toolbox allowing a Linux enthusiast to build real solutions for all sorts of use cases! It allows us to "get on with building" unlike some of the other distributions where we are forced to wait for upstream changes and fixes. Just our opinion!

CoreDesktop is simply some scripts to take an install of Arch Linux and the Gnome desktop environment and add some Gnome extensions so that you get a great tiling environment that can be 100% controlled from the keyboard. This combination is especially good for ultrawide monitors where a power of 3 grid is better than a power of 2. And, with Gnome, you get a nice mouse-capable desktop, too.

Additionally, CoreDesktop includes a lot of useful software mostly for work at Federated Computer but you may find it useful for you, too. You may want to suggest some missing titles or services. Please do! Or send in a PR.

These scripts are based on the initial work of Typecraft.

Installing Arch

1. Download the ISO for Arch from this link. You may need to scroll down to find the download links.
2. Write the ISO file to a USB stick.
3. Boot from the Arch ISO USB stick. When the ISO has booted, type archinstall to get to the simple installer.

(Note: if you're on a laptop and/or don't have a wired internet connection, you'll need to set up the wifi card, etc. Here's the great article how to do this. But it really boils down to five steps: at the prompt type "iwctl"; then "device list"; then "station wlan0 scan" where "wlan0" is your wifi device; then "station wlan0 get-networks"; then "station wlan0 connect SSID" where you replace "SSID" with the name of your network.)

4. You will go through the different options. Mostly choose the defaults.
5. Video cards: IF YOU HAVE AN NVIDIA GPU, CHOOSE THE PROPRIETARY NVIDIA OPTION. Choose the AMD option for AMD cards. Just works better. We've found Arch is very good maintaining compatability with Nvidia and AMD options.
6. When asked what type of system your want, the correct choice is "desktop" and the correct desktop environment is "Gnome".
7. For sound, "pipewire" is strongly recommended for the sound system choice during install. This is known to work really well with Jitsi, Element, and the other Federated Core SaaS applications, if you're using those. This may no longer be required in the newest installations of Arch Linux.
8. Reboot the system and log in. You should have a working Arch system at this point but without the Coredesktop configurations.

You will likely screw up the installation of Arch the first or second time. Don't despair. Keep trying! The logic of the install will ultimately become clear and, frankly, efficient for you. And, besides, you get to know the base Arch install better and better over time.

(A Note About Networking in Arch)

You'll need a connection to the internet to successfully install Arch.

If you have a wired connection, then your network should "just work" and you can use that to configure your Arch network installation. But if you do not have a wired connection and you have a wifi chip installed in your computer, before installing Arch you'll want to set up the wifi network. You can do that using the too iwctl.

Type iwctl and that will put you into the utility iwd.

To list the wireless adapters type: device list. If your wireless device is "wlan0" (for example) you next type: station wlan0 scan to put the wireless chip into scan mode then station wlan0 get-networks to find the wireless networks available. The join your wireless network with the command station wlan0 connect SSID where SSID is the wireless network name. You can test your network with a ping to some server, etc.

When you have the wireless network working (check by doing "ping google.com"), then you can proceed to install Arch.

Installing Federated CoreDesktop

When Arch and Gnome have been successfully installed, you log in to the system then...

1. Open the "Web" browser then navigate to https://gitea.federated.computer and click "Explore" and "CoreDesktop". Scroll down and you'll find the command to enter to kick off installation.

2. Open a terminal, then enter the following command (you copied it from Gitea in step #1):

wget -qO- https://gitea.federated.computer/david/coredesktop/raw/branch/main/install.sh | bash

3. You'll have to enter your password a couple times and click to install a gnome extension. Be patient. When the installation finishes, reboot (command: 'sudo reboot now') so that Element can find the encryption keychain.

4. If something fails, just run the script again. The typical fails are not entering the password in time, or failing to click on a Gnome extension dialog. Just re-run the script and it will get through everything. You'll know you're done when the script asks you to reboot your machine.

Notes about what is installed

You will end up with a Gnome system with a three-tile set up (again, great for widescreens). If you want to change the tiling, the icon in the top right of your screen allows you to change your tiling setup however you want. Using the super key (windows key or equivalent) plus the arrow keys, you can move windows around the screen.

The scripts are installed in ~/.local/share/coredesktop/

The scripts install lots of useful software. There are (4) main ways software is installed: pacman, AUR, Flathub, and mise.

Pacman

Pacman installs software from the "packages.conf" file. It installs software such as nice versions of neovim, tmux, VS Codium (VS Code without the M$ surveillance), Go, etc. Tell me if you want other tools or submit a pull request.

AUR

Yay is installed as is the way AUR packages are installed and maintained. Examples include the Helium Browser and Winboat.

Flathub

The file "install-flatpaks.sh" file for Flatpaks.

Flatpaks installed: Chrome, Chromium, Firefox, Brave, Zen, Vivaldi, Warehouse (manage Flatpaks), Embellish (manage fonts), Revolt (Discord clone), Impression (burn ISOs to usb sticks), Logseq (note taking), Apostrophe (markdown writer), Signal (messaging), Thunderbird (email), Trayscale (tailnet), VS Code (IDE), Telegram (messaging), LibbreOffice, Extension Manager (for Gnome extensions), Nextcloud client, Kdenlive (video editing), OBS (video recording), Discord (messaging), Spotify (music), VLC (video watching), Obsidian (note taking), qBittorent, Bitwarden desktop, Inkscape (postscript editor), Zoom, Audacity (audio editing), Remmina (remote desktop), Postman, Alpaca (work with AI), DBeaver (database client), Jellyfin Media (client), Zen (interesting browser project), Localsend (send stuff to other devices easily), Boxes (virtual machines) and much else.

If you want to install more software from Flathub, simple visit https://flathub.org.

Mise

Ruby and Rails are installed using Mise from the file "install-mise-ruby-rails.sh".

Development Tools

Lots of development tools including herdr, neovim, tmux, go, hugo, python, rust, rails, ruby, docker and docker compose, etc. Three terminals: console, kitty, ghostty.

Printing and Networking

The printing service (cups) is turned on. This may need more work to "just work" with other "coredesktop" machines.

mDNS is installed and enabled so the your can find and SSH to your machine on your LAN using {machinename}.local.

Firewall

The ufw firewall is on. It blocks incoming connections except SSH (22), mDNS (5353/udp), LocalSend (53317) and anything arriving over Tailscale. ufw-docker is installed too, because ports published by Docker containers otherwise get around ufw. To let a container's port through, use sudo ufw-docker allow {container} {port}. To open a port for something else, e.g. a dev server you want to reach from another machine, use sudo ufw allow {port}/tcp. sudo ufw status shows the current rules.

Shell

Your ~/.bashrc sources ~/.local/share/coredesktop/shell/bashrc, which sets up the starship prompt, zoxide (z {part of a path} jumps to a directory you've used before), fzf key bindings (Ctrl-R searches history, Ctrl-T inserts a file path), eza for ls/ll/la/lt, and the aliases and functions in shell/. If you already have ~/.config/starship.toml, your prompt config is used. Anything you add to ~/.bashrc after the CoreDesktop line overrides it.

Snapshots

If / is btrfs (the archinstall default), Snapper takes a snapshot of / before every update and keeps the last 5. /home is a separate subvolume and isn't included, so rolling back never touches your files. sudo snapper -c root list shows the snapshots.

These snapshots can't be picked from the boot menu. To roll back after a bad update, boot the Arch ISO and replace the @ subvolume with a snapshot:

mount -o subvolid=5 /dev/{root partition} /mnt
mv /mnt/@ /mnt/@.broken
btrfs subvolume snapshot /mnt/@.snapshots/{number}/snapshot /mnt/@
reboot

If the disk is encrypted, open it with cryptsetup open first and mount the opened device. Once the system works again, free the space the broken root used:

sudo mount -o subvolid=5 /dev/{root partition} /mnt
sudo btrfs subvolume delete /mnt/@.broken
sudo umount /mnt

GPU drivers

The installer adds the Vulkan driver for Intel and AMD GPUs. If there's an NVIDIA GPU and archinstall's proprietary driver wasn't chosen, it installs NVIDIA's driver: the open kernel modules for GTX 16xx / RTX 20xx and newer, or the 580xx legacy driver for older cards back to the GTX 900 series. Reboot afterwards.

System defaults

• SSH connections notice a dropped link within a minute instead of hanging (override per host in ~/.ssh/config).
• Logins allow 10 wrong passwords before locking the account for 2 minutes (Arch's default is 3 tries, then 10 minutes).
• Shutdown waits at most 10 seconds for a service that won't stop, instead of 90.
• If memory runs out, systemd-oomd closes the app causing it instead of the whole desktop freezing.
• Boot no longer waits for the network.
• Commands run over SSH (ssh {machine} {command}) can find tools in ~/.local/bin and mise.

Keep your System Up-to-date

From time-to-time, you'll want to update your system. Hopefully you'll do this more than once-a-month.

To update the system type into the terminal:

update

The script pulls the latest CoreDesktop, then runs each step in ~/.local/share/coredesktop/updates.d/ in order. Among other things it:

• stops if there's less than 10 GiB free on / (run UPDATE_FORCE=1 update to skip the check)
• snapshots / first, if Snapper is set up (see Snapshots above)
• updates the Arch keyring, then Arch and GNOME, then AUR packages, Flatpaks, Ruby, GNOME extensions and firmware
• warns you not to reboot if the initramfs failed to rebuild
• runs any one-time migrations, the way existing machines pick up new CoreDesktop setup
• removes packages that were installed only because something else needed them, and are no longer needed by anything. It lists what it removed. To stop a package you use directly from being removed, run sudo pacman -D --asexplicit <package>

If a step fails, the other steps still run, and the failed ones are listed at the end.

It is a good idea to reboot after an update especially if you see you have a new Linux kernel installed (and that happens frequently enough for Arch).

Note: sometimes, for whatever reason, the update barfs. Take a look at https://archlinux.org in the "Latest News" section for fixes.

Refresh your system

If you want to pull down "new" additions to Coredesktop, run in the terminal:

refresh

This will download the latest repo and run through the original installation script adding any "new" applications or services. You should run "update" after running "refresh".

Which version am I running?

CoreDesktop is a rolling release, so its version is the date of the latest CoreDesktop change on your machine, followed by that change's id. To see it, run in the terminal:

version

CoreDesktop  2026.10.22 (c5f0651)
Kernel       7.2.11-arch1-1
Last update  2026-10-22 13:43

The kernel comes from Arch, so it's shown separately. If a newer kernel is waiting for a reboot, "version" says so. It also tells you if a newer version of CoreDesktop is available.

You don't have to check by hand: a few minutes after you log in, and every few hours after that, CoreDesktop checks for a new version and shows a notification if there is one. Click it to run "update" in a terminal, or dismiss it. Once dismissed, you won't be notified again until there's an even newer version.

Sibling projects

A sibling project is another git repository that builds on CoreDesktop. To install one, run in the terminal:

sibling

It asks for the repository's git URL, clones it into ~/.local/share/siblings/, runs the project's "install.sh" (if it has one), and confirms the install. After that, every "update" pulls the latest version of each sibling and runs its "update.sh" (if it has one).

Use "sibling list" to see what's installed and "sibling remove {name}" to uninstall one.

To make your own repository work as a sibling project, see skills/sibling-project-format.md.

Configure

Some of what CoreDesktop installs needs you to sign in or make a choice before you can use it. To see what's set up and set up the rest, run in the terminal:

configure

It covers:

• Your Federated Computer Core. Give it your Superpanel's address (e.g. https://superpanel.example.com), your Core email, name and password, and it adds Superpanel to your applications, joins this computer to your Core's Tailscale network, adds your Nextcloud (calendar, contacts and files) and email to GNOME's Online Accounts, and mounts your Nextcloud files at /mnt/example.com ("example.com" in the Files sidebar), and points Element at your Core's Matrix server. For Nextcloud and the files it creates a Nextcloud app password, which you can revoke in Nextcloud under Settings > Security.
• Signing in to Claude Code, opencode and Hermes Agent and choosing their model providers.

To set up one thing, name it, e.g. configure hermes; configure --list shows the names.

Sandboxed AI agents

CoreDesktop installs the AI coding agents opencode, Hermes Agent and Claude Code, and runs them in a sandbox. In the sandbox, an agent:

• can change files only in the directory you start it from (plus its own settings and a few package caches), so start it from a project directory
• can't read your SSH keys, password stores, browser profiles, cloud and Git credentials, or the other agents' logins
• can reach only AI providers and common developer sites: GitHub, Gitea, npm, PyPI, crates.io, RubyGems, the Go module proxy and archlinux.org

Typing opencode, hermes or hermes-agent runs it in the sandbox. To run one without it, type unsandboxed opencode. Hermes' gateway, the background service that lets you talk to Hermes through Matrix and other messaging apps, runs in the sandbox too, and can reach the Matrix server in Hermes' settings. For other messaging services, add their domains as shown below. Claude Code uses its own built-in sandbox for every command it runs (see /sandbox inside Claude).

Before using an agent the first time, sign in and choose a model provider with configure (see below).

If an agent needs a site or folder the sandbox blocks, add it in ~/.config/coredesktop/sandbox/base.json (for every agent) or ~/.config/coredesktop/sandbox/opencode.json (for one agent):

{
  "network": { "allowedDomains": ["docs.example.com"] },
  "filesystem": { "allowWrite": ["~/notes"] }
}

The sandbox is Anthropic's sandbox runtime, which uses bubblewrap and socat. The default rules are in sandbox/config/.

mDNS Networking

If you want to use mDNS networking on your LAN (the ability to log in to other local machines using the format "machine.local"), then you should replace /etc/nsswitch.conf with the one in this repository and add /etc/mdns.allow. These two files are formatted to avoid any conflicts with systemd-resolved that may cause nss-mdns not to work. See: https://wiki.archlinux.org/title/Avahi#Hostname_resolution (section 4.2) for more information.

Contributing

This whole "project" is licensed under the MIT License. Want to help make CoreDesktop better? Awesome! We welcome any and all help. Just contribute a PR and we're off to a better CoreDesktop.

Changes to install.sh only reach new installs. If existing machines need the change too, also add a migration: a script named migrations/$(date +%s).sh that update runs once on each machine. It may also run on fresh installs, so make it safe to repeat.

Bonus

Bonus: here's a nice song to listen to while you're installing.