Best practices for persistent custom App Store registry deployment via CLI

CasaOS manages its application stores through the casaos-app-management service. By default, it syncs with the official IceWhale store, but you can manage multiple or custom registries natively using the configuration files or the CLI client.

To permanently add or change a registry via the CLI without it being overwritten during a system update, follow these steps:

1. Locate the App Management Configuration

The stores are tracked in the database and configuration files located under /etc/casaos/. Specifically, you can look at:

/etc/casaos/app-management.conf

2. Register the Custom URL via CLI

CasaOS stores its configured store URLs in a local configuration structure. To cleanly inject a custom store URL (like a community-maintained list) via terminal, run:

# Add a custom third-party app store via the app-management CLI tool
casaos-app-management-cli store add https://raw.githubusercontent.com/<username>/<repo>/main/apps.json

💡 Note: Alternatively, users can paste the raw JSON URL directly into the GUI under App Store -> Add Source.

3. Ensuring Persistence Across Updates

Because CasaOS updates preserve user-generated configuration files in /etc/casaos/ and the local storage directory (/var/lib/casaos/), any store added via the official API/CLI or GUI settings will persist across container and service updates. The update process only replaces the binary files and static web assets, leaving your custom configurations completely intact.