appjail

A small command-line manager for AppImages that runs every app inside a bubblewrap sandbox. It works in user mode (no sudo), supports GUI apps under Wayland, and treats the software you install as untrusted.

appjail is young software: read the limits before relying on it.

Why

Package managers for AppImages typically download a release and run it with your full privileges. appjail is built around the opposite assumptions:

• Declarative manifests, no remote code. An app is a small TOML file: source, pinned hash, permissions. Nothing fetched from the network is ever executed or sourced, and appjail has no self-update.
• You name the source. You give a GitHub owner/repo, or an AppImage file or URL yourself. That is the only place the app is fetched from, whatever an AppImage's embedded update information says.
• Downloads are jailed. The download, the extraction and the verification tools run in throwaway sandboxes with only the access they need (a private network namespace for downloads, none for extraction).
• Everything is denied by default. An app starts with a private home and a restricted Wayland socket. Network, directories, D-Bus names, portals and the rest are explicit grants you can inspect and change.
• Updates are reviewed. A new release waits in quarantine (7 days by default), is shown to you as a diff, and is blocked outright if its evidence gets weaker or the repository changes owner.

Requirements

• Linux on x86-64 with unprivileged user namespaces. Tested on Debian 13 and Ubuntu 26.04; older systems are not supported.
• Python 3.12 or newer (tested with 3.13 on Debian 13 and 3.14 on Ubuntu 26.04; 3.12 is the declared minimum and is not run by the tests). appjail uses only the standard library.
• bubblewrap and squashfs-tools (unsquashfs) are required.
• Recommended: passt (the pasta command) for apps with network access, xdg-dbus-proxy for D-Bus filtering, xwayland for X11-only apps, git for the manifest history and the search index.
• A Wayland compositor for GUI apps. Apps that need X11 run on a private Xwayland inside their own sandbox; the host X11 socket is never shared.

On Debian or Ubuntu:

sudo apt install bubblewrap squashfs-tools passt xdg-dbus-proxy xwayland git

Install

appjail is a Python package with no dependencies. Install it as a command with pipx or pip:

pipx install appjail    # or: pip install --user appjail
appjail --help

Or from a clone (pip downloads only the build backend, Hatchling):

git clone <repository-url> appjail
cd appjail
pipx install .          # or: pip install --user .
appjail --help

To try it without installing, run it from the clone: PYTHONPATH=src python3 -m appjail --help. appjail never updates itself: upgrade with pipx upgrade appjail (or git pull and reinstall) after reading what changed.

Data lives in ~/.local/share/appjail (images, extracted trees, private homes, staging) and ~/.config/appjail (manifests, tracked in a small local git repository). APPJAIL_DATA_DIR and APPJAIL_CONFIG_DIR override them.

Quick start

appjail add skyjake/lagrange     # review the repository, pick the asset, download, pin, extract
appjail run lagrange             # run it in its sandbox
appjail list                     # installed apps, tiers and permissions
appjail update                   # check every app for a newer release
appjail remove lagrange          # delete the app and its private home

add also takes --tag TAG (a specific release instead of the latest), --name, --prerelease, and the permission options below at install time (--allow, --dir, --dbus, --dbus-own, --portal, --display xwayland, --no-audio, --no-gpu). run takes --dir PATH[:ro|:rw] and --file PATH[:rw] for one run only, and passes everything after -- to the app (appjail run lagrange -- --help). remove and perms ask for confirmation unless given --yes.

add shows the repository owner, account age, stars and fork or archive status before it downloads anything, and asks if several release assets match. By default an app gets audio and GPU access and nothing else.

Apps that are not GitHub releases. Give the AppImage itself:

appjail add --file ~/Downloads/Tool-x86_64.AppImage [--name tool] [--sha256 HEX]
appjail add --url https://example.org/dl/Tool-x86_64.AppImage [--name tool] [--sha256 HEX] [--max-size MIB]
appjail update tool --file ~/Downloads/Tool-new.AppImage       # an app added from a file

