webcoredesktop/content/utilities.md

title, description, sections

title	description	sections
Utilities	The CoreDesktop commands: update, refresh, version, audit, configure and reset. Keep your system current, check your version and open ports, connect your Federated Core and back up, or start over.	type compact eyebrow title subhead logTitle log hero true 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 tag text update Snapshot, then update everything tag text refresh Pull in new CoreDesktop additions tag text version Show what this machine is running tag text audit Show open ports and who can reach them tag text configure Connect your Core, Tailscale and backups tag text reset Back to the state right after install done text true Type any of them in a terminal. type kicker headline columns items cards At a glance Six commands, one job each. 3 label title body link linktext update Keep everything current Snapshots your system, then updates [Arch](https://archlinux.org), [GNOME](https://www.gnome.org), AUR packages, Flatpaks, the languages you added with mise, extensions and firmware. /utilities/#update How update works label title body link linktext refresh Get what's new Runs the install script again to add any new applications or services. /utilities/#refresh About refresh label title body link linktext version Know what you're running Shows your CoreDesktop version, kernel, sibling projects and last update, and whether something newer is waiting. /utilities/#version About version label title body link linktext audit See who can reach you Lists every open network port, who can connect to it through the firewall, and the service behind it. /utilities/#audit About audit label title body link linktext configure Sign in once Connects your Federated Core, joins its Tailscale network, sets up backups and signs in your AI agents. /utilities/#configure About configure label title body link linktext reset Start over, cleanly Changes your installation back to the state it was in right after you installed it. /utilities/#reset About reset type id kicker headline lede command note command update 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. 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. type kicker headline lede items checklist What update does Each step in updates.d, in order. update pulls the latest CoreDesktop (fast-forward only: if you've changed your copy, it warns you instead of merging), 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. Each run's full output is saved in `~/.local/state/coredesktop/logs/`; update keeps the logs of the last 10 updates and the last 3 installs or refreshes. 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](/system/#snapshots). Updates the Arch keyring, then Arch and GNOME, then AUR packages, Flatpaks, the languages you added with [mise](/software/mise/), 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. Lists packages that were installed only because something else needed them, and that nothing needs any more, and asks before removing them. The answer defaults to no. Packages CoreDesktop installs are never on this list. Debug symbols left behind by a package that's gone (the `-debug` packages the AUR builds alongside some programs) are removed without asking. type text callout To keep a package you use directly off that list for good, run `sudo pacman -D --asexplicit <package>`. And if an update ever barfs, check the **Latest News** on [archlinux.org](https://archlinux.org) for fixes. type id kicker headline lede command note command refresh 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. refresh Run `update` after `refresh`. type id kicker headline body text version 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 Video driver Mesa 26.2.6 Last update 2026-10-22 13:43 Sibling projects HamPack 2026.10.22 (52f043d), 2026.11.05 (b2c3d4e) is available coredesktop-dev v1.2.0 Update HamPack to 2026.11.05 (b2c3d4e)? [y/N] ``` The kernel and video driver come from Arch, so they're shown separately. version also tells you: - if a newer version of CoreDesktop, the kernel or the video driver is available - if a newer kernel is installed and waiting for a reboot - if your copy of CoreDesktop has local changes (it says "modified") ### Sibling projects If you've installed [sibling projects](/siblings/), version lists each one with its version: its latest release tag, such as `v1.2.0`, or, if it has none, the date and id of its latest change, like CoreDesktop's. For each one with a newer version, it asks whether to update it now. Answer `y` to update just that project without running a full update; update still keeps them all current. In a script, `version --check` prints the newer version of CoreDesktop if there is one. It doesn't look at sibling projects; `sibling check` does. ### 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. type id kicker headline body text audit 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](/system/#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. type id kicker headline lede command note command configure 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. configure To set up one thing, name it, e.g. `configure hermes`. `configure --list` shows the names. type kicker headline items features What configure covers Your Core, your network, your backups, your agents, your languages. label body Your Federated Computer Core Give 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. label body Your Core's Tailscale network Joins 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. label body Daily backups of your home folder Encrypted 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. label body Your AI agents Signs you in to Claude Code, opencode and Hermes Agent, and lets you choose their model providers. See the [AI Sandbox](/ai-sandbox/). label body Languages `configure languages` asks whether you want [Ruby on Rails](/software/ruby-on-rails/), then installs anything else [mise](/software/mise/) can, with a version, such as `java@21 deno@latest`. Go, Rust, Node.js, Python, Bun and Zig are already installed. type text callout **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. type id kicker headline body text backups Backups How the backups work. Once a day, shortly after midnight, restic backs up your home folder to `.backup-{machine name}` in your Nextcloud files. If the computer was off or you weren't logged in, it runs at your next login instead, once Nextcloud can be reached. It runs at the lowest priority, so it stays out of the way of whatever you're doing, and it only uploads what changed since the last backup. 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**. If a backup fails, a notification tells you. If only a few files couldn't be read, the rest are still backed up, and the log names the ones it skipped. ### How many backups are kept restic calls each backup a snapshot. After each backup, it removes older snapshots and keeps: - the latest from each of the last **7 days** - the latest from each of the last **4 weeks** - the latest from each of the last **6 months** One snapshot can count for more than one of these, so there are usually about 15 snapshots, going back about six months. Days, weeks and months with no backup, such as when the computer was off, don't count, so the oldest snapshot can be older than that. A file that's in several snapshots is stored only once, so keeping them all takes little more space than one full copy plus what's changed. ### What's left out The backup is for what you can't get back any other way. It leaves out things that can be downloaded, reinstalled or rebuilt, which keeps it smaller and quicker and saves space in your Nextcloud: - **Caches and the trash.** `~/.cache`, `~/.local/share/Trash`, the cache for the `/mnt` mount, Flatpak apps' caches, the caches Electron and Chromium apps (Element, browsers, editors) keep in `~/.config`, and any folder marked as a cache with a `CACHEDIR.TAG` file. - **Apps and tools that can be installed again.** Flatpak apps, Podman containers and images, CoreDesktop's own files and sibling projects, package caches (npm, bun, Cargo, Go), and what mise, uv, pipx, Claude Code and Neovim's plugins install. - **The AI agents' programs and downloads.** Their settings, memories and sessions are backed up. - **LM Studio's models and engines.** They're large and can be downloaded again. - **Element's search index** for encrypted messages, which Element rebuilds. - **WinBoat's Windows VM** (`~/winboat`). Its disk is large and changes whenever Windows runs, so most of it would be uploaded every day. - **Other drives and btrfs subvolumes** mounted inside your home folder. To leave out more, list paths or patterns in `~/.config/coredesktop/backup-exclude`, one per line, e.g. `$HOME/Videos` or `*.iso`. ### Turning backups off Run `configure backup` and choose **Turn backups off**. This stops the daily backup, and any backup that's running. The backups made so far stay in your Nextcloud files, and configure asks whether to delete them: - **Keep them** (the default). You can still restore from them as shown below, as your passphrase and app password stay in your keyring. To turn backups back on, run `configure backup`; they carry on in the same folder. - **Delete them.** Type the folder name to confirm. configure deletes the folder, revokes the backup's Nextcloud app password, and removes the passphrase and app password from your keyring. Nextcloud keeps the folder in its trash bin, where it still uses your storage, until you empty it. After that, the backups are gone for good. ### Checking on it ``` 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. type id kicker headline body text restoring-from-a-backup 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 ``` type id kicker headline lede command note command reset 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. reset Before you reset, make sure your [backup](/utilities/#backups) is current. Afterwards, run `update` to bring everything up to date. type headline body ctas final-cta Don't have a Federated Core yet? Every app your business needs, unlimited users, one low price, and private AI that runs on it. label url style Visit Federated Computer https://federated.computer/ primary label url style Contribute to CoreDesktop /contribute/ ghost