Documentation

How zapps organizes your storage folder, symlinks configs safely, encrypts notes, and exposes an MCP server.

1. Cloud Storage & Per-Device Sync

On first launch, zapps scans for local cloud-synced folders including Dropbox (reading ~/.dropbox/info.json and ~/Dropbox), MEGA, Nextcloud, OneDrive, Google Drive, Syncthing, pCloud, Proton Drive, Koofr, and Tresorit. You can also pick any custom folder (defaulting to ~/zapps).

To prevent cloud sync conflicts, each PC writes only to its own file under <storage>/zapps/devices/<device-id>.json, while reading every other device's file to highlight apps missing on the current machine.

2. Config Symlinking & Conflict Protection

Each app's configuration path can be switched between Local and Shared:

3. AppImage Desktop Integration (Linux)

When installing a kind: "appimage" entry on Linux, zapps downloads the AppImage to ~/Applications/<id>.AppImage, verifies any optional SHA-256 digest, extracts its embedded icon and .desktop metadata, and writes ~/.local/share/applications/zapps-<id>.desktop so it appears in your application launcher right away. Uninstalling removes the AppImage, icon, and menu entry cleanly.

4. Encrypted Notes

Notes are stored as JSON files under <storage>/zapps/notes/. Setting a password on a note derives a 256-bit key using Argon2id (random salt per note) and encrypts the body with AES-256-GCM (binding the note ID as associated data). Plaintext is never written to disk once locked.

5. MCP Server Reference (zapps --mcp)

zapps ships with a built-in Model Context Protocol server over stdio exposing 11 tools:

ToolDescription
list_appsList catalog and custom apps with install & cross-device status
get_appInspect methods, dependencies, and config sync state for one app
install_appInstall an app (and any missing dependencies in topological order)
uninstall_appUninstall an app via its configured package manager or runner
list_devicesList all synced PCs and their installed software
get_config_statusCheck symlink sync status of an app's config paths
set_config_modeSwitch a config path between local and shared
list_notesList synced notes and encryption status
read_noteRead a note (supplying password when encrypted)
save_noteCreate or update a plain or password-encrypted note
delete_noteRemove a note from synced storage

6. CLI Flags

zapps [--mcp] [--catalog <path>] [--storage <dir>] [--config <path>]