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](https://www.youtube.com/@typecraft_dev).

## Requirements

- A 64-bit PC (x86_64) that can run Arch Linux, with an internet connection.
- At least 100 GB for / (the root partition). CoreDesktop installs a lot of software, about 50 GB, and `update` needs at least 10 GB free.
- A fresh Arch Linux install with GNOME (see below). CoreDesktop changes system settings, so it's best not to run it on a machine you've already set up the way you like (see "What CoreDesktop changes on your system").
- A Federated Core is optional. Without one, everything works except what `configure core` sets up: your Core's apps, files, calendars and email, its Tailscale network, and backups.

## Installing Arch

1) Download the ISO for Arch from [this link](https://archlinux.org/download/). 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, set up Wi-Fi first. See "A Note About Networking in Arch" below.)

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 at maintaining compatibility with Nvidia and AMD options.
6) When asked what type of system you 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 tool `iwctl`. Here's [the great article](https://wiki.archlinux.org/title/Network_configuration/Wireless) on how to do this.

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. Then 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/Federated_Computer/coredesktop/raw/branch/main/install.sh | bash
```
3) Enter your password when asked, once at the start. Be patient: it takes a while.

   First it checks the machine. It stops if this isn't Arch, if you run it as root, if your user can't use sudo, or if there's no internet. It asks before going on if there's less than about 60 GB free, or if / isn't on btrfs (then there are no snapshots before updates, and only reinstalling Arch with btrfs changes that). If the login screen isn't GNOME's, or sound goes through PulseAudio, it offers to switch to GNOME's login screen and to PipeWire.

4) At the end, it offers to run `configure`, which connects to your Federated Core, sets up backups and signs you in to the AI agents (see "Configure" below). If the install brought in a newer kernel, it asks you to reboot first; run `configure` after the reboot.

5) If something fails, just run the command again. It skips what's already done.

6) Reboot (`sudo reboot now`) when you're done, so that Element can find the encryption keychain, among other things.

## 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 (3) main ways software is installed: pacman, AUR and Flathub. mise installs other languages if you want them (see Mise below).

### Pacman

Pacman installs software from the "packages.conf" file. It installs software such as neovim, tmux, Go, Rust, Docker, Tailscale, Element, LibreOffice, etc. If you'd like other tools, open an issue or send a pull request.

Federated Computer's own packages, such as Federated Calendar, come from the `[federated]` repository on Federated Computer's Gitea. CoreDesktop adds it to /etc/pacman.conf and trusts its signing key (fingerprint `6AB7C080D87C74BEE3925A026329376994F18B4E`), so they install and update like any other pacman package. Federated Calendar is installed alongside GNOME Calendar and can invite people to events on your Core's Nextcloud calendars.

### AUR

Yay is installed as is the way AUR packages are installed and maintained. Examples include the Helium Browser and Winboat. Helium is made the default browser once; you can choose another in Settings > Apps > Default Apps.

### Flathub

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

Flatpaks installed include: Chrome, Chromium, Firefox, Brave, Zen, Vivaldi (browsers), Signal, Telegram, Discord, Revolt, FluffyChat (messaging), Thunderbird and Evolution (email), VSCodium (VS Code without Microsoft's telemetry; for extensions only Microsoft's marketplace has, such as Remote-SSH, install VS Code with `flatpak install flathub com.visualstudio.code`), Obsidian and Logseq (notes), Apostrophe (markdown writer), Kdenlive (video editing), OBS (video recording), Audacity (audio editing), Inkscape (vector graphics), Scribus (page layout), Spotify, Jellyfin (media client), Zoom, Remmina and RustDesk (remote desktop), Postman, DBeaver and Beekeeper Studio (database clients), Alpaca and LM Studio (local AI), LocalSend (send files to other devices), Boxes (virtual machines), Impression (write ISOs to USB sticks), Trayscale (Tailscale), Warehouse (manage Flatpaks), Extension Manager (GNOME extensions), RetroArch and more. See [install-flatpaks.sh](install-flatpaks.sh) for the full list.

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

### Don't want something CoreDesktop installs?

Uninstall it, then add its name to ~/.config/coredesktop/skip-packages, one per line: the pacman package name (e.g. `libreoffice-fresh`) or the Flatpak's ID (e.g. `us.zoom.Zoom`, shown by `flatpak list`). Otherwise `update` installs it again. For example:

```
sudo flatpak uninstall us.zoom.Zoom
echo us.zoom.Zoom >> ~/.config/coredesktop/skip-packages
```

### Mise

Go, Rust, Node.js, Python, Bun and Zig come from pacman, and Arch keeps them current. [mise](https://mise.jdx.dev) is installed for everything else:

- **Other languages.** `configure languages` installs Ruby on Rails, or any tool mise knows (`mise registry` lists them), such as `java@21` or `deno@latest`. `update` keeps them up to date within the version you chose: `latest` moves to each new release, `21` stays on 21. To remove one, run `mise unuse -g <tool>`.
- **The version a project needs.** Put a mise.toml in the project, e.g. `mise use node@20` in its folder, and inside that folder `node` is version 20, while everywhere else it's pacman's.

### Development Tools

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

### Printing and Networking

The printing service (cups) is turned on. Network printers show up in GNOME Settings and browsers on their own, but often not in the GTK print dialog ("Print using system dialog...") until they're added as printers on this computer. `configure printers` does that (see Configure).

mDNS is installed and enabled so you 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, keys only: see System defaults), 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/](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, and Intel's video decoding driver, so videos and calls don't decode on the CPU (AMD's comes with Mesa). 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.
- You log in to this machine over SSH with a key, not a password, so nobody on the same network can try to guess your password. Put your public key in ~/.ssh/authorized_keys on this machine (`ssh-copy-id` does this from the other machine). To allow passwords again, delete /etc/ssh/sshd_config.d/10-coredesktop-keys-only.conf and run `sudo systemctl reload sshd`. Machines installed earlier, where someone has logged in over SSH with a password, keep accepting passwords until you run `bash ~/.local/share/coredesktop/system/sshd.sh`.
- ssh uses Bitwarden's SSH agent while Bitwarden is running it (turn it on in Bitwarden's settings), and GNOME's otherwise. A terminal opened before Bitwarden started uses GNOME's; open a new one.
- WinBoat's Windows container doesn't start at boot: install and every update turn off WinBoat's "Auto Start Container" (in ~/.winboat/docker-compose.yml and on the container), since Windows would otherwise hold 8 GB of memory and 4 cores from boot whether you use it or not. It still starts when you open WinBoat.

### What CoreDesktop changes on your system

Besides installing software, CoreDesktop changes these settings. They're listed so you know what you're running, and so you can undo them (see "Uninstalling").

- **/etc/pacman.conf**: adds the `[federated]` repository and trusts its signing key (see Pacman above).
- **Mirrors**: reflector rewrites /etc/pacman.d/mirrorlist once a week with fast HTTPS mirrors that synced with Arch in the last 12 hours, using /etc/xdg/reflector/reflector.conf. To choose your own mirrors, delete that file's first (CoreDesktop) line and edit the rest; to stop CoreDesktop changing your mirrors at all, add `reflector` to ~/.config/coredesktop/skip-packages.
- **SSH**: sshd is on, with key login only (/etc/ssh/sshd_config.d/10-coredesktop-keys-only.conf). The SSH client keepalives are in /etc/ssh/ssh_config.d/20-coredesktop-keepalive.conf.
- **Firewall**: ufw is on, with the rules under Firewall above, and ufw-docker's rules in /etc/ufw/after.rules.
- **Login lockout**: deny and unlock_time in /etc/security/faillock.conf.
- **systemd**: a 10-second stop timeout (/etc/systemd/system.conf.d/ and /etc/systemd/user.conf.d/10-coredesktop-timeout.conf), systemd-oomd for apps (/etc/systemd/user/app.slice.d/10-coredesktop-oomd.conf), and NetworkManager-wait-online is masked.
- **/etc/security/pam_env.conf**: a PATH line, so SSH commands find ~/.local/bin and mise.
- **mDNS**: Avahi is on, nss-mdns is added to /etc/nsswitch.conf, and SSH is advertised in /etc/avahi/services/ssh.service.
- **Services turned on**: Avahi, Bluetooth, CUPS (printing), fwupd, GDM, NetworkManager, reflector (weekly), sshd, Docker, Tailscale, ufw and systemd-oomd. Your user is added to the docker group.
- **Snapper** (btrfs only): a config for / in /etc/snapper/configs/root.
- **NVIDIA** (only if it installs the driver): /etc/mkinitcpio.conf.d/nvidia.conf and NVIDIA's suspend services.
- **Your home folder**: lines in ~/.bashrc (CoreDesktop's shell setup, ~/.local/bin on PATH, the Bitwarden SSH agent), the commands in ~/.local/bin (update, refresh, sibling, version, configure, audit), GNOME extensions and their settings, Claude Code's ~/.claude/settings.json if you had none, a user timer that checks for updates, and a user service that pauses your Core's email if its password stops working (see Configure).
- **configure** adds more, only for what you set up: your Nextcloud files mount and network storage in /etc/fstab (SMB passwords in /etc/coredesktop/smb, SFTP mounts as user services named coredesktop-sftp-*), printers in CUPS, GNOME Online Accounts, passwords in your GNOME keyring, and the backup timer.

## 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)
- switches to up-to-date mirrors first if yours is more than a day behind Arch, as it would otherwise miss new packages without saying so
- updates the Arch keyring, then Arch and GNOME, then AUR packages, Flatpaks, the languages you installed with mise, the pipx apps CoreDesktop installs, 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
- lists packages that were installed only because something else needed them, and are no longer needed by anything, and asks before removing them. Packages CoreDesktop installs are never on this list. To keep one you use directly off the list, 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](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, 7.2.13 is available (run update)
Video driver Mesa 26.2.6
Last update  2026-10-22 13:43
```

