Qortium Home

Home 2.1.0-beta.13 testing and app development: beta testing guide.

Qortium Home is a desktop and Android application for managing Qortium wallets, running or connecting to a Qortium node, and browsing QDN content from one simple interface.

Qortium Home is focused on account management, QDN browsing, and a browser-like foundation built around account-aware tabs. Prebuilt packages are published at https://github.com/QortiumDev/qortium-home/releases (currently on the prerelease channel). See Status below before using wallets with meaningful funds.

Status

This project is in active early development. Wallet support and QDN rendering are useful for testing, but they have not had a production security review.

Do not use wallets containing meaningful funds in this application until the wallet flows, signing flows, and release builds have been reviewed and tested more broadly.

Current Features

• Wallets — create, load, and export encrypted wallet backups on desktop and Android, derive multiple addresses from one wallet, and keep saved wallets locked after restart with per-session unlock, lock, and remove.
• Node modes — switch between a local node, one saved custom node, and Previewnet network discovery, with a node status dashboard showing sync phase, target height, blocks remaining, and peer counts when Core provides them.
• Managed Core node — install the current Qortium Core prerelease from GitHub into a stable desktop app-data folder, start and stop it, surface its runtime log paths, and check Core's approved on-chain/QDN update status.
• Managed Java runtime — install a Home-managed Java 25 runtime when system Java is missing (any system Java 17 or newer keeps working), with a visible weekly update check and an opt-in automatic Java update setting.
• Managed I2P transport — install and run the i2pd router from QortiumDev/qortium-i2pd with selectable IP/I2P transport modes for the managed Core.
• QDN browsing — explore services, names, and resources from qdn:// URLs in session-only tabs with independent history, a per-tab selected account, read-only node API browsing, and saved bookmarks.
• Document and media viewers — in-app viewers for images, audio, and video; a document reader for PDF, EPUB, plain text, and CBZ/CBR comics; a ZIP/RAR archive browser and a GIT_REPOSITORY branch, commit, and file-tree browser with a plain-snapshot fallback; and code, Markdown, CSV, and JSON views.
• QDN app hosting — APP and WEBSITE resources run in isolated views with the account-aware qdnRequest bridge for read lookups and approval-gated writes (see QDN App Bridge).
• QDN app notifications — apps can show system notifications and register subscription rules with filters that keep working while their tab is in the background, plus app-controlled tab titles for unread counts.
• Self-update — checks GitHub releases on a stable or prerelease channel, downloads and verifies the matching platform asset, installs desktop updates next to the running build, and hands Android updates to the system package installer.
• First-run Welcome setup — a resumable, skippable setup for new installs that helps choose a connection mode, create or import an account, and pick what to explore first.
• App versioning (QAVS) — recognizes the Qortium App Versioning Standard label on QDN apps and websites, shows compatibility badges, and answers GET_HOST_INFO so apps can adapt to the platform version.
• UI styles and languages — Classic, Modern, and Fun display styles, adjustable text size, and translations for more than twenty locales.
• Build targets — Linux x64/arm64 AppImages, macOS DMGs, a Windows x64 portable executable, and Android APK/AAB packages via Capacitor.

Preview Limits

Previewnet network discovery uses public read-only APIs. They are suitable for status checks, peer discovery, QDN browsing, and read-only API inspection, but restricted write, admin, and private endpoints should use a local Core or a custom node controlled by the user.

When network discovery is selected, Home starts from the public seeds, asks for known peers, probes candidates for public QDN/read API support, and prefers a reachable node that can answer public QDN resource searches. Home does not send the local API key while using Previewnet network mode.

Qortium Home does not yet expose a first-party direct chat UI or generic transaction signing workflows. Its SEND_MESSAGE bridge action is deliberately not an exception: it only permits a fee-zero plaintext message to a validated Qortium AT, after a transaction-specific approval and local MemoryPoW/signing.

QDN App Bridge

