webcoredesktop/content/system.md

---
title: "System"
description: "How Federated CoreDesktop sets up your system: tiling, the shell, SSH, the firewall, Snapper snapshots, GPU drivers, mDNS, printing and sensible defaults, every setting it changes, and how to undo it."
sections:
  - type: hero
    compact: true
    eyebrow: "Sensible defaults, all of them explained"
    title: "What CoreDesktop sets up for you."
    subhead: "A flexible tiling GNOME desktop, a better shell, a firewall that's actually on, snapshots before every update, and a handful of small fixes that add up."
    tiles: ["Tiling", "Firewall", "Snapshots"]

  - type: text
    kicker: "Tiling"
    headline: "Flexible tiling, all from the keyboard."
    body: |
      You end up with a [GNOME](https://www.gnome.org) system with a flexible tiling setup that works on any screen and really shines on widescreens. Hold <kbd>Super</kbd> (the Windows key or equivalent) and use the arrow keys to move windows around the screen.

      To change the tiling, use the icon in the top right of your screen. You can set it up however you want. [Using the desktop](/desktop/#windows) shows how, along with workspaces, notifications and screenshots.

  - type: text
    kicker: "Shell"
    headline: "A better terminal, without the setup."
    body: |
      Your `~/.bashrc` sources `~/.local/share/coredesktop/shell/bashrc`, which sets up:

      - the **starship** prompt (your own `~/.config/starship.toml` wins if you have one)
      - **zoxide**: `z {part of a path}` jumps to a directory you've used before
      - **fzf** key bindings: <kbd>Ctrl</kbd>+<kbd>R</kbd> searches history, <kbd>Ctrl</kbd>+<kbd>T</kbd> inserts a file path
      - **eza** for `ls`, `ll`, `la` and `lt`
      - the aliases and functions in [shell/](https://gitea.federated.computer/Federated_Computer/coredesktop/src/branch/main/shell)

      Anything you add to `~/.bashrc` after the CoreDesktop line overrides it.

  - type: text
    kicker: "Firewall"
    headline: "ufw is on, and Docker can't get around it."
    body: |
      Incoming connections are blocked except SSH (22, keys only), mDNS (5353/udp), LocalSend (53317) and anything arriving over Tailscale.

      Docker normally publishes container ports around ufw, so **ufw-docker** is installed too. To let a container's port through, or to open a port for something else, such as a dev server you want to reach from another machine:

      ```
      sudo ufw-docker allow {container} {port}
      sudo ufw allow {port}/tcp
      sudo ufw status
      ```

      To see every open port and who can reach it, run [audit](/utilities/#audit).

  - type: text
    id: ssh
    kicker: "SSH"
    headline: "Reach this machine with a key, not a password."
    body: |
      The SSH server is on, so you can reach this computer from your other ones, and it accepts keys only. On a laptop at a café or a conference, that means nobody on the same Wi-Fi can try to guess your password. To log in over SSH, copy your public key to this computer once, from the computer you connect from:

      ```
      ssh-copy-id you@machine.local
      ```

      To allow passwords again, delete `/etc/ssh/sshd_config.d/10-coredesktop-keys-only.conf` and run `sudo systemctl reload sshd`.

      On machines installed earlier, where someone has logged in over SSH with a password, `update` leaves password login on, so nobody is locked out. Add your key, then switch with:

      ```
      bash ~/.local/share/coredesktop/system/sshd.sh
      ```

  - type: text
    id: snapshots
    kicker: "Snapshots"
    headline: "Roll back a bad update."
    body: |
      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, boot the [Arch ISO](https://archlinux.org/download/) 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
      ```

  - type: features
    kicker: "Hardware & network"
    headline: "Drivers, printing and your LAN."
    items:
      - label: "GPU drivers"
        body: "The Vulkan driver for Intel and AMD GPUs. For NVIDIA, if archinstall's proprietary driver wasn't chosen: the open kernel modules for GTX 16xx / RTX 20xx and newer, or the 580xx legacy driver back to the GTX 900 series. Reboot afterwards."
      - label: "mDNS"
        body: "Reach machines on your LAN as `machine.local`, e.g. `ssh machine.local`. Avahi and nss-mdns are set up ahead of systemd-resolved, so the two don't conflict."
      - label: "Printing"
        body: "The CUPS printing service is turned on. This may need more work to just work with other CoreDesktop machines."

  - type: checklist
    kicker: "System defaults"
    headline: "Small fixes that add up."
    items:
      - "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."
      - "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."

  - type: callout
    text: "On a machine without systemd-resolved, set up mDNS yourself with `bash ~/.local/share/coredesktop/fixmdns.sh`. See the [Arch wiki](https://wiki.archlinux.org/title/Avahi#Hostname_resolution) for more."

  - type: table
    id: what-coredesktop-changes
    kicker: "What CoreDesktop changes"
    headline: "Every system setting, beyond the software."
    lede: "Listed so you know what you're running, and so you can undo what you don't want."
    headers: ["Area", "What changes"]
    rows:
      - ["`/etc/pacman.conf`", "Adds the `[federated]` repository and trusts its signing key"]
      - ["SSH", "sshd is on, with key login only (`/etc/ssh/sshd_config.d/10-coredesktop-keys-only.conf`). Client keepalives are in `/etc/ssh/ssh_config.d/20-coredesktop-keepalive.conf`"]
      - ["Firewall", "ufw is on, with the [rules above](#firewall), 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 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`"]
      - ["Wi-Fi", "If iwd is turned on alongside NetworkManager (archinstall's **Copy ISO network configuration** does that), iwd and systemd-networkd are turned off, so NetworkManager runs the network from the next restart. Choose your Wi-Fi network once in GNOME's top-right menu after that restart. If you set NetworkManager to use iwd itself (`wifi.backend=iwd`), iwd is left alone"]
      - ["Services", "Avahi, Bluetooth, CUPS, fwupd, GDM, NetworkManager, sshd, Docker, Tailscale, ufw and systemd-oomd are turned on. 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"]
      - ["configure", "Only for what you set up: your Nextcloud files mount in `/etc/fstab`, GNOME Online Accounts, passwords in your GNOME keyring, and the backup timer"]

  - type: text
    id: uninstalling
    kicker: "Uninstalling"
    headline: "Undo CoreDesktop by hand."
    body: |
      CoreDesktop doesn't have an uninstaller, but you can undo it yourself. 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](#what-coredesktop-changes) you don't want. The software stays installed: remove what you don't want with `sudo pacman -Rns <package>` and `flatpak uninstall <app>`.

  - type: final-cta
    headline: "Keep it all current with one command."
    body: "`update` snapshots first, then updates everything, and tells you what failed."
    ctas:
      - label: "How updates work"
        url: "/utilities/#update"
        style: primary
---