The kernel and video driver (NVIDIA's if it's installed, otherwise Mesa, which drives Intel and AMD graphics) come from Arch, so they're shown separately. "version" tells you if Arch has a newer kernel or video driver, or if a newer version of CoreDesktop is available; "update" installs them. If a newer kernel is waiting for a reboot, it says that too. It can only see what your package mirror has, so if the mirror is more than a day behind Arch it warns you; "update" then switches to up-to-date mirrors.

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](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 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, 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. You can add more Cores: run `configure core` again and choose "Add a Core". Each gets its own Superpanel, Nextcloud, email and files; Element, Tailscale and backups use your main Core (the first one, unless you choose another). "Remove a Core" takes it off this computer and revokes its app password, and leaves everything on the Core itself as it is. If you change your Core password (e.g. in Superpanel), run `configure core` and choose "Your Core password changed": email keeps your Core password, so it saves the new one there, and it signs in to Nextcloud with it, which turns the app passwords for Nextcloud, files and backups back on (Nextcloud turns them off when your password changes), then checks each of them. To check that a Core still works from this computer, run `configure core` and choose "Test a Core": it signs in to Superpanel, Nextcloud, email, your files, Element's Matrix server and backups the way this computer does, says which work, and offers to fix those that don't (asking for your Core password if a fix needs it, e.g. to make a new app password for one that was revoked), then tests again.
- **Your Core's Tailscale network.** Joins this computer to it through headscale.example.com, so you can reach your other machines on it. Set up your Core first. You sign in through a link it shows you; if this computer is on another Tailscale network, it moves it to your Core's. To leave your Core's network, run `configure tailscale` again.
- **Daily backups of your home folder** to your Nextcloud files, in a .backup-{machine name} folder, with restic. Set up your Core first. The backup is encrypted with a passphrase that `configure` shows you once: save it somewhere other than this computer, such as Bitwarden. It keeps 7 daily, 4 weekly and 6 monthly backups, and leaves out caches, things that can be reinstalled, and WinBoat's Windows VM (~/winboat). To leave out more, list paths in ~/.config/coredesktop/backup-exclude, one per line. restic reaches Nextcloud directly through rclone with its own Nextcloud app password, so the backup doesn't depend on the /mnt mount. See "Restoring from a backup" below. To turn backups off, run `configure backup` again; it also offers to delete the backups from your Nextcloud files (they go to Nextcloud's trash bin).
- **Tally for Plausible**, if your main Core runs Plausible Analytics: it's pointed at plausible.example.com.
- Signing in to Claude Code, opencode and Hermes Agent and choosing their model providers.
- **Languages** to install with mise, such as Ruby on Rails (see Mise above).
- **Printers** on your network. It lists the printers it finds, whether they're reached directly or shared by another computer, and adds the ones you choose as printers on this computer, without drivers (IPP Everywhere), so they're in every print dialog. A printer another computer shares that can also be reached directly is marked, and not chosen unless you pick it, so printing doesn't depend on that computer being on. Printers already added, e.g. in GNOME Settings, are left alone. To choose without being asked, set a default printer or try it first, run `~/.local/share/coredesktop/system/setup-printers.sh --help`.
- **Network storage**: shared folders from other machines on your network, mounted in /mnt and added to the Files sidebar. It finds SMB servers (Windows, Samba and NAS boxes, and Macs with File Sharing on) and machines you can ssh to, or you enter an address (`smb://nas.local/files`, `sftp://me@server.local/srv/data`). An SMB share is in /etc/fstab and mounts the first time you open its folder, so a server that's off doesn't hold anything up; its password is kept in /etc/coredesktop/smb, readable only by root. An SFTP folder is mounted by sshfs as you, at login, with the SSH keys in your Bitwarden or GNOME SSH agent, so the server has to accept one of them (it can't ask for a password). Agents in the sandbox can read these folders, and change one only if you start the agent in it. "Remove one" unmounts it and takes it back out.
- **Agent sandbox**, if WinBoat is set up: the sandbox hides WinBoat's settings (~/.winboat) from agents, since they include your Windows password. To let agents read them, e.g. to have one help with WinBoat, run `configure sandbox` and switch it; switch it again to hide them. This only covers the sandboxed agents (opencode, Hermes, Cline), not Claude Code's own sandbox. Your SSH keys, password stores and the rest stay hidden either way.
- **AI servers** on your network, such as Ollama on a Mac. It finds the machines on your network over mDNS and asks each one on the ports LLM servers use (11434 Ollama, 1234 LM Studio, 8080 llama.cpp, 8000 vLLM), since LLM servers don't announce themselves; or you enter a server's address. For the server you choose, it lets the sandboxed agents reach it (that port only), adds it to opencode with its models, offers to make it Hermes' model, and lets the commands Claude Code runs reach it too. Claude Code itself keeps using Anthropic's models. A server has to accept connections from other machines: in Ollama's settings, turn on "Expose Ollama to the network"; in LM Studio, "Serve on Local Network". "Remove a server" takes it back out of all of them.

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

### When your Core password changes

Your email in Online Accounts keeps your Core password, so after you change it (e.g. in Superpanel), the mail server starts refusing the old one. GNOME tries it again each time your network changes, and Evolution each time it fetches mail, and after a few wrong passwords the mail server blocks this computer for a while.

So CoreDesktop watches for it, without ever trying the password on the mail server. When your password changes, Nextcloud stops accepting the app passwords this computer uses, and Online Accounts notices. CoreDesktop then checks the password your email has with Nextcloud, once. If Nextcloud says it's wrong, CoreDesktop pauses your email: this computer stops trying the old password, and you get a notification. Click it, choose "Your Core password changed" and enter your new password; that ends the pause. Or remove the Core, or just the email account in Settings > Online Accounts. `configure core` > "Test a Core" shows a paused email too, and checks email's password with Nextcloud before trying it on the mail server.

This needs your Core's Nextcloud in Online Accounts, which `configure core` sets up along with email.

### Restoring from a backup

To see the backups and get files back:

```
source ~/.local/share/coredesktop/system/backup-env.sh
restic snapshots
restic restore latest --target ~/restored --include ~/Documents
```

On a new computer, run `configure core` and `configure backup` first. Then name the old computer's folder, and restic asks for the passphrase you saved:

```
source ~/.local/share/coredesktop/system/backup-env.sh .backup-{old machine name}
restic snapshots
```

`systemctl --user list-timers coredesktop-backup.timer` shows when the next backup runs, and `journalctl --user -u coredesktop-backup` shows how the last ones went.

## Sandboxed AI agents

CoreDesktop installs the AI coding agents opencode, Hermes Agent, Cline Desktop 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, Flatpak apps' data (browsers, Signal, Telegram and the rest), your Nextcloud password, WinBoat's settings (which hold your Windows password), 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. Hermes talks to its gateway through a local socket, so its sandbox allows local sockets but hides the ones that would let it act outside the sandbox: your session's D-Bus and SSH agent, Docker, Tailscale, X11, tmux and browsers. Claude Code uses its own built-in sandbox for every command it runs (see `/sandbox` inside Claude).

Cline Desktop, opened from the app menu, runs in the sandbox with your projects in `~/Projects`: it can change files there, and open projects elsewhere only to read them. It also reaches Cline's own servers (cline.bot). It draws through your Wayland session but can't reach the session's other sockets, so it can't use D-Bus, the keyring or the GPU (it draws without the GPU). To run it without the sandbox, type `unsandboxed cline-desktop`.

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):

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

A server on your local network, such as an LLM server, is added the same way, with its port: `"llm.local:11434"` (`configure ai-servers` does this for you). Use its `.local` name or its IP address.

The sandbox is Anthropic's [sandbox runtime](https://github.com/anthropics/sandbox-runtime), which uses bubblewrap and socat. The default rules are in [sandbox/config/](sandbox/config/).

## Open ports

`audit` shows the network ports open on this computer. For each one it shows who can connect to it, after the firewall: only this computer, your Tailscale network, or your LAN. It also shows which service opened the port and why.

You can stop a service from there, which also keeps it from starting at boot, or start a stopped one again. `update` leaves the services you stop off. audit won't stop the ones the desktop, Files or the network need. Run it with sudo rights so it can name the services run by root; `audit --list` only shows the ports.

## mDNS Networking

mDNS lets you reach other machines on your LAN as "machine.local", e.g. `ssh machine.local`. When systemd-resolved is enabled, the installer sets it up with [fixmdns.sh](fixmdns.sh): it turns on Avahi and adds nss-mdns to /etc/nsswitch.conf ahead of systemd-resolved, so the two don't conflict. On a machine without systemd-resolved, run `bash ~/.local/share/coredesktop/fixmdns.sh` yourself. See the [Arch wiki](https://wiki.archlinux.org/title/Avahi#Hostname_resolution) for more.

## Uninstalling

CoreDesktop doesn't have an uninstaller, but you can undo it by hand. If you set up a Core, do this first, while `configure` is still installed, so your app passwords are revoked: `configure backup` (turn backups off), `configure tailscale` (leave the network), then `configure core` and "Remove a Core" for each Core.

Then remove CoreDesktop's own files:

```
systemctl --user disable --now coredesktop-update-check.timer coredesktop-backup.timer coredesktop-email-watch.service
rm -f ~/.config/systemd/user/coredesktop-*
rm -f ~/.local/bin/{update,refresh,sibling,version,configure,audit}
rm -rf ~/.local/share/coredesktop ~/.local/share/siblings ~/.local/state/coredesktop ~/.config/coredesktop
```

Delete the CoreDesktop lines from ~/.bashrc, and undo the system settings you don't want from "What CoreDesktop changes on your system". The software stays installed: remove what you don't want with `sudo pacman -Rns <package>` and `flatpak uninstall <app>`.

## 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.

Found a bug or have an idea? [Open an issue](https://gitea.federated.computer/Federated_Computer/coredesktop/issues).

Every push is checked with [shellcheck](https://www.shellcheck.net) (settings in .shellcheckrc). Before sending a PR, run `make check`: it runs shellcheck (`make lint`) and the [bats](https://github.com/bats-core/bats-core) tests in tests/ (`make test`).

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](https://music.youtube.com/watch?v=y-5o2f9wzmw&si=_z9kcKHRwj-KTs7w).