webcoredesktop/content/utilities.md

---
title: "Utilities"
description: "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."
sections:
  - type: hero
    compact: true
    eyebrow: "update · refresh · version · audit · configure · reset"
    title: "A few commands keep it all running."
    subhead: "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."
    logTitle: "CoreDesktop utilities"
    log:
      - tag: "update"
        text: "Snapshot, then update everything"
      - tag: "refresh"
        text: "Pull in new CoreDesktop additions"
      - tag: "version"
        text: "Show what this machine is running"
      - tag: "audit"
        text: "Show open ports and who can reach them"
      - tag: "configure"
        text: "Connect your Core, Tailscale and backups"
      - tag: "reset"
        text: "Back to the state right after install"
      - done: true
        text: "Type any of them in a terminal."

  - type: cards
    kicker: "At a glance"
    headline: "Six commands, one job each."
    columns: 3
    items:
      - label: "update"
        title: "Keep everything current"
        body: "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."
        link: "/utilities/#update"
        linktext: "How update works"
      - label: "refresh"
        title: "Get what's new"
        body: "Runs the install script again to add any new applications or services."
        link: "/utilities/#refresh"
        linktext: "About refresh"
      - label: "version"
        title: "Know what you're running"
        body: "Shows your CoreDesktop version, kernel and last update, and whether something newer is waiting."
        link: "/utilities/#version"
        linktext: "About version"
      - label: "audit"
        title: "See who can reach you"
        body: "Lists every open network port, who can connect to it through the firewall, and the service behind it."
        link: "/utilities/#audit"
        linktext: "About audit"
      - label: "configure"
        title: "Sign in once"
        body: "Connects your Federated Core, joins its Tailscale network, sets up backups and signs in your AI agents."
        link: "/utilities/#configure"
        linktext: "About configure"
      - label: "reset"
        title: "Start over, cleanly"
        body: "Changes your installation back to the state it was in right after you installed it."
        link: "/utilities/#reset"
        linktext: "About reset"

  - type: command
    id: update
    kicker: "update"
    headline: "Keep your system up to date."
    lede: "From time to time, you'll want to update your system. Hopefully you'll do it more than once a month."
    command: "update"
    note: "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: checklist
    kicker: "What update does"
    headline: "Each step in updates.d, in order."
    lede: "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."
    items:
      - "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."

  - type: callout
    text: "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: command
    id: refresh
    kicker: "refresh"
    headline: "Pull in new additions."
    lede: "refresh downloads the latest CoreDesktop and runs through the original install script again, adding any new applications or services. Anything already installed is skipped."
    command: "refresh"
    note: "Run `update` after `refresh`."

  - type: text
    id: version
    kicker: "version"
    headline: "Which version am I running?"
    body: |
      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.

  - type: text
    id: audit
    kicker: "audit"
    headline: "See who can reach your machine."
    body: |
      ```
      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: command
    id: configure
    kicker: "configure"
    headline: "Sign in once, and it's all connected."
    lede: "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."
    command: "configure"
    note: "To set up one thing, name it, e.g. `configure hermes`. `configure --list` shows the names."

  - type: features
    kicker: "What configure covers"
    headline: "Your Core, your network, your backups, your agents, your languages."
    items:
      - label: "Your Federated Computer Core"
        body: "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: "Your Core's Tailscale network"
        body: "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: "Daily backups of your home folder"
        body: "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: "Your AI agents"
        body: "Signs you in to Claude Code, opencode and Hermes Agent, and lets you choose their model providers. See the [AI Sandbox](/ai-sandbox/)."
      - label: "Languages"
        body: "`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: callout
    text: "**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: text
    id: backups
    kicker: "Backups"
    headline: "How the backups work."
    body: |
      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: text
    id: restoring-from-a-backup
    kicker: "Restoring"
    headline: "Restoring from a backup."
    body: |
      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: command
    id: reset
    kicker: "reset"
    headline: "Start over from a clean install."
    lede: "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."
    command: "reset"
    note: "Before you reset, make sure your [backup](/utilities/#backups) is current. Afterwards, run `update` to bring everything up to date."

  - type: final-cta
    headline: "Don't have a Federated Core yet?"
    body: "Every app your business needs, unlimited users, one low price, and private AI that runs on it."
    ctas:
      - label: "Visit Federated Computer"
        url: "https://federated.computer/"
        style: primary
      - label: "Contribute to CoreDesktop"
        url: "/contribute/"
        style: ghost
---