AppImage Configuration

Setting Updates

Shelly supports checking for and installing AppImage updates through two mechanisms:

1. Static URL
2. Repository (GitHub, GitLab, Codeberg, or Forgejo)

---

Static URL

The Static URL option serves as a fallback update mechanism for AppImages that are distributed outside of supported git forge release feeds (GitHub, GitLab, Codeberg, or Forgejo).

When to Use a Static URL

Use a static URL when the upstream project provides a permanent link (“permalink”) that always points to the latest binary. Examples include:

• https://example.com/downloads/app-latest.AppImage
• https://example.com/builds/nightly/app-x86_64.AppImage

The URL remains constant over time, while the binary hosted at that location is updated upstream whenever a new version is released.

No Manual URL Editing Needed

Do not use a Static URL for version-tagged release assets (such as .../releases/download/v1.0.0/app-1.0.0.AppImage). If the application is hosted on GitHub, GitLab, Codeberg, or Forgejo, configure a Repository instead. Shelly will automatically fetch the latest asset without requiring you to update the URL manually for each new release.

How Static URL Update Detection Works

Because a permalink URL contains no version string, Shelly detects updates using HTTP cache validators:

1. HTTP HEAD Request: Shelly sends a lightweight HEAD request to the configured URL without downloading the full binary.
2. Cache Token Inspection: Shelly inspects the HTTP headers, preferring ETag first and falling back to Last-Modified.
3. Metadata Tracking: On a successful update, Shelly records the version embedded in the AppImage (if extractable, for display) and stores the ETag or Last-Modified token as the installed release tag.
4. Update Suppression: On subsequent update checks, Shelly compares the server’s current token against the stored release tag. If they match, the update is suppressed, preventing unnecessary re-downloads of the same file.

---

Repository

Use this option when an AppImage is hosted on a supported git forge (GitHub, GitLab, Codeberg, or Forgejo). Shelly connects directly to the forge’s release API to track new releases and download assets automatically.

You will need the Repo Owner and Repo Name.

For example, to track osu! releases from GitHub:

• Repository URL: https://github.com/ppy/osu
• Value to enter: ppy/osu

Shelly will query the repository and check for updates using the most recent stable release (or the latest pre-release, depending on your configuration).

---

Key Details for Updates

1. Version Matching: Shelly inspects the version defined in the application’s .desktop file and compares it to the latest upstream release.
2. Unknown Versions: If the local version is marked as Unknown, Shelly updates to the latest release and tracks subsequent updates via release tags.
3. Self-Updating Applications: If an AppImage includes its own built-in updater, allowing the application to update itself is often the most reliable method. You can use Shelly’s sync feature to keep your local metadata in sync.

---

Syncing AppImages

You can use the sync feature to align Shelly’s metadata, icons, and binary with the currently installed AppImage. This is especially useful for self-updating AppImages that have updated outside of Shelly.