Nothing identifies who published such a file, so these apps are tier 5 (trust on first use) or tier 4 when you pass the hash the publisher gives with --sha256 (a mismatch aborts). A URL must be https and is downloaded in the jail (1 GiB at most unless --max-size); redirects may go to any host, and a redirect through plain http asks for an extra confirmation unless --sha256 matches. update of a URL app asks the server first with a conditional request and a few small range requests, and downloads the whole file only when something changed.

Permissions

appjail perms lagrange                              # show
appjail perms lagrange --allow network              # outbound network only (see below)
appjail perms lagrange --add-dir ~/Documents:rw     # a directory, read-only unless :rw
appjail perms lagrange --add-dbus org.example.Name  # talk to one session-bus name through a filtering proxy
appjail perms lagrange --add-dbus-own org.example.Name  # own a session-bus name (MPRIS player, single instance)
appjail perms lagrange --allow portals              # desktop portals (file chooser, notifications, ...)
appjail perms lagrange --deny network --rm-dir ~/Documents   # take grants back (also --rm-dbus, --rm-dbus-own, --rm-portal)
appjail portals lagrange                           # files it was granted through the file chooser
appjail portals lagrange --revoke-all               # take those grants back (also --revoke DOC_ID)
appjail run lagrange --file ~/report.pdf            # one file, for this run only

Giving one file. run --file PATH (add :rw to allow writing) makes just that file visible, not the rest of its directory, and appends its path inside the sandbox to the app's arguments. It applies to that run only and is never saved in the manifest; for a standing grant use a directory, or portals and the file chooser. Credentials, browser profiles and the like are refused as for directories, and shell startup files are never writable. Apps that save by writing a temporary file and renaming it fail on :rw.

Every sandbox also drops all capabilities, has its own PID, IPC and UTS namespaces, a read-only system, a minimal /dev, a generated /etc/passwd, and a seccomp filter. The extracted app tree is hashed and checked at every launch.

How trust works

Each app is pinned by hash and carries an evidence tier that update will never silently lower:

Tier 2 (GPG signatures) is not implemented. Most AppImages will land on tier 3 to 5, which proves "unchanged" (and, for GitHub, "from the same account"), not "safe". update APP --sha256 HEX earns tier 4 for a tier 5 app when the hash matches, and a tier 4 URL or file app refuses new content that comes without one.

appjail update re-resolves the pinned repository, downloads the candidate in the jail, verifies it, and shows you the version, the hashes, the tier and the release link. A release must be seen for the quarantine period before it can be installed (--quarantine DAYS). For tier 4 apps appjail records the candidate's hash when it is first seen and refuses the install if the content changed in the meantime. A change of repository owner or a drop in tier blocks the update. --channel stable|prerelease|pinned chooses which releases an app follows.

What update prints per app: up to date; waiting (a candidate was seen and its quarantine has not ended: run update again later, it needs no action); blocked (the owner changed, the evidence got weaker, or the content changed during the quarantine: nothing was installed and the message says why); declined (you answered no); pinned (the app follows no releases). The exit status is 1 if any app was blocked or failed. A URL app's candidate is kept on disk during the quarantine and installed from there (--verify downloads it again first); a file app has no quarantine, you hold the bytes.

Searching

search looks through catalogs: lists of apps with, where known, the GitHub repository each one comes from. A hit is only a suggestion; installing is always appjail add owner/repo (or --file/--url), after you have checked the owner. Catalogs are untrusted data: appjail parses them strictly, strips terminal escape sequences from every text, and never runs anything from them.

appjail index update                  # refresh every catalog: fetch, show what changed, ask before accepting
appjail index status                  # the sources, their revisions and update times
appjail index rollback [NAME]         # back to the previous catalog of a source (default: am)
appjail index add mine --url https://example.org/apps.json    # another catalog (https; fetched in the jail)
appjail index add local --file ~/apps.json                    # or a local file
appjail index update mine             # refresh one source (--commit SHA is for am only)
appjail index remove mine
appjail search editor                 # all sources; with several, each hit shows its source in brackets

search shows 20 results; use --limit N or --all for more.

Sources. The built-in am source is the AM application list: index update fetches its repository in a network-only jail (only the list and the install scripts, no hooks or submodules), reads each script as text to find the SITE= line, and keeps the result as a catalog. The scripts themselves are not kept. Sources you add yourself provide a catalog directly. Every update shows the number of apps, the apps added and removed, and every app whose repository changed, with a loud warning when the owner changed, and asks before it replaces the catalog. One previous catalog is kept per source for index rollback.

