Shilling
Shilling is a household budgeting app built with Kotlin Multiplatform. Plan recurring income and expenses, track what cleared, and see what is coming up in a Friday-to-Friday weekly view. It has desktop (Tauri), web, iOS, and Android clients.
The app stores budget data on each device. Optional device sync uses WebRTC peer-to-peer data channels. The server helps peers connect and, in hosted mode, provides authentication and household metadata. It does not store or relay budget entries or receipts. Application data passes through the Store5 repository layer.
Current status
This repository is under active development. The hosted web app is at
app.shilling.finance. For your own installation,
use the self-hosted Docker Compose guide. See the
GA launch plan for known product work
before a stable release.
Try it locally
mise installs everything the build needs at pinned, checksum-verified versions (Node.js, Java, Rust, the Tauri CLI) and runs the project tasks. It doesn't change your system-wide tools.
1. Install mise
curl https://mise.run | sh # or: brew install mise
Optionally, activate it in your shell (for example eval "$(mise activate zsh)" in ~/.zshrc) so node, java and cargo resolve to the project versions whenever you're in the repository. mise run works without it.
2. Clone and run
git clone https://github.com/j1philli/shilling.git
cd shilling
mise trust # allow this repository's mise.toml
mise install # pinned tools from mise.lock
mise run desktop # build the web bundle and launch the Tauri desktop app
Tasks prepare what they need: npm packages are reinstalled whenever package-lock.json changes, and iOS tasks download WebRTC.xcframework. The first build also downloads the Kotlin Toolchain and its dependencies, so it takes several minutes. Run mise tasks to list every task.
| Command | What it does |
|---|
mise run web | Serve the web build at http://localhost:3000 and rebuild on source changes |
mise run ios | Build and launch the native iOS app in the Simulator |
mise run android | Build and install on an emulator; set ANDROID_AVD to your emulator name (default Pixel_9_Pro_XL_API_35) and ANDROID_HOME if the SDK isn't at ~/Library/Android/sdk |
mise run server | Run the signaling server on port 8081 |
mise run sync-proxy | Serve the signaling server over HTTPS on port 8443 |
mise run build-all | Compile every module for every platform |
Development builds use a separate shilling-dev database and dev icons, so they don't touch data from a production install.
Platform SDKs
mise can't install Apple's or Google's SDKs. You only need them for the mobile apps:
- iOS: macOS with Xcode 15 or later and an iOS Simulator runtime.
- Android: Android Studio with the Android SDK 37 platform and an emulator.
mise doctor project checks for both and says what to install.
macOS is the tested development platform. The web, desktop, server and Android tasks are expected to work on Linux once Tauri's Linux prerequisites are installed, but this isn't regularly tested.
Sync between devices
Clients only connect to signaling over HTTPS/WSS, including debug builds and localhost. Run the server and an HTTPS proxy in two terminals:
mise run server # self-hosted mode on port 8081, no Supabase credentials needed
mise run sync-proxy # https://<this machine>:8443 -> the server
sync-proxy creates a certificate with mkcert, trusts its local CA on this Mac (it asks for your password the first time) and in a booted iOS Simulator, and prints the URLs to use. In the app, choose Self-hosted and enter one of them on each device. Real phones and the Android emulator must also trust the printed rootCA.pem; see HTTPS is required for signaling. mise run homelab starts the server, the proxy, the desktop app and the iOS Simulator together.
The self-hosted server does not authenticate household joins; operate it only in an environment where you control access. For optional TURN configuration and hosted Supabase setup, see the server overview and hosted auth guide.
Development
mise run test # architecture guard and JVM tests
mise run guard-architecture # WebRTC, signaling, and Store5 invariant checks
The main modules are app/shared (data and sync), app/shared-ui (Compose UI), the platform apps under app/, core (shared protocol models), and server (signaling and hosted metadata). More details are in the getting started guide and server docs.
Tool versions live in mise.toml. To update one, change it there and run mise lock to refresh the checksums in mise.lock.
Release numbers and the current target publishing status are in the
release guide. Run mise run check-version before tagging.
Contributing
Issues and pull requests are welcome. Read CONTRIBUTING.md before changing sync, server, or data flow code.
For security issues, follow SECURITY.md.
License
Shilling is licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only). If you distribute a modified version or offer a modified version as a network service, the license has source-sharing requirements. Contributions upstream are welcome, but the license does not require a fork to submit a pull request here.
Bundled and inlined third-party components retain their own licenses; see THIRD_PARTY_NOTICES.md.
Optional product analytics is described in the usage analytics privacy notice and analytics setup guide.
