Nia documentation · 4.0.0
Apps and PWA
Install Nia as a web app or download the matching Windows, Android and Debian clients from inside your instance.Nia can run as a normal website, an installable Progressive Web App (PWA), or a native client. Native clients contain their own app UI and connect to your self-hosted server for login, API access and synchronization.
Open the app installer
Open your Nia instance in a regular browser and select Download apps:
- Before signing in: below the login form
- After signing in: at the bottom of the left sidebar, below the version information
This opens the app installer with the downloads included in your server release. It also displays the server address you need when starting a native client for the first time.
When the button is not visible
The Download apps button is shown only when all of the following are true:
- Nia is open in a normal browser, not already running as a PWA or native app
- the server release contains a valid native-app download manifest
- at least one verified client artifact is available
Development/source builds and release builds created without native artifacts can legitimately have no app downloads. In that case, the button remains hidden. Use a published full server bundle or published Docker image if you need the bundled clients.
Available native clients
Published releases can provide these builds:
| Platform | Package | Architecture |
|---|---|---|
| Windows | Setup .exe |
x64 |
| Android | Sideloaded .apk |
arm64 |
| Debian/Ubuntu desktop | Desktop .deb |
amd64 |
There is currently no native client for iOS, iPadOS or macOS. Use the PWA on those platforms.
Windows
Download and run the Windows setup from the in-app installer. The desktop client supports native notifications, local reminder scheduling, tray integration, global hotkeys, native attachment downloads and Windows passkeys.
Android
Download the APK from the in-app installer. Android may ask you to allow installation from the browser or file manager used to open it.
The Android client supports native notifications, local reminders, location-based reminders and passkeys through Android Credential Manager. Location reminders can be created and managed elsewhere, but only the Android app currently triggers them based on the device location.
Debian or Ubuntu desktop
Download the desktop package, then install it locally:
sudo apt install ./nia-todo-desktop-vX.Y.Z-debian-amd64.deb
The Debian desktop client supports native notifications, local reminders, tray/autostart settings, global hotkeys, OIDC return handling and native attachment downloads. Native passkeys are not currently supported in the Debian client; use TOTP, recovery codes or another available login method.
The desktop client package is separate from the Nia server package. Installing the desktop package does not create or host a server.
Connect a native client
On first launch, enter the server address shown in the app installer, for example:
https://todo.example.com
The client verifies the address through the public instance endpoint before saving it. For a remote server, the URL must use HTTPS and must not contain credentials, query parameters or fragments. Plain HTTP is accepted only for local loopback development.
Use the same origin configured as the server’s Public base URL. This is especially important for OIDC and passkeys.
Modules across devices
Tasks, Shopping and Recipes use the same account and navigation. Settings → Modules changes which modules are visible on all of that account’s devices. Personal workspaces and their dashboard belong to Tasks; Shopping lists and cookbooks do not use the Tasks workspace boundary.
Use a client build that matches the server release when evaluating V4. An older client does not gain new modules just because its server was upgraded; update the native client as well.
Synchronize Tasks dashboard preferences
Dashboard personalization is stored locally by default, so each browser or app can keep its own layout. From version 3.3.1, you can optionally enable Synchronize via my account in the dashboard customization dialog.
The switch applies to the whole account on the current Nia instance. The actual dashboard configuration remains separate for each workspace and is synchronized between compatible web, PWA and native clients. When synchronization is enabled for the first time, the current device uploads its local configuration. Later changes are stored locally for offline use, sent to the server when possible and distributed to other open clients in real time.
Disabling synchronization removes the server copy but keeps the current local configuration on the device. Clients older than 3.3.1 continue to use their local dashboard layout; they ignore the new real-time update and cannot overwrite the synchronized server configuration.
Work offline
Web and PWA clients cache the app shell after a successful online load. Native clients bundle that shell. Synchronized content and pending changes are stored in IndexedDB for the current account and server.
V4 supports offline work with accessible Tasks content, Shopping lists and cookbooks/recipes that have been synchronized to the device. This includes Tasks comments and subtasks, Shopping item changes and recipe edits. Recipe-to-shopping transfers can be queued offline and submitted on reconnect. Changes survive reloads and are retried without intentionally duplicating a completed operation.
Offline availability depends on what the device has already loaded. Tasks attachment uploads, previews, downloads and removal require a connection. Recipe images are available offline only after they have been cached. Recipe link imports, BrainDump and changes to access/sharing require the server. A new device cannot discover uncached content while offline.
On reconnect, Nia checks the current server state. Revoked access or deleted content can prevent a queued change from being applied; cached content is removed when that loss of access is known. Do not clear browser/app storage or uninstall the client while unsynchronized changes remain. Signing out also clears account-specific cached data.
Install the PWA
The PWA runs the web client in a standalone window and keeps the offline-capable app shell plus its local IndexedDB synchronization queue. It is the recommended option when no native client exists or when you do not need platform-specific features.
Chromium browsers
Open Download apps and choose Install web app when the browser offers installation. Depending on the browser, the same action can also appear as an install icon in the address bar or under Install app in the browser menu.
iPhone and iPad
There is no native iOS app. Open Nia in Safari, select Share, then Add to Home Screen. The in-app installer shows this flow step by step on iOS and iPadOS.
Feature differences
- Browser/PWA uses Web Push where supported.
- Native clients use platform notifications and local reminder scheduling.
- Location-triggered reminders require the Android client.
- Native passkeys are supported on Windows and Android, but not currently in the Debian client.
Client updates
V4 servers require native clients 4.0.0 or newer. A client below the server’s effective minimum receives a required update rather than a dismissible update notice. Publish matching Windows, Android and Debian client builds before upgrading a server that enforces the new floor. An older stored minimum cannot lower the V4 source floor; a higher configured minimum is preserved.
Native clients regularly read the download manifest from their configured server. When that server includes a newer build for the current platform, Nia displays an update dialog with the matching download.
From version 3.4.0, the Windows, Debian and Android clients can start verified updates directly from this dialog:
- Windows: Nia verifies the signed updater, installs it in place and restarts the desktop app.
- Debian or Ubuntu: Nia verifies the package checksum and release signature, then asks for administrator authorization before installing the package and restarting the desktop app.
- Android: Nia verifies the APK download and signing identity before opening Android’s package installer. The first update can require permission to install apps from Nia; the app opens the relevant system setting and continues after you return. Android still requires you to confirm the installation. When you return from the installer, Nia checks the installed app version and reports a cancelled or unsuccessful installation instead of treating the installer launch as success.
The native updater accepts only artifacts published by the configured Nia server for the current platform. If a release does not contain the required updater metadata, the dialog falls back to the normal external download flow. If a native download, checksum, signature, authorization or installation step fails, Nia displays the error and restores the update action so you can retry; it does not automatically switch to an external download after a failed native update.
Once the release contains the matching client artifacts, update the server so it can serve them to native clients. Use Download apps in a regular browser for fresh installations; existing native clients discover the new release automatically and must install it when below the server’s minimum.