Desktop APP and WEBSITE pages rendered in isolated QDN views and Android APP/WEBSITE pages rendered in the Capacitor WebView can use the Qortium-native qdnRequest bridge. It exposes read-only node, QDN, account, group, chat, rating, and market-data lookups, plus approval-gated write actions (QDN publish/delete, group, name, payment, poll, list, chat, minting, rating, and node-settings requests) that Home signs itself, so QDN apps never receive wallet private keys or generic signing capability. The bridge accepts strict object-form requests only — legacy aliases, string-form requests, external URLs, and write-style node API methods are rejected — and Android APP/WEBSITE bridge injection is limited to Home-owned tokenized iframe loads.

The authoritative action catalogue is electron/qdn-app-actions.ts. Documented bridge feature areas include app versioning (docs/APP_VERSIONING.md), app notifications (docs/APP_NOTIFICATIONS.md), same-tab navigation (docs/OPEN_CURRENT_TAB.md), and approval-gated Home display settings (docs/HOME_SETTINGS_BRIDGE.md). Operational details apps rely on — per-mode action availability, poll scheduling fields, the publish source-token flow, FETCH_NODE_API limits, and the rating actions — are collected in docs/BRIDGE_ACTIONS.md. The bridge also offers interoperability actions that target the separate Qortal network — such as SEND_QORT and the GET_QORTAL_* reads — which are kept distinct from Qortium's own actions; Qortium and Qortal remain separate networks.

Planned Work

• Additional qdnRequest approval prompts for generic signing and other write-style account actions.
• First-party local-node workflows for chat management.
• Mainnet Core profile selection and richer Core maintenance controls.
• Code signing and release verification for production builds.

Download

Prebuilt packages are published on the GitHub Releases page: Linux AppImages (x64 and arm64), macOS DMGs, a Windows x64 portable executable, and an Android APK. Home also has an in-app self-update system with stable and prerelease channels that downloads and verifies the matching platform asset; releases are currently published on the prerelease channel.

Current desktop builds are unsigned, while public Android release APKs use the project's established Android release signer. Expect operating-system warnings for unsigned desktop packages and Android unknown-source prompts, and see Status before using wallets with meaningful funds.

Development Setup

Install dependencies:

npm install
npm run setup:electron

Use Node.js 22.12 or newer (CI uses Node 24). Electron 43 downloads its binary on demand; setup:electron makes that step explicit before native tests.

Build and start the desktop app locally:

npm run dev

Home 2 deliberately loads its built renderer from dist/ in local runs because the shell blocks ordinary HTTP navigation, including a Vite development server. npm run dev is therefore an alias for the build-and-start flow below rather than a hot-reload server.

Build the renderer and Electron main process:

npm run build

Run the built app locally:

npm start

Release Builds

Beta.14 and newer target macOS 12 or later with patched Electron 43. New macOS 10.15/11 builds are retired; existing beta.13 legacy downloads remain available. macOS packages are ad-hoc code-signed for native API compatibility, without an Apple publisher identity or notarization. See the release runbook.

Build a Linux x64 AppImage:

npm run dist:linux:x64

Build a Linux arm64 AppImage:

npm run dist:linux:arm64

Build both Linux AppImage targets:

npm run dist:linux:all

Linux AppImage dist scripts set the generated .AppImage files to executable mode after electron-builder finishes.

Build a macOS x64 DMG on macOS:

npm run dist:mac:x64

Build a macOS arm64 DMG on macOS:

npm run dist:mac:arm64

Build a universal macOS DMG on macOS:

npm run dist:mac:universal

Each macOS dist target also has a :remote variant (for example npm run dist:mac:universal:remote) that runs the build on a remote Mac; see docs/REMOTE_MAC_BUILDS.md.

Build a Windows x64 portable executable:

npm run dist:win:x64

Sync the web app into the Android project:

npm run android:sync

Open the Android project in Android Studio:

npm run android:open

Build a local Android debug APK:

npm run dist:android:debug

Build Android release APK and AAB packages:

npm run dist:android:release

Build only one Android release package type:

npm run dist:android:release:apk
npm run dist:android:release:aab

