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:
- Local → Shared: Moves the config file or directory into
<storage>/zapps/configs/<app>/<config>and replaces the original path with a symlink. - Shared → Local: Replaces the symlink with a local copy while leaving the shared copy intact for your other devices.
- Conflict resolution: If both a local config and a shared config already exist, zapps prompts you to pick Use Shared or Keep Local and saves a timestamped backup under
zapps/backups/before replacing anything.
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:
| Tool | Description |
|---|---|
list_apps | List catalog and custom apps with install & cross-device status |
get_app | Inspect methods, dependencies, and config sync state for one app |
install_app | Install an app (and any missing dependencies in topological order) |
uninstall_app | Uninstall an app via its configured package manager or runner |
list_devices | List all synced PCs and their installed software |
get_config_status | Check symlink sync status of an app's config paths |
set_config_mode | Switch a config path between local and shared |
list_notes | List synced notes and encryption status |
read_note | Read a note (supplying password when encrypted) |
save_note | Create or update a plain or password-encrypted note |
delete_note | Remove a note from synced storage |
6. CLI Flags
zapps [--mcp] [--catalog <path>] [--storage <dir>] [--config <path>]