216 lines
10 KiB
Markdown
216 lines
10 KiB
Markdown
---
|
||
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, 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
|
||
---
|