Android release packages are copied into dist-release/. If release signing is not configured, the files are named with an -unsigned suffix and are suitable for local packaging checks only. Configure these values as environment variables or Gradle properties before building public Android release assets:

QORTIUM_HOME_ANDROID_KEYSTORE=/absolute/path/to/release.keystore
QORTIUM_HOME_ANDROID_KEYSTORE_PASSWORD=...
QORTIUM_HOME_ANDROID_KEY_ALIAS=...
QORTIUM_HOME_ANDROID_KEY_PASSWORD=...

Check a local unsigned Android package set while signing is still pending:

npm run release:check -- --skip-github --android-only --allow-unsigned-android

Smoke-test the Android QDN app bridge against the default emulator:

npm run smoke:android:qdn-bridge

The smoke command uses the newest debug APK, reuses an attached Android device when one is present, or starts the qortium_home_api36 AVD in headless mode. Set ANDROID_AVD_HOME, QORTIUM_HOME_ANDROID_AVD, or QORTIUM_HOME_KEEP_ANDROID_EMULATOR=1 to override those defaults. The command points the app at the host's local Previewnet node through http://10.0.2.2:24891, first verifies Android wallet creation and encrypted backup export through the native wallet backup bridge, then verifies strict qdnRequest injection, SHOW_ACTIONS, read-only node API GET/HEAD calls, structured QDN resource status/properties/metadata/URL/fetch calls, resource list/search calls, group/chat read action availability, selected-account approval/deny/no-account flows, and account-backed QDN publish/delete approve, deny, missing-API-key, non-local-node, and no-account write paths with ignored preview account material at ~/git/qortium/preview/secrets/initial-minting-accounts.json. It also verifies rejected legacy, malformed, write-method, and oversize node API requests, and that un-tokened Android APP render pages do not receive the Home-owned qdnRequest bridge. Set QORTIUM_HOME_ANDROID_NODE_API_URL, QORTIUM_HOME_PREVIEW_ACCOUNTS_PATH, or QORTIUM_HOME_SMOKE_ACCOUNT_ROLE to override those defaults.

The Android bridge smoke also covers Previewnet public-node discovery and no-account behavior. Home 2 does not currently advertise the generic app-assignment actions; assignment management in the 2.1 F4 slice stays inside the trusted Home Settings shell.

Smoke-test Android QDN image, audio, and video viewers against the default emulator:

npm run smoke:android:qdn-media

The media smoke uses the newest debug APK, points Android at the host's local Previewnet node through http://10.0.2.2:24891, opens the IMAGE, AUDIO, and VIDEO QDN fixtures, and verifies that Android loads them through blob URLs with image dimensions or media metadata available and no viewer error message.

Smoke-test Android QDN file download/open handoff against the default emulator:

npm run smoke:android:qdn-download

The download smoke uses the newest debug APK, points Android at the host's local Previewnet node through http://10.0.2.2:24891, opens the FILE QDN fixture, uses the native Open action, verifies that the file was saved under Home's private Android app data, and confirms Android received the open handoff.

Smoke-test the Android update install handoff against the default emulator:

npm run smoke:android:update-install

The update install smoke uses the newest debug APK, copies it into Qortium Home's app-private update download directory, verifies that unsafe paths and non-APK filenames are rejected, then confirms the valid APK reaches Android's package installer or the unknown-app-source Settings screen.

Smoke-test the update status shown after an update has been installed:

npm run smoke:desktop:app-update-state
npm run smoke:android:app-update-state

Both commands seed a downloaded-update record, stub the GitHub release endpoints, and assert what the update card reports. The installed scenario covers the regression fixed in #179, where a downloaded update that had already been installed kept being reported as "Downloaded" with a "Show file" / "Install APK" action instead of "Up to date". The pending scenario covers the other half, that a download for a release which really is still available survives. Pass --scenario=installed or --scenario=pending to run one.

The Android command needs a debuggable build, since a release APK exposes neither run-as nor a WebView debugging socket: run npm run dist:android:debug first. It reuses an attached device when there is one and otherwise boots the default emulator; pass --emulator to force the emulator. If the device already has a release build installed, the signing keys differ and installing fails — pass --reinstall to uninstall it first, which erases that app's data on the device.

