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, GNOME, AUR packages, Flatpaks, Ruby, 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, 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, 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."

  - type: callout
    text: "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](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."
    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/)."

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

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