Update checks and in-place updates for Linux desktop apps released on GitHub or Forgejo.
praeco is a Rust library and a command-line tool. It does all the update logic: it asks a release source what is new, works out how the running app was installed, downloads the right file, verifies its SHA-256, installs it, and restarts the app. It draws no UI. Each app shows its own pill, "What's new" sheet and buttons, and calls praeco underneath.
- Apps in any language (C++/Qt, Python, Go, ...) run the
praecoCLI and read its JSON. - Rust apps can use the
praecolibrary crate directly, or the CLI.
praeco works with any Linux desktop and is at home in Omarchy. An app registers once
with praeco init, and omarchy update then brings it up to date along with the rest
of the system, silently, with the password the update already asked for. Apps that link
praeco as a library can register their own update command instead, so nothing else has
to be installed. Elsewhere the same registrations work with praeco update-all, run by
hand or from a timer. See Updating with the system.
Linux only, on x86_64 and aarch64; each release has static binaries for both. Asset
selection follows the machine's architecture (x86_64/amd64, aarch64/arm64, ...).
Signed releases, thanks to packslip. An app can publish a signed manifest of its release files, and praeco checks it before it installs anything, with no setup by the app or the user. The signed format, the verifier praeco embeds, and the signing action that praeco's own releases use are all the work of the packslip project; praeco only decides when to check and what to remember. Without it, the best praeco could do was compare a download with a checksum that comes from the same place as the file. If you ship an app, please sign your releases. Since 0.4.0, praeco's own releases are signed too, and the packaging notes changed with them: the binary is bigger, and building it from source needs a newer Rust and a C compiler.
- Quick start
- How an update works
- CLI reference
- JSON formats
- Install kinds and the exact commands
- Dialog mode, terminal mode and the fallback
- Restart
- Updating with the system:
initandupdate-all - Shipping praeco with your app
- Using praeco from an app
- Library API
- Security
- Limitations
- Building and testing
- Acknowledgements
- License
# Is there something newer than 1.0.4? (JSON)
praeco check --github you/myapp --current 1.0.4 --json
# Install 1.0.5 over the running app, then restart it
praeco install --github you/myapp --version 1.0.5 --exe /usr/bin/myapp \
--restart-pid 4242 --restart -- /usr/bin/myapp --some-arg
# A Forgejo or Gitea server instead of GitHub
praeco check --forgejo https://code.example.com owner/repo --current 1.0.4 --json- Check.
GET /repos/{owner}/{repo}/releases(GitHub) orGET /api/v1/repos/{owner}/{repo}/releases(Forgejo/Gitea). Drafts and prereleases are ignored unless--prereleases. Versions are compared as semantic versions (a leadingvis fine,1.2reads as1.2.0). The result lists every release newer than the running one, newest first, each with its notes. The notes are the release body with the install boilerplate cut off at the first line that starts with the marker (default## Install;--markerchanges it,--marker ''keeps whole bodies). The marker must be a whole heading: the line starts with it and it is followed by nothing or whitespace, so## Installand## Install (Linux)cut,## Installer fixesdoes not. - Detect how the app was installed from its executable path and the environment (see below).
- Download the matching asset into a private (
0700) temporary directory. Only URLs from the release's own asset list are used, and only if they belong to the configured repository. - Verify. If the release (on GitHub) carries a signed manifest, the
download is checked against its signature, see Signed releases.
Otherwise the SHA-256 is checked against the release's
<asset>.sha256file and/orSHA256SUMS. No match, or no checksum at all, means failure: nothing is installed. - Install (dialog or terminal mode).
- Restart the app, if asked.
A release can carry a packslip: one file,
packslip.sigstore.json, signed by the project's release workflow and uploaded
beside the other assets. All of this rests on the packslip project: praeco uses its Rust
crate to verify bundles, and its GitHub Action signs praeco's own releases. packslip
records each signature in Sigstore's public transparency log, so there is no signing key
for a project to keep or lose. Publish one if you can. Without it, praeco can only compare
the download with a checksum that comes from the same place as the file, so anyone who
can publish a release can publish a matching checksum. With it, praeco checks the
signature and the signed digest of the exact file it downloaded, and a stolen upload or
release token alone is no longer enough to push a bad build.
Upload the packslip before the release goes public. Once praeco has seen an app signed, it refuses a later release without a bundle (see below), so a release that is public for even a few minutes without its signature makes every update fail until the file appears, and keeps failing if signing breaks. Create the release as a draft, sign, upload the bundle, then publish. praeco's own release workflow does it in that order.
What praeco does, with no setup by the app or the user:
- It looks for
packslip*.sigstore.jsonamong the release's assets. With one, it verifies the bundle before downloading anything, then checks the download against it. A bad signature, a different project or version, or an asset the signature does not list stops the update:signature_invalid. - The first signed release of a project is trusted on first use, bound to the
repository's ID on GitHub rather than only its name (a repository deleted and
re-created under the same name does not pass). Praeco remembers the repository and the
signing workflow in
~/.config/praeco/signers.json. Later releases must match. - A project that was signed once cannot go back to unsigned releases:
a release without a bundle is refused with
signature_missing. If a project stops signing on purpose, or changes its release workflow, delete its entry fromsigners.jsonto accept that. - Releases without a bundle are installed as before, with the checksum check. Signing is never required.
Only repositories on github.com are covered. Forgejo and GitHub Enterprise sources
stay on checksums, because packslip names a signer only for GitHub and GitLab projects.
The check needs the signed cargo feature, on by default; see
Building and testing.
A check is one request. It sends If-None-Match with the cached ETag (cache in
$XDG_CACHE_HOME/praeco, or ~/.cache/praeco), so repeated checks are cheap:
GitHub does not count a 304 against the rate limit. Rate limits come back as a
clean rate_limited error with a "try again in N minutes" message. There is no
authentication by default; if you need it, put a token in the environment variable
PRAECO_TOKEN (or name another with --token-env). The token goes to the API host
only, never to downloads. Only the first page of releases is read (100 on GitHub, 50
on Forgejo), which is plenty for "what is new since my version".
praeco check SOURCE --current VERSION [--marker TEXT] [--prereleases] [--exe PATH] [--json]
praeco install SOURCE --version VERSION --exe PATH [--mode dialog|terminal]
[--restart-pid PID] [--restart -- COMMAND [ARGS...]]
praeco detect --exe PATH
praeco init --name NAME SOURCE (--exe PATH | --appimage PATH) [--version-arg ARG]... [--hook auto|none] [--json]
praeco init --name NAME SOURCE [--exe PATH | --appimage PATH] [--needs-terminal] [--hook auto|none] [--json]
--update-cmd -- PROGRAM [ARGS...]
praeco init --remove --name NAME [--hook auto|none] [--json]
praeco update-all [--mode auto|inline|dialog|terminal] [--json]
praeco --help | --version
Source (exactly one):
| Flag | Meaning |
|---|---|
--github OWNER/REPO |
GitHub release source |
--forgejo BASE_URL OWNER/REPO |
Forgejo or Gitea at BASE_URL, e.g. https://code.example.com |
--github-api-base URL |
With --github: a GitHub-compatible API base (GitHub Enterprise) |
HTTPS is required. Plain HTTP is accepted only for loopback addresses.
Options for all commands:
| Flag | Meaning |
|---|---|
--prereleases |
Include prereleases (default: stable only). For install, needed to install a prerelease version. |
--asset-pattern KIND=GLOB |
Asset name pattern for KIND (pacman, deb, rpm, appimage, tarball). Repeatable; replaces that kind's defaults. * and ? wildcards, case-insensitive. {arch} expands to the machine's architecture names. |
--token-env NAME |
Environment variable holding an API token (default PRAECO_TOKEN) |
--appimage PATH, --appdir PATH |
The AppImage the app runs from and its mount directory. Default: the APPIMAGE and APPDIR environment variables. |
check:
| Flag | Meaning |
|---|---|
--current VERSION |
The running app's version (required) |
--marker TEXT |
Cut notes at the first line starting with TEXT (default ## Install) |
--exe PATH |
Also report how that executable is installed and which asset would be used |
--no-cache |
Skip the ETag cache |
--json |
One JSON object on stdout. Without it, a short human summary. |
install:
| Flag | Meaning |
|---|---|
--version VERSION |
Version to install (required); must be a release of the source |
--exe PATH |
The running app's executable (required); decides the install kind |
--mode dialog|terminal |
dialog (default): permission prompt through polkit. terminal: open a terminal and use sudo. |
--restart-pid PID |
The app's PID: it is sent SIGTERM and awaited before relaunch |
--restart -- CMD ARGS... |
The command line that starts the new version. Everything after -- belongs to it, so it must come last. Without --restart-pid, the command is just started. |
--restart-timeout SECS |
How long to wait for the app to quit (default 30) |
--detach |
Continue in a background process (new session) and return at once. See Launching praeco from an app. |
--progress-file PATH |
With --detach: where the background process writes its JSON lines. Must not exist yet; created 0600 (exclusively, never through a symlink) in a directory that is yours and not writable by others. Default: a new private (0700) temporary directory; the path is in the detached event. |
Output of install is JSON lines on stdout, one event per line, flushed as it
happens. A closed pipe never kills praeco, which matters when the app quits
mid-restart.
Environment: PRAECO_TOKEN (see above). Debug builds, which the tests use, also read
PRAECO_TRUSTED_DIRS and PRAECO_ESCALATION_CMD; release builds ignore both (see
Security).
| Code | Meaning |
|---|---|
| 0 | Success. For check, also when no update exists. |
| 1 | Failure: network, API, rate limit, missing or bad checksum, install failed, permission refused, terminal closed |
| 2 | Usage error (bad flags) |
| 3 | needs_terminal: dialog mode cannot work here; run again with --mode terminal |
| 4 | Unsupported install (a source build): nothing to update automatically |
| 5 | Installed, but the app could not be restarted (the new version is on disk) |
{
"ok": true,
"source": "github:you/myapp",
"current": "1.0.4",
"latest": "1.0.6",
"update_available": true,
"releases": [
{
"version": "1.0.6",
"tag": "v1.0.6",
"name": "MyApp 1.0.6",
"published_at": "2026-10-24T09:12:00Z",
"url": "https://github.com/you/myapp/releases/tag/v1.0.6",
"prerelease": false,
"notes": "### Fixed\n- The sidebar no longer flickers."
},
{
"version": "1.0.5",
"tag": "v1.0.5",
"name": "MyApp 1.0.5",
"published_at": "2026-10-20T16:40:00Z",
"url": "https://github.com/you/myapp/releases/tag/v1.0.5",
"prerelease": false,
"notes": "### Added\n- Tag chips in the editor."
}
]
}(The real output is a single line.)
latestis the highest eligible release, whether or not it is newer thancurrent(nullwhen the source has no eligible releases).releasesholds every release newer thancurrent, newest first; empty when up to date.notesis Markdown: the release body up to the install marker.
With --exe PATH, an install object is added, so the app knows whether to offer
an Install button at all:
"install": {
"kind": "pacman",
"supported": true,
"reason": "Installed as a pacman package",
"detail": "/usr/bin/myapp is owned by myapp 1.0.4-1",
"target": "/usr/bin/myapp",
"asset": { "name": "myapp-x86_64.pkg.tar.zst", "size": 18874368 }
}kind is pacman, deb, rpm, appimage, tarball or unsupported.
supported is false for unsupported, and also when the latest release has no file
for this kind and architecture; reason says which.
Up to date:
{"ok":true,"source":"github:you/myapp","current":"1.0.6","latest":"1.0.6","update_available":false,"releases":[]}Failure (exit code 1: offline, rate limit, bad response, ...):
{"ok":false,"error":{"code":"network","message":"Could not reach api.github.com. Check the internet connection. (...)"}}Error codes: usage, invalid_version, network, rate_limited, api,
no_release, no_asset, unsupported, checksum_missing, checksum_mismatch,
signature_invalid, signature_missing, download, needs_terminal, auth_cancelled, auth_failed, install_failed,
terminal_closed, restart_failed, io. Messages are plain language and can be shown to a user as is.
{"ok":true,"kind":"appimage","supported":true,"reason":"Running from the AppImage /home/you/Apps/MyApp.AppImage","detail":null,"target":"/home/you/Apps/MyApp.AppImage","asset":null}A successful dialog-mode install with a restart:
{"event":"resolving","version":"1.0.5"}
{"event":"downloading","asset":"myapp-x86_64.pkg.tar.zst","bytes":0,"total":18874368}
{"event":"downloading","asset":"myapp-x86_64.pkg.tar.zst","bytes":9437184,"total":18874368}
{"event":"downloading","asset":"myapp-x86_64.pkg.tar.zst","bytes":18874368,"total":18874368}
{"event":"verifying","asset":"myapp-x86_64.pkg.tar.zst"}
{"event":"installing","kind":"pacman","message":"Installing the pacman package. Administrator permission is needed."}
{"event":"installed","version":"1.0.5","kind":"pacman"}
{"event":"restarting","message":"Closing the app so the new version can start..."}
{"event":"restarting","message":"Starting the new version..."}
{"event":"done","version":"1.0.5","restarted":true}
| Event | Fields | Notes |
|---|---|---|
resolving |
version |
First event |
downloading |
asset, bytes, total |
First, last, and at most every ~150 ms between. total is null if unknown. |
verifying |
asset |
The SHA-256 or signature check |
signed |
project, signer |
Only for a signed release, after the signature checked out; signer is the workflow that signed it |
installing |
kind, message |
message is plain language |
installed |
version, kind |
The new version is on disk |
restarting |
message |
Only with --restart; two events (closing, starting) |
done |
version, restarted |
Last event of a success |
terminal_opened |
terminal |
Terminal mode only: first event, which terminal was started |
detached |
progress_file |
--detach only: the only line printed on stdout; the other events go to that file |
needs_terminal |
message |
Last event, exit code 3: retry with --mode terminal |
error |
code, message |
Last event of a failure; the exit code follows the table above |
Every run ends with exactly one of done, needs_terminal or error. In terminal
mode the same events are relayed to stdout; the plain-language progress is shown in
the terminal window instead. Usage errors (exit 2) print the failure object shown
for check instead of events.
Examples of the last line on failure:
{"event":"error","code":"checksum_mismatch","message":"The downloaded myapp-x86_64.AppImage does not match the checksum in myapp-x86_64.AppImage.sha256. It was not installed."}
{"event":"needs_terminal","message":"No polkit authentication agent is running, so a permission prompt cannot appear. Continue in a terminal."}
{"event":"error","code":"unsupported","message":"/opt/build/myapp is not owned by a package, is not an AppImage and is not under your home folder, so it looks like a source build. Update it the way you built it."}
Detection looks at the executable path (--exe) and the environment, in this order:
| Order | Test | Kind | Default asset pattern |
|---|---|---|---|
| 1 | APPIMAGE (or --appimage) names an existing file, and APPDIR (or --appdir) is set and contains the executable |
appimage |
*.AppImage |
| 2 | pacman -Qo <exe> succeeds |
pacman |
*.pkg.tar.zst |
| 3 | dpkg -S <exe> succeeds |
deb |
*.deb |
| 4 | rpm -qf <exe> succeeds |
rpm |
*.rpm |
| 5 | the executable lives under the user's home | tarball |
*.tar.gz |
| 6 | anything else | unsupported (a source build), with a reason |
none |
The package queries (run from the trusted directories only, see below) are tried on the path as given and on its symlink-resolved path. A build you compiled yourself under your home folder is indistinguishable from a tarball install and is treated as one.
Asset selection: the name must match the kind's pattern; names for another
architecture (aarch64, arm64, ...) are excluded; a name that mentions this
architecture beats one that mentions none. Assets named like these
(myapp-x86_64.pkg.tar.zst, myapp-amd64.deb, myapp-x86_64.rpm,
myapp-x86_64.AppImage, myapp-linux-x86_64.tar.gz, their .sha256 files and
SHA256SUMS) match the defaults. Override with --asset-pattern, for example
--asset-pattern 'deb=myapp_*_{arch}.deb'.
The commands that run elevated, always on the verified local file in the private
temp directory, never a script (<file> is its absolute path, in a canonical
$TMPDIR or /tmp, a relative TMPDIR being ignored). Programs (pkexec, sudo,
pacman, apt-get, dpkg, dnf, rpm) are looked up only in /usr/bin,
/usr/sbin, /bin and /sbin, never in the user's PATH; each must be an
absolute, executable path that is owned by root and not writable by group or others.
The elevated command runs with a cleared environment and
PATH=/usr/sbin:/usr/bin:/sbin:/bin:
| Kind | Elevated command |
|---|---|
| pacman | pacman -U --noconfirm <file> |
| deb | apt-get install -y <file>, or dpkg -i <file> if apt-get is not installed |
| rpm | dnf install -y <file>, or rpm -U <file> if dnf is not installed |
Why these: apt-get install and dnf install on a local file also pull in
dependencies and handle it as an upgrade; pacman -U is the supported way to install
a local package; dpkg -i and rpm -U are the plain fallbacks. In dialog mode the
full command is pkexec <program> <args> <file>; in terminal mode it is
sudo <program> <args> <file>; when praeco already runs as root there is no prefix.
apt-get may print a notice that the file cannot be read by the _apt user and is
used "unsandboxed"; that is expected for a local file and harmless.
No root is involved for the other two kinds:
- AppImage: the destination is resolved through symlinks first (a symlinked AppImage is updated at its real path and the link stays a link). The file is written beside the old one (hidden name, same directory), fsynced, given the old file's mode (the owner execute bit is guaranteed), and renamed over it; the directory is fsynced too. A running AppImage keeps working from the old file until it exits. If anything fails the old file is untouched and the temporary file is removed.
- Tarball: praeco finds the archive entry for the app's executable (same file
name, longest common path suffix with the installed path). Everything above that
suffix in the archive is dropped, and everything above it in the installed path is
the install root. For
~/.local/opt/myapp/bin/myappand an archive holdingmyapp-1.0.5/bin/myapp, the root is~/.local/opt/myappand themyapp-1.0.5/prefix is stripped. The root is never/, your home folder or any parent of it, nor a hidden folder directly in your home folder other than~/.local: if the match would put it there (an archive unpacked straight into~, so the app lives in~/myapp-1.0/lib/myapp/myapp), the root moves down to the archive's own top folder (~/myapp-1.0). Every entry must lie below the archive prefix; an entry outside it (a.bashrcat the top of the archive) is an error and nothing is installed. The archive is extracted into a private staging directory inside the root (same file system), refusing absolute paths,.., hard links, devices and symlinks that point outside their tree, more than 100,000 entries and more than 2 GiB in total (decompression bombs); then each file is renamed over its destination. Each rename is atomic, so a running program never sees a half-written file; the tree as a whole is not one transaction. Files in the install that are not in the archive are left alone (nothing is deleted).
Dialog mode (default) asks for administrator rights with pkexec, which shows
the desktop's own polkit prompt. praeco decides up front, before downloading
anything, whether that can work. It reports needs_terminal (exit code 3) unless
all of these hold:
pkexecis onPATH;- a graphical session exists (
WAYLAND_DISPLAYorDISPLAYis set); - a polkit authentication agent is running: some process in
/procnamed like*polkit*or*policykit*(polkit-gnome-authentication-agent-1,hyprpolkitagent,lxqt-policykit-agent, ...;polkitd, the daemon, does not count), or a shell that embeds an agent (gnome-shell,cinnamon,cosmic-osd).
Item 3 is a heuristic. If it guesses wrong and pkexec still cannot show a prompt, it
exits 127 or 126 afterwards, those are not "no agent" (that case is decided up front)
and do not trigger the terminal fallback: 126 (dismissed, or not allowed to install)
becomes auth_cancelled, and 127 (password not accepted, or the prompt could not
finish) becomes auth_failed, each with a plain message. When praeco already runs as root none of this is
needed. AppImage and tarball installs need no rights and never fall back.
The app's job on needs_terminal is to run the same praeco install ... again with
--mode terminal.
Terminal mode (--mode terminal) re-runs praeco itself inside the user's
terminal, doing the same steps with sudo instead of pkexec, and shows plain
language progress. On failure it waits for Enter so the message can be read. The
terminal is chosen as: xdg-terminal-exec, then $TERMINAL, then the first found of
foot, kitty, alacritty, ghostty, wezterm, gnome-terminal, konsole, xfce4-terminal,
terminator, x-terminal-emulator, urxvt, xterm. Terminals that re-split their command as
one string (tilix, lxterminal) are never used, because a path with spaces would break;
the command is always handed over as separate arguments. The terminal
process and the original praeco talk through an events file in a private temp
directory; the original relays the worker's events to stdout as JSON lines. If the
window is closed before the update finishes, the result is terminal_closed. The
restart is done by the original process after the worker reports success, with the
same code as dialog mode. (The worker is the hidden mode --mode terminal-inner;
apps should not call it.)
With --restart-pid N --restart -- COMMAND..., after a successful install praeco:
- sends
SIGTERMtoN(the app should quit cleanly) and waits, polling every 100 ms, until it has exited (a zombie counts as exited), up to--restart-timeoutseconds (default 30). If it does not exit, praeco stops withrestart_failed("The app did not close within 30 seconds. The update is installed; ..."), exit code 5, and never sendsSIGKILL; - starts
COMMAND...fully detached: a new session (setsid), no controlling terminal, stdio on/dev/null, not through a shell. It survives praeco exiting and the terminal closing. The AppImage variablesAPPIMAGE,APPDIR,ARGV0andOWDare removed from its environment, since they describe the old mount, and so are entries pointing into that mount (/tmp/.mount_*or underAPPDIR) inLD_LIBRARY_PATH,QT_PLUGIN_PATH,QML2_IMPORT_PATH,PATHandXDG_DATA_DIRS(a variable left empty is removed); - exits.
N must be a real process other than praeco and init. praeco ignores SIGHUP
during an install so a closing terminal does not interrupt a package manager.
The app is told to quit with a signal, so it should handle SIGTERM by quitting
cleanly (a Qt app can install a handler that calls QCoreApplication::quit()).
praeco must keep running after the app quits, because it starts the new version. A plain
child process of the app may be killed with it, and a process started with
QProcess::startDetached has no stdout to read. So use --detach:
praeco install SOURCE --version V --exe PATH --restart-pid PID --detach \
--progress-file /run/user/1000/myapp/update-1.jsonl --restart -- /usr/bin/myapp
--detach makes praeco start a second copy of itself in a new session (setsid, no
terminal, stdin and stderr on /dev/null, stdout going to the progress file) and return
at once. The copy installs and restarts as usual and writes the same JSON lines to the
progress file; it survives the app's exit. The progress file must not exist yet; praeco
creates it 0600, exclusively and never through a symlink, in a directory that must
belong to you and not be writable by others (so not /tmp itself). Without
--progress-file praeco makes a private temporary directory and the path is printed in
the one line it writes to stdout:
{"event":"detached","progress_file":"/tmp/praeco-progress-Ab3dEf/progress.jsonl"}
The exit code of the detached run is not available; its last line says how it ended
(done, needs_terminal or error).
If praeco itself is inside the app's AppImage mount (under APPDIR or /tmp/.mount_*),
that mount disappears when the app quits. With --detach or --restart, praeco first
copies itself to a private temporary directory, continues from the copy, and removes the
copy when done, so an AppImage can carry praeco inside it. A distro package needs no
copy: it ships praeco outside any mount (see
Shipping praeco with your app).
C++/Qt, the one pattern to use:
const QString dir = QStandardPaths::writableLocation(QStandardPaths::RuntimeLocation) + "/myapp";
QDir().mkpath(dir); // yours, mode 0700
QFile::setPermissions(dir, QFile::ReadOwner | QFile::WriteOwner | QFile::ExeOwner);
const QString progress = dir + "/update-" + QUuid::createUuid().toString(QUuid::Id128) + ".jsonl";
// The praeco this app ships, by full path (see "Shipping praeco with your app").
const QString praeco = QDir::cleanPath(QCoreApplication::applicationDirPath() + "/../lib/myapp/praeco");
QStringList args = {"install", "--github", "you/myapp", "--version", latest,
"--exe", QCoreApplication::applicationFilePath(),
"--restart-pid", QString::number(QCoreApplication::applicationPid()),
"--detach", "--progress-file", progress,
"--restart", "--", QCoreApplication::applicationFilePath()};
QProcess::startDetached(praeco, args);
// Then tail the file with a 200 ms QTimer: remember the read offset, read new
// complete lines, QJsonDocument::fromJson each one. Stop at "done", "error" or
// "needs_terminal". On "needs_terminal" run the same command again with
// "--mode terminal" and a new progress file.The app keeps running while the update downloads and installs; it quits only when praeco
sends SIGTERM, and the new version starts from the detached copy.
Rust: call the library in-process, as shown below, or use the same CLI
command with std::process::Command::new(&praeco).args(...).spawn(), praeco being
the full path of the binary you ship, and tail the
progress file the same way. The library path needs no file.
An app can have praeco keep it current even when the app is not running, by
registering once. The app calls praeco init, for example on first run or from its
package's post-install step; praeco does the rest.
praeco init --name myapp --github you/myapp --exe /usr/bin/myapp
praeco init --name myapp --github you/myapp --appimage "$APPIMAGE" # an AppImageinit writes ~/.config/praeco/apps.d/myapp.json (or under $XDG_CONFIG_HOME),
runs the app's version command once and reports the version it read (a warning, not
an error, if it cannot), and adds praeco to the system's own update command where
there is one. Run it again to change anything; it replaces the registration.
--version-arg ARG (repeatable) changes how the version is asked for (default
--version); --prereleases and --asset-pattern work as elsewhere; --hook none
skips the system hook; --json prints one object.
praeco init --remove --name myapp is the way out: it deletes the registration and,
when no app is registered any more, the system hook praeco added. Call it when the
user turns "update with the system" off or the app is uninstalled. Removing a name
that is not registered is not an error, a registration owned by a system package is
never deleted (remove the package instead), and a hook file praeco did not write is
never touched.
praeco update-all # every registered app, silently
praeco update-all --mode inline # sudo in this terminal
praeco update-all --json # {"ok":..,"apps":[{"name","status","from","to","error"}],"problems":[..]}update-all never asks whether to update, like the system updaters it runs beside.
For each app it reads the installed version, checks the source, and installs a newer
release the same way praeco install does. One app failing does not stop the
others; the exit code is 1 if any failed. An app whose executable is gone is
reported not_installed and is not a failure. status is up_to_date, updated,
hosted, not_installed or failed. It does not restart apps: a new version starts the next
time the app is launched.
Administrator rights (packages only; AppImage and tarball installs need none):
--mode |
What happens |
|---|---|
auto (default) |
sudo in the current terminal if stdin is one; otherwise the desktop permission prompt; if that cannot appear, a terminal window |
inline |
sudo in the current terminal |
dialog |
the permission prompt (pkexec) only |
terminal |
a terminal window only |
Only "no prompt is possible" moves on to the next way. A dismissed prompt is an answer and stops that app.
Omarchy. praeco init adds ~/.config/omarchy/hooks/post-update.d/50-praeco
(recognised by ID=omarchy in /etc/os-release), so omarchy update also runs
praeco update-all with the password it already took. The hook is one shared file
that calls praeco by full path. It is installed with Omarchy's own
omarchy-hook-install when that is on your PATH (praeco follows the path the tool
reports and checks the file is right), and written directly otherwise. init
rewrites it if praeco moved, never replaces a file of the same name that praeco did
not write, and refuses to point it at a praeco inside an AppImage mount or /tmp. A failing hook never stops the system update.
Deleting the file undoes it. Other systems get no hook yet; update-all still works
when run by hand or from your own timer.
Apps that link praeco as a library. An app with no praeco program of its own
(a Rust app using the crate, shipped as an AppImage) registers with an update
command: the command that makes the app update itself, headless. The system update
runs that command directly, so nothing else has to be installed, and the app's own
rules (its settings, its skipped versions, "off") decide whether to update.
praeco init --name myapp --github you/myapp --update-cmd -- "$APPIMAGE" update-now
praeco init --remove --name myappuse praeco::integrate::{self, HookMode};
use praeco::registry::{App, SourceSpec};
use praeco::updateall::{update_hosted, Options, UpdateMode};
// Once, when the user chooses "update with the system":
let app = App {
name: "myapp".into(),
source: SourceSpec::from(&source), // the praeco::Source you already check
exe: program.clone(), // the AppImage file, not a path inside its mount
appimage: true,
version_cmd: vec![], // not needed: the app knows its version
update_cmd: Some(vec![program.display().to_string(), "update-now".into()]),
needs_terminal: false, // true if an update may need sudo
prereleases: false,
asset_patterns: vec![],
};
integrate::register(&praeco::detect::Env::from_process(), &app, HookMode::Auto, None)?;
// In `myapp update-now`, after your own checks:
let opts = Options::from_process(UpdateMode::Auto);
let result = update_hosted(&app, env!("CARGO_PKG_VERSION"), &opts, &mut |line| println!("{line}"));On Omarchy this writes 50-praeco-myapp beside (not instead of) the shared hook.
The command runs in a session of its own, with no terminal and stdin closed, unless
needs_terminal is set, so an app that needs no administrator rights cannot reach the
update's unlocked sudo. A command that is gone (the app was uninstalled) is skipped
quietly, and a program under /tmp or inside an AppImage mount is refused. update-all
lists such an app as hosted and does not run it; its own hook does.
integrate::unregister (or praeco init --remove) takes the registration and the
app's hook out; the shared hook stays while any app still relies on it.
Where registrations live and who is trusted. ~/.config/praeco/apps.d/ for the
user, and /usr/share/praeco/apps.d/ for packages (the user's file of the same name
wins). Each file is {"name", "source", "exe", "version_cmd" or "update_cmd", ...}; a file must be
owned by the folder's owner (root for the system folder) and not writable by anyone
else, or it is ignored and listed under problems.
Security note. The version command runs the registered program. During
omarchy update the caller's sudo is unlocked for its terminal, and praeco must not
hand that to an app, so the version command runs in a session of its own with no
terminal and stdin closed (a time limit of 15 seconds applies). That keeps it from
using the terminal's sudo timestamp unless sudo is set to share timestamps across
terminals (timestamp_type=global) or to need no password. Anything that can write
to your registry or to a hook directory can already run code when you run the system
update, so the registry adds no new kind of access, but treat apps.d like a hook
directory.
Each app ships its own praeco, pinned to a release tag, and calls it by full path. praeco is then updated the same way as the app: to move to a newer praeco, bump the pin in an app release. The praeco already installed downloads and installs that release, and the new package carries the new praeco. Users never install or update praeco themselves.
Do not rely on a praeco shared between apps or found on PATH: nothing would keep it
up to date, one app's update could change another app's updater, and a PATH lookup
runs whatever binary comes first.
Where to put it. A private directory of the app, so the path is the same relative to the app's executable in every package:
| Package | App | praeco |
|---|---|---|
| pacman, deb, rpm | /usr/bin/myapp |
/usr/lib/myapp/praeco |
| AppImage | usr/bin/myapp in the image |
usr/lib/myapp/praeco in the image |
| Tarball | myapp-1.2.0/bin/myapp |
myapp-1.2.0/lib/myapp/praeco |
In each case praeco is at <directory of the executable>/../lib/myapp/praeco, which
is what the C++ examples above and below use. Look nowhere else, and when the file is
missing (a source build, say) hide the update UI rather than search for one.
Putting it into a package. Download a release's static binary and check it against
its .sha256 file, which needs no Rust toolchain:
v=0.4.0; arch=$(uname -m) # x86_64 or aarch64
base=https://github.com/jrimmer/praeco/releases/download/v$v
curl -fLO "$base/praeco-linux-$arch" -O "$base/praeco-linux-$arch.sha256"
sha256sum -c "praeco-linux-$arch.sha256"
install -Dm755 "praeco-linux-$arch" "$pkgdir/usr/lib/myapp/praeco"What changed in 0.4.0. Signature checking is part of the binary now, so it grew: the x86_64 download is 7.7 MB (5.9 MB on aarch64), against 3.2 MB (2.8 MB) for 0.3.1. It is still one static file with nothing to install beside it, and there is no separate lean build. If the size matters and your app is written in Rust, the library can be built without signature checking, see Rust apps using the library. Building from source now needs Rust 1.93 and a C compiler, see Building praeco from source.
praeco is a static-pie binary. Editing it with patchelf (for example
patchelf --set-rpath '$ORIGIN' praeco) exits 0 and reports nothing, but leaves a
file that crashes with a segmentation fault as soon as it starts. The damage only shows
at runtime, so the exit code of the patchelf step tells you nothing. This was reproduced
with patchelf 0.18.0 on every praeco release from 0.1.1 to 0.4.0, so it is a property of
static-pie files and not of one praeco version. A copy that was only copied, or only
stripped, runs normally: strip is safe, so do not blame it.
This matters for AppImages because linuxdeploy runs patchelf (it logs
Setting rpath in ELF file ... to $ORIGIN) on every ELF file in the AppDir, praeco
included. praeco has no shared libraries, so the rpath is useless to it, and the result
is an app whose updater cannot start. Packages that do not go through linuxdeploy
(pacman, deb, rpm, tarball) are not affected, unless your tarball is built from the same
patched AppDir.
The symptom is a silent crash: praeco --version prints nothing and the shell reports
Segmentation fault. If your build discards the output of the check, you will see only
that.
Whatever builds your AppImage, make sure the praeco inside is the file you verified. Put it back after linuxdeploy has finished, compare it with the download, and pack the image with a step that does not run linuxdeploy (and so patchelf) again:
# after linuxdeploy has finished with the AppDir
install -Dm755 "praeco-linux-$arch" AppDir/usr/lib/myapp/praeco
cmp "praeco-linux-$arch" AppDir/usr/lib/myapp/praeco
AppDir/usr/lib/myapp/praeco --version # must print "praeco <version>"
# then, for example: linuxdeploy-plugin-appimage --appdir AppDirAn app that ships praeco has packed its AppImage this way, and restored praeco the same
way for its tarball; both passed a praeco --version check on ubuntu:24.04 and
debian:trixie. That is one passing CI run, not a long record.
Do the --version check on the finished image too (--appimage-extract, then run praeco).
A praeco --version run belongs in every package's smoke test, whatever the format: a
praeco that does not start gives your users no error, the updater just never works.
From 0.4.0 each praeco release carries a packslip, packslip.sigstore.json, signed by this
repository's release workflow. The checksum above catches a damaged download; the
signature also shows that the file was built by that workflow and not swapped by someone
who could upload to the release. Check it in the packaging script, with the packslip
command-line tool (cargo install packslip; see packslip's documentation
for other ways to get it):
curl -fLO "$base/packslip.sigstore.json"
packslip verify packslip.sigstore.json --artifact "praeco-linux-$arch"It prints ok: github.com/jrimmer/praeco, the version and the signing workflow, and exits
0. Any other result means the file must not be shipped. Keep the file name as published:
packslip matches the file by name. The bundle covers both architectures, so the same file
verifies either binary.
git clone --depth 1 --branch v0.4.0 https://github.com/jrimmer/praeco.git
(cd praeco && cargo build --locked --release)
install -Dm755 praeco/target/release/praeco "$pkgdir/usr/lib/myapp/praeco"You need Rust 1.93 or newer (up from 1.85 before 0.4.0, which is what packslip requires)
and a C compiler: the signature check uses a cryptography library that cargo compiles
from its C source. The release binaries are built for the -unknown-linux-musl targets,
which is what makes them static; that needs musl-tools, and a normal glibc build is fine
for a package that carries its own dependencies.
For an Arch package built with makepkg, add options=(!lto) to the PKGBUILD. makepkg
turns on link-time optimisation for C code by default, and with it the link fails with
undefined aws_lc_* symbols (the signature check's cryptography library), or undefined
ring_core_* symbols in a build without signatures. Without LTO both build. --no-default-features
leaves the signature check out, which makes the binary about 3 MB again and the build
much shorter (79 crates instead of 169), at the price of verifying every release by
checksum alone.
Rust apps add praeco from crates.io (cargo add praeco) and bump the version the same
way:
[dependencies]
praeco = "0.4"
# Without signature checking, and without the 90 or so extra crates it brings
# (a C compiler is then not needed either):
# praeco = { version = "0.4", default-features = false }The default build checks signatures. A Rust app that wants the terminal fallback still
ships the praeco binary at the path above, because terminal mode runs the CLI.
An app whose releases carry a packslip gets signature checking from every praeco, with nothing to configure in the app and nothing for the user to do. The first praeco that sees a signed release remembers the signer, and from then on a release of that app without a valid signature is refused (see Signed releases). Signing is done in the release workflow on GitHub, with packslip's action, and uses the workflow's own identity, so there is no key. This is the shape praeco's own release workflow uses: create the release as a draft, sign, attach the bundle, then publish.
permissions:
contents: read
jobs:
build: # your existing job: build and upload each file as an artifact
# ...
release:
needs: build
runs-on: ubuntu-24.04
permissions:
contents: write
steps:
- uses: actions/download-artifact@v4
with: { path: dist, merge-multiple: true }
- env:
GH_TOKEN: ${{ github.token }}
run: gh release create "$GITHUB_REF_NAME" --repo "$GITHUB_REPOSITORY" --draft --generate-notes dist/*
sign:
needs: release
runs-on: ubuntu-24.04
permissions:
contents: read
id-token: write # the keyless signature
attestations: write
steps:
- uses: actions/download-artifact@v4
with: { path: dist, merge-multiple: true }
- uses: jdx/packslip@44e50e5f64551234b4a382d991bd7f7f7d021d06 # v1.11.3
id: packslip
with:
artifacts: dist/myapp-linux-x86_64 dist/myapp-linux-aarch64 # every file an update may install
bin: myapp
upload: false
- uses: actions/upload-artifact@v4
with:
name: packslip-bundle
path: ${{ steps.packslip.outputs.bundle }}
if-no-files-found: error
publish:
needs: sign
runs-on: ubuntu-24.04
permissions:
contents: write
steps:
- uses: actions/download-artifact@v4
with: { name: packslip-bundle, path: packslip }
- env:
GH_TOKEN: ${{ github.token }}
run: |
gh release upload "$GITHUB_REF_NAME" packslip/packslip.sigstore.json --repo "$GITHUB_REPOSITORY"
gh release edit "$GITHUB_REF_NAME" --repo "$GITHUB_REPOSITORY" --draft=falseThings to get right:
- Pin the action to a commit, as above. Its code decides what gets signed.
- List every file praeco may install. praeco matches the file it downloaded to the bundle by name, and refuses a file the bundle does not list. A package or AppImage added to the release by hand after signing is not in the bundle, so praeco will not install it. Build everything in the signing run, or leave it out of what users update to. The example describes plain executables; for packages, AppImages and archives see packslip's documentation for how to describe each file.
- Keep one bundle per release, named
packslip.sigstore.json. praeco looks forpackslip*.sigstore.jsonamong the assets. - Never publish before the bundle is attached. A release that is public without its signature fails every update of an app praeco has seen signed, until the file appears. The draft-first order above prevents that, and if signing fails the draft simply stays invisible.
- Only github.com repositories are checked. A project on Forgejo or GitHub Enterprise keeps the checksum check whether or not it signs.
What a signature does and does not prove is in Security.
On startup, now and then, and on "Check for updates":
QProcess p; // praeco: the full path of the binary you ship, as above
p.start(praeco, {"check", "--github", "you/myapp", "--current", APP_VERSION,
"--exe", QCoreApplication::applicationFilePath(), "--json"});
p.waitForFinished(20000);
auto doc = QJsonDocument::fromJson(p.readAllStandardOutput()); // always valid JSON with --jsonShow the pill only when update_available is true and latest is not the version
the user chose to skip. Use install.supported to decide whether the sheet offers
Install or only a link to releases[0].url.
To install, run praeco install --detach as described in
Launching praeco from an app with --version set to the
latest from the check, and drive a progress bar from the downloading events
(bytes/total) in the progress file. The command after --restart -- is
applicationFilePath() plus its arguments (for an AppImage, the APPIMAGE path). On
needs_terminal, run the same command again with --mode terminal. Let SIGTERM quit the
app cleanly when the restart comes, and show message text as is.
use praeco::{check, CheckOptions, InstallOptions, Mode, RestartSpec, Source};
let src = Source::github("you/myapp")?;
// Blocking: run on a background thread.
let result = check(&CheckOptions::new(src.clone(), env!("CARGO_PKG_VERSION")))?;
if result.update_available {
// show the pill and the sheet from result.releases
}
let exe = std::env::current_exe()?;
let mut opts = InstallOptions::new(src, "1.2.0", &exe);
opts.mode = Mode::Dialog;
let restart = RestartSpec::new(Some(std::process::id()), vec![exe.into()]);
praeco::update(&opts, Some(&restart), &mut |event| { /* forward to the UI */ })?;praeco::update sends SIGTERM to the PID in the RestartSpec, which is your own
process here, so use it from a process that can survive that (or handle SIGTERM
gracefully). An app that wants to do its own shutdown can instead pass None as the PID,
or call praeco::install alone, then quit and relaunch with
praeco::restart::launch_detached. If the app itself must exit for the new version to
start and cannot outlive the update, use the CLI with --detach instead.
Terminal mode starts the praeco executable inside a terminal (it locates itself
with std::env::current_exe), so a library user that wants the terminal fallback
should ship the praeco binary and run the CLI for that case.
praeco supplies the data; the UI belongs to the app:
- A pill near the version number or title bar when
update_availableis true: "Update 1.0.6". - A "What's new" sheet opened from the pill, listing
releasesnewest first (version, date, rendered Markdownnotes). - Buttons: Install / Later / Skip this version. Install runs the install command
(progress from the events, then the app restarts). Later closes the sheet and asks
again at the next check. Skip this version stores
latestin the app's settings and hides the pill until a newer version appears.
All blocking; run it on a worker thread.
| Item | Purpose |
|---|---|
Source::github, Source::forgejo |
Where releases come from |
check(&CheckOptions) -> CheckResult |
The check, as in check --json |
detect(&Env, &Path) -> Detection |
How an executable was installed |
InstallOptions, install(...) |
Download, verify, install; progress through a callback |
update(&InstallOptions, Option<&RestartSpec>, &mut FnMut(&Event)) |
Install in either mode, restart, finish with done |
signed::plan, signed::Store |
The signature check and the remembered signers (feature signed, on by default) |
Env |
Everything praeco reads from the machine (PATH, APPIMAGE, uid, /proc root, ...), replaceable in tests |
InstallOptions::escalation |
Replaces pkexec/sudo (an argv prefix) |
Errors are praeco::Error { code, message }; code.as_str() is the string the CLI
prints.
What is trusted:
- HTTPS to the release source. Certificates are checked against the bundled
Mozilla root set (rustls with
webpki-roots). HTTP is refused, except to a loopback address when the configured source is itself a loopback HTTP address (tests, local mirrors): a remote server cannot redirect praeco tohttp://127.0.0.1. Redirects are followed by hand, one hop at a time, and every hop must be HTTPS. - The repository's release. The release list from the configured source says
which files exist. Only URLs from that asset list are downloaded, and they must be
HTTPS URLs on the source's own host under that repository's release-download path
(
/owner/repo/releases/download/, anchored at the start of the path; Forgejo's legacy/attachments/<id>URLs only when that exact URL is in the release's asset list; GitHub's CDN redirects are followed from there). A release that lists an asset anywhere else is refused before any request is made. - The checksum published with the release. The file must match every checksum
source that mentions it (
<asset>.sha256,SHA256SUMS), and at least one must exist. Missing, unreadable or mismatching means failure, and nothing is run.
What is not trusted or not done:
- A packslip signature, when the release has one (GitHub only). The signature is made by the repository's release workflow and recorded in a public transparency log (Sigstore's Rekor). praeco checks it against the repository's immutable ID and holds later releases to the same signer, so a mirror or CDN cannot swap the file, a release or upload token alone cannot publish a build, and a signed project cannot quietly fall back to unsigned releases. What it does not prove: that the workflow itself was uncompromised. Anyone who can change and run the repository's release workflow can still get a bad release signed, and praeco cannot tell. It also does not say a release is the newest, or that it was not withdrawn.
- The checksum published with the release, for releases without a signature. The checksum comes from the same place as the file, so it catches corruption and a tampered mirror or CDN, but not a compromised repository or release account: anyone who can publish a release can publish a matching checksum. Forgejo and GitHub Enterprise sources are in this group.
- praeco does not check that the requested version is newer than the installed one (the app decides), or what is inside a package.
Privilege handling:
- Only the package manager runs elevated, on a verified file. praeco itself
never runs as root unless you start it that way. The elevated process is
pacman,apt-get/dpkgordnf/rpmwith the arguments listed above. praeco never executes anything it downloaded, and never runs a script or a shell. - Privileged programs are not looked up on the user's
PATH.pkexec,sudoand the package managers come from/usr/bin,/usr/sbin,/binand/sbinonly, as absolute paths of files owned by root and not writable by group or others, and run with a cleared environment and a fixedPATH. Apacmanorsudoplanted in~/.local/bin(or reached through an emptyPATHentry) is never used. The only way to change this is thePRAECO_TRUSTED_DIRSvariable, which exists in debug builds only. - Right before handing the file to the elevated command, praeco hashes it again and
refuses to continue if it changed since verification. The file lives in a
0700directory only the user can write to; a process already running as the same user could still swap it in the last instant, which is the limit of what a user-owned file can promise. - Downloads go to a fresh private temp directory that is removed afterwards.
- AppImage installs run as the user and replace one file: the AppImage itself (at its
real path). Tarball installs run as the user and write only below the app's own
folder, which is never your home folder, its parents, or
/; entries outside it, unsafe paths, and decompression bombs are refused (details above). PRAECO_ESCALATION_CMD(replaces thepkexec/sudoprefix) andPRAECO_TRUSTED_DIRSexist only in debug builds, for the test suite. Release builds ignore them.- An optional API token is sent only to the API host and is never put on a command line.
- Linux only.
- The tarball install needs the archive to contain the app's executable under the same file name, and does not delete files that a newer version no longer ships.
- The polkit-agent probe is a heuristic (see above); pkexec's exit codes catch what it misses.
- Terminal mode does not forward
PRAECO_TOKEN.APPIMAGEandAPPDIRare passed explicitly, since some terminals (gnome-terminal's server) do not inherit the environment. - Private repositories are not supported: asset downloads carry no credentials.
- Only the first page of releases is read.
update-allreads versions by running each app's version command; it does not restart apps, and registrations are removed only bypraeco init --remove.- The system hook exists for Omarchy only.
- No delta updates, no rollback.
- Signatures are checked only for packslip-signed releases on github.com.
cargo build --release # target/release/praeco
cargo test # offline, no root
cargo clippy --all-targets
cargo test --test signed_live -- --ignored # needs the network: a real signed releaseSignature checking is the signed feature (on by default). It brings in the packslip
crate and what that needs: Rust 1.93 or newer, a C compiler for its crypto, and a
larger build (169 crates instead of 79, a 7.7 MB static binary instead of 3.2 MB).
--no-default-features leaves it out and every release is verified by checksum alone.
Packagers: see Building praeco from source for the
makepkg flag.
The tests need neither network nor root. They use a fake release server bound to
127.0.0.1, fake pacman/dpkg/rpm/apt-get/dnf/pkexec/sudo shims on a
private PATH, a recording escalation command that proves the exact package-manager
argv without running it, a fake /proc for the polkit probe, a fake APPIMAGE, and
dummy child processes for restart.
praeco's signed releases are packslip's work, and
a large part of what 0.4.0 can promise comes from it: the manifest format, the Rust
crate that verifies it offline against Sigstore's public records, the GitHub Action that
signs praeco's own releases, and the policy that makes a project's name say who may sign
for it. The test suite checks a real bundle from jdx's hk release that ships in the
packslip repository (see tests/fixtures). Thank you to the packslip authors and
contributors, and if you ship software, go and look at what it can do for your own
releases at packslip.dev.
MIT, see LICENSE.