Smoke-test desktop QDN app publish/delete writes against the local Core:

npm run smoke:desktop:qdn-write

This command starts the desktop development app, opens the APP fixture, approves one QDN publish and one delete request through the UI, and signs with the ignored preview account file at ~/git/qortium/preview/secrets/initial-minting-accounts.json. It expects the local Previewnet node, API key, and QDN preview APP fixture to already be available. Set QORTIUM_HOME_PREVIEW_ACCOUNTS_PATH, QORTIUM_HOME_NODE_API_KEY, QORTIUM_HOME_NODE_API_KEY_PATH, QORTIUM_HOME_SMOKE_ACCOUNT_ROLE, or QORTIUM_HOME_SMOKE_PUBLISH_NAME to override those defaults.

Smoke-test desktop QDN app read/API bridge behavior against the local Core:

npm run smoke:desktop:qdn-api

This command starts the desktop development app, opens the APP fixture, and checks strict qdnRequest injection, SHOW_ACTIONS, path-only FETCH_NODE_API GET/HEAD calls, structured QDN resource status/properties/metadata/URL/fetch calls, resource list/search calls, group/chat read calls, and rejected legacy, malformed, write-method, and oversize node API requests. It expects the local Previewnet node and QDN preview APP/JSON fixtures to already be available.

Smoke-test the same QDN app read/API bridge behavior from the packaged Linux AppImage:

npm run smoke:desktop:qdn-api:packaged

This command builds the Linux x64 AppImage, launches it with an isolated temporary profile, and runs the same bridge assertions against the packaged preload and main-process files. Set QORTIUM_HOME_SKIP_PACKAGE_BUILD=1 to reuse an existing AppImage, or set QORTIUM_HOME_DESKTOP_QDN_API_APPIMAGE to test a specific AppImage path.

Run the full desktop QDN permission smoke suite:

npm run smoke:desktop:qdn-permissions

The full suite covers the success path plus denied publish/delete, no selected account, locked account, missing API key, non-local node, and stale QDN view approval cases. To run one case directly, pass --scenario=<name> to scripts/smoke-desktop-qdn-write.mjs.

Check that Home's QDN service whitelist has not drifted from the node's catalogue:

npm run smoke:qdn-services

This imports Home's curated service list from the built dist-electron/qdn-public-services.js and compares it to GET /arbitrary/services: every listed service must still exist in Core and be public, and Home's _PRIVATE-suffix rule must agree with Core's authoritative private flag across the whole catalogue — so a service Core renames, removes, or reclassifies cannot silently rot in Home. Public Core services Home does not surface (system/chat-internal ones) are reported, not failed. It only needs a reachable node; override the URL with QORTIUM_HOME_NODE_API_URL.