Catalog format. One UTF-8 JSON document, at most 16 MiB and 50,000 apps:

{
  "format": "appjail-catalog",
  "version": 1,
  "origin": "https://example.org/my-apps",
  "revision": "2026-10-22",
  "apps": [
    {"name": "lagrange", "description": "A Gemini browser", "source": "skyjake/lagrange"},
    {"name": "tool", "description": "Hosted elsewhere", "note": "resolve manually: https://example.org/tool"}
  ]
}

Unknown keys are errors, so a catalog means the same thing to every version that accepts it. A catalog that breaks a rule is refused as a whole and nothing changes. appjail writes the catalog it validated, not the downloaded bytes. Sources are listed in ~/.local/share/appjail/index/.

Command reference

appjail COMMAND --help lists every option.

Other commands

• appjail history [app] [--limit N]: every change to the manifests, from the local git repository. appjail run warns if a manifest was edited outside appjail.
• appjail tools status|install NAME: helper binaries whose URL, size and hash are pinned in appjail's source (gh for attestations, dwarfs for DwarFS-based AppImages).
• appjail desktop NAME [--mime TYPE]... [--mime-all] [--rw] (also add --desktop): a menu entry that starts the app through appjail, generated by appjail (the AppImage's own .desktop is never used). File types are opt-in: only the ones you pick show under "Open with", and appjail never makes the app a default. Opening a file passes just that file to the app, read-only unless --rw (appjail open NAME -- FILE...). --remove and --prune delete entries; remove does it too.
• appjail version (or --version): the installed version. It comes from the git tag at build time (0.2.0 on a release, 0.2.1.dev4+g1a2b3c4 four commits after it); it prints unknown when run from a source tree that is not installed.
• Set GITHUB_TOKEN to raise the GitHub API rate limit. It is only ever sent to api.github.com.

Troubleshooting

Limits

• Not audited, not a security boundary you should bet on yet. bwrap and the Linux kernel do the isolation; appjail configures them conservatively but has had no external review.
• Releases are resolved on GitHub only. Apps hosted elsewhere appear in search and can be added with --url or --file, but then nothing identifies the publisher (tier 5). The cheap update check for URL apps detects a new version; a change confined to bytes it does not sample, with the same size and validators, is only seen by a full download.
• A sandboxed app can still do whatever its grants allow. An app with network can reach other machines on your LAN.
• Granting a directory, a portal or a D-Bus name widens what a compromised app can do.
• x86-64 only. The GNOME and KDE portal backends have not been tested (the GTK backend and a real X11-only AppImage have, under headless weston; the portal dialogs themselves are not driven). Real internet IPv6 under pasta is untested; IPv6 forwarding is tested in a fake network.
• Stopping appjail run with SIGINT, SIGTERM or SIGHUP stops the whole jail, including pasta. If appjail is killed with SIGKILL, an app with network is stopped about a second later by a watcher inside its network namespace (a small empty directory appjail-life-* stays in the runtime directory).
• The audio permission includes the microphone.

The full design, the reasoning behind each choice and the verification notes are in DESIGN.md.

Development

The code is stdlib-only Python under src/appjail/; tests are plain pytest. Many tests start real sandboxes and need a Linux machine with bubblewrap, unsquashfs, pasta, a headless Wayland compositor (weston) and the other packages in tests/vm/packages.txt.

APPJAIL_INTEGRATION=1 python3 -m pytest

Without APPJAIL_INTEGRATION=1 the tests that need real sandboxes are skipped. Tests that download from the network are opt-in (APPJAIL_E2E=1, APPJAIL_LIVE=1). The project's own workflow runs the suite inside a disposable QEMU guest built from tests/vm/ (create.sh, start.sh, provision.sh, test.sh) so that downloads and sandboxed apps never run on the developer's machine. GitHub Actions runs the full suite and a REUSE compliance check on every push, and a separate workflow runs every opt-in suite (real downloads) on demand and weekly.

License

MPL-2.0. The repository follows the REUSE specification.