Install
Menu

update · refresh · version · audit · configure · reset

A few commands keep it all running.

CoreDesktop comes with a handful of utilities. Type one in any terminal to keep your system current, see what’s open, connect your Core, or start over.

CoreDesktop utilities Running
  1. update Snapshot, then update everything
  2. refresh Pull in new CoreDesktop additions
  3. version Show what this machine is running
  4. audit Show open ports and who can reach them
  5. configure Connect your Core, Tailscale and backups
  6. reset Back to the state right after install
  7. Done Type any of them in a terminal.

At a glance

Six commands, one job each.

  • update

    Keep everything current

    Snapshots your system, then updates Arch, GNOME, AUR packages, Flatpaks, Ruby, extensions and firmware.

    How update works
  • refresh

    Get what’s new

    Runs the install script again to add any new applications or services.

    About refresh
  • version

    Know what you’re running

    Shows your CoreDesktop version, kernel and last update, and whether something newer is waiting.

    About version
  • audit

    See who can reach you

    Lists every open network port, who can connect to it through the firewall, and the service behind it.

    About audit
  • configure

    Sign in once

    Connects your Federated Core, joins its Tailscale network, sets up backups and signs in your AI agents.

    About configure
  • reset

    Start over, cleanly

    Changes your installation back to the state it was in right after you installed it.

    About reset

update

Keep your system up to date.

From time to time, you’ll want to update your system. Hopefully you’ll do it more than once a month.

Terminal
update

It’s a good idea to reboot after an update, especially when a new Linux kernel comes in, which happens often enough on Arch.

What update does

Each step in updates.d, in order.

update pulls the latest CoreDesktop, then runs each step in ~/.local/share/coredesktop/updates.d/. If a step fails, the other steps still run, and the failed ones are listed at the end.

  • 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.
  • Updates the Arch keyring, then Arch and GNOME, then AUR packages, Flatpaks, Ruby, CoreDesktop’s pipx apps, 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 installed only as dependencies that nothing needs anymore, and lists them. Packages CoreDesktop installs are never removed this way.

To keep a package you use directly from being removed, run sudo pacman -D --asexplicit <package>. And if an update ever barfs, check the Latest News on archlinux.org for fixes.

refresh

Pull in new additions.

refresh downloads the latest CoreDesktop and runs through the original install script again, adding any new applications or services. Anything already installed is skipped.

Terminal
refresh

Run update after refresh.

version

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:

$ 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. version also tells you:

  • if a newer version of CoreDesktop is available
  • if a newer kernel is installed and waiting for a reboot
  • if your copy of CoreDesktop has local changes (it says “modified”)

In a script, version --check prints the newer version if there is one.

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.

audit

See who can reach your machine.

audit

audit shows the network ports open on this computer. For each one it shows who can connect after the firewall: only this computer, your Tailscale network, or your LAN. It also names the service that opened the port and explains why, for example SSH, printing, mDNS, Tailscale or LocalSend.

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.

configure

Sign in once, and it’s all connected.

Some of what CoreDesktop installs needs you to sign in or make a choice first. configure shows what’s set up and sets up the rest.

Terminal
configure

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

What configure covers

Your Core, your network, your backups, your agents.

  • Your Federated Computer CoreGive it your Superpanel’s address (e.g. https://superpanel.example.com), your Core email, name and password. It adds Superpanel to your apps, your Nextcloud calendar, contacts and files and your email to GNOME Online Accounts, mounts your Nextcloud files at /mnt/example.com, and points Element at your Core’s Matrix server.
  • Your Core's Tailscale networkJoins this computer to it through headscale.example.com, so you can reach your other machines. 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.
  • Daily backups of your home folderEncrypted restic backups to a .backup-{machine name} folder in your Nextcloud files. It keeps 7 daily, 4 weekly and 6 monthly backups, and leaves out caches and things that can be reinstalled.
  • Your AI agentsSigns you in to Claude Code, opencode and Hermes Agent, and lets you choose their model providers. See the AI Sandbox.

Save your backup passphrase. configure shows it once. Keep it somewhere other than this computer, such as Bitwarden. Without it, the backups can’t be restored.

Backups

How the backups work.

restic reaches Nextcloud directly through rclone, with its own Nextcloud app password, so the backup doesn’t depend on the /mnt mount. The Nextcloud app passwords configure creates can be revoked in Nextcloud under Settings › Security.

To leave out more, list paths in ~/.config/coredesktop/backup-exclude, one per line.

systemctl --user list-timers coredesktop-backup.timer
journalctl --user -u coredesktop-backup

The first shows when the next backup runs; the second shows how the last ones went.

Restoring

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

reset

Start over from a clean install.

reset changes your CoreDesktop installation back to the state it was in right after you installed it. Use it when you’ve changed so much that starting again from a known-good setup is simpler than undoing things one by one.

Terminal
reset

Before you reset, make sure your backup is current. Afterwards, run update to bring everything up to date.