The offline half of that guard (list shape, duplicates, agreement with Home's own private-service rule) runs in npm test via test:qdn-public-services, and the comparison logic itself is covered against fabricated catalogues by test:qdn-services-drift — neither needs a node.

Release artifacts are written to dist-release/. Generated build output should not be committed to git. The release checker and publisher default to the public QortiumDev/qortium-home GitHub repository.

The current Windows executable is a portable self-extracting build, not an installer. It is unsigned and may show Windows SmartScreen warnings.

The current macOS DMG builds are unsigned and should be built on macOS. Local test builds may require opening from Finder's right-click menu or approving the app in macOS privacy and security settings.

Android builds require a local Android SDK with Android Platform 36 and Build Tools 35 installed, SDK licenses accepted, and ANDROID_HOME or ANDROID_SDK_ROOT pointing at the SDK. The debug APK output is generated under android/app/build/outputs/apk/debug/ with a filename like Qortium-Home-<version>-android-debug.apk. Release APK/AAB outputs are collected under dist-release/; release:publish expects signed Android release files without the -unsigned suffix.

Regenerate Android launcher icons after changing build/icon-source.png:

npm run icons:android

Android currently connects to existing nodes only. By default it uses Previewnet network discovery: it starts from the public seed API URLs, calls /peers/known, converts discovered peer addresses to candidate API URLs, and uses a reachable node for read-only QDN/API browsing. Candidate nodes are preferred when they answer both /admin/status and a public QDN resource-search probe. Users can still choose a custom LAN or remote node URL. Android can open file-style QDN resources through the native Android chooser, load existing encrypted wallet JSON files into app-private storage, create new encrypted wallets only after a backup file is saved through Android's document picker, and export saved encrypted wallet backups again later. Android QDN APP/WEBSITE pages can also request single-file QDN publish/delete writes, group joins, group chat sends, and private closed-group chat reads after approval when the user has a local selected node, an unlocked selected account, and the local node API key saved in app-private node settings.

Desktop Home 2.0 defaults to the local Qortium Core at https://127.0.0.1:24891 and the local Qortal Core at https://127.0.0.1:12391. Because local Cores use private certificate authorities, Home learns and stores each authority through the Core's loopback bootstrap endpoint before trusting the HTTPS connection. Local mode keeps using the local API key for authorized calls. Public mode selects synchronized named HTTPS nodes for read-only browsing without calling that access Previewnet.

Desktop can also manage a local Qortium Core Previewnet install from the node settings menu. The first Core management flow checks QortiumDev/qortium-core GitHub releases for the current qortium-preview.zip prerelease asset, installs it under the stable qortium-core app-data folder, can install a managed Java 25 runtime when needed (any system Java 17 or newer is also accepted), and runs the bundled preview start and stop scripts. Home keeps its own desktop data under qortium-home by default, while Core release files, install metadata, downloads, Java, and runtime files live under qortium-core. Core updates replace only qortium-core/install, leaving qortium-core/runtime intact so they do not recreate the chain database, QDN data, logs, PID file, or API key. When a local or trusted custom Core node is selected with an API key available, the dashboard also checks Core's approved on-chain/QDN update status through /admin/update. For Home-created local Core installs, Home reads the Core runtime apikey.txt automatically and saves it in node settings. Custom nodes can save their own API key in node settings. On Linux, Home can also detect the apikey.txt for an already-running local Core process so it does not send a stale Core key to a different local Core. If Core reports an approved update and its auto-update mode is INSTALL, Home shows that Core will install it automatically; otherwise Home offers a manual approved-update install action.

QDN Preview Test Data

The development helper below is for local Previewnet testing only:

npm run qdn:bootstrap-test-data

It registers or reuses a local test name and publishes APP, WEBSITE, IMAGE, AUDIO, VIDEO, JSON, and FILE fixtures that Qortium Home can browse. It expects a running local Previewnet node and a local preview account with permission to publish test resources.

Supported environment variables:

• QORTIUM_HOME_NODE_API_URL
• QORTIUM_HOME_TEST_NAME
• QORTIUM_HOME_NODE_API_KEY
• QORTIUM_HOME_NODE_API_KEY_PATH
• QORTIUM_HOME_PREVIEW_ACCOUNTS_PATH

Never commit node API keys, private account files, wallet files, seed material, or local preview secrets.

Documentation

• Project plan: docs/PROJECT_PLAN.md
• App versioning standard (QAVS): docs/APP_VERSIONING.md
• QDN app notifications: docs/APP_NOTIFICATIONS.md
• Core management: docs/CORE_MANAGEMENT.md
• OPEN_CURRENT_TAB bridge action: docs/OPEN_CURRENT_TAB.md
• Bridge action notes: docs/BRIDGE_ACTIONS.md
• Home settings QDN bridge: docs/HOME_SETTINGS_BRIDGE.md
• Remote macOS builds: docs/REMOTE_MAC_BUILDS.md
• Change log: QORTIUM-HOME-CHANGELOG.md — every merged PR adds one plain-language entry in the same branch.
• Website: https://qortium.app
• Community discussions: https://github.com/orgs/QortiumDev/discussions

License

Qortium Home is licensed under the BSD Zero Clause License (0BSD). You may use, copy, modify, and distribute it for any purpose, with or without fee, and no attribution is required.