Skip to content

Signed desktop installer for macOS and Linux #521

Open

Description

@andersalm

Problem

People install ElastOS 2.0.0 by pasting a command into a terminal. A signed app that installs ElastOS and keeps Home running would remove the main barrier for new users.

Expected behaviour

  • One app. Use the standalone Home app in Lab desktop app for Mac, Windows and Linux Elacity/elastos-agent-host-spike#1386, under Anders’s 10 November decision. Carry over reusable signing, verified installation and existing-Home adoption work through the Runtime contracts and their acceptance checks; rebase it onto current spike/agent-host first.
  • Install: double-click, no terminal. The app installs ElastOS through Install ElastOS from a signed release packed inside a desktop installer #520, registers the background service (Home stops when the terminal or SSH session that started it closes #518, Linux: keep Home running after the last SSH logout and start it at boot #519) and opens Home.
  • Passkeys: #1386 makes passkeys work in the app window, with Touch ID on Mac and the TPM on Linux, where browsers often have no passkey store (First-time setup dead-ends at the passkey step on Windows and Linux #452). Today the window accepts only passkeys the app holds. Whichever way ships, a person who already has a passkey in their browser can sign in through the app, and a person who set up in the app can still sign in from a browser or another device.
  • Menu bar: Home status, Open Home, Stop, Start at login on or off.
  • Mac: a DMG signed with Elacity's Developer ID, hardened runtime, notarized and stapled. Minimum macOS matches the Runtime's.
  • Linux: a package for Ubuntu x86-64 and ARM64 (including Jetson) whose download can be checked against the release signature.
  • Release pipeline: built and signed from the same release as install.sh, which packaging verifies exactly as install.sh does before building. The app's own updates are signed and checked. No developer tools or lab settings in release builds.
  • Signing credentials: "Developer ID Application: Elacity LLC" already signs and notarizes elastos-launcher (checked on v1.4.0); reuse it. New certificates or paid signing services need Anders's approval.
  • Uninstall: removes the app and the service; keeps Home's data unless the person asks to delete it.
  • Size: the Browser image is not packed in; Home fetches it when needed.

Out of scope

Acceptance (on the published candidate)

  • Mac, new user: the downloaded DMG opens without warnings; install with no terminal; create a passkey; quit the app and Home keeps running; restart the Mac and Home comes back; update in System; uninstall keeps data.
  • Mac with an existing terminal-installed Home: adopted; its browser passkey signs in through the app, and the browser still works.
  • Ubuntu x86-64, Ubuntu ARM64 and Jetson: the same journeys. Linux passkey creation depends on First-time setup dead-ends at the passkey step on Windows and Linux #452; until it is fixed, the test uses a phone or security-key passkey and says so.
  • Recovery works without a terminal (Anders, 10 Nov).

Links

Elacity/elastos-agent-host-spike#1386, Elacity/elastos-launcher#46, #520, #518, #519, #172, #265, #452.

Acceptance record

  • Candidate: none selected. Baseline: source read on origin/develop, 19 Nov 2026.
  • Exercised checks: the 10 November owner decision selects the standalone Home app. Runtime recovery exports are at elastos/crates/elastos-server/src/api/auth_gateway.rs:1825; current data/key limits are at docs/INSTALL.md:535,547. Not run: builds and installed checks (source read only).
  • Review links: retain Anders’s app review and the later scoped Runtime reviews.
  • Installed release evidence: retain the dated trials with their stated limits; none added.
  • Remaining gate: browser/app passkey access, terminal-free recovery, existing-Home adoption, data preservation, signed update/Undo and the applicable WalletConnect: connect a phone wallet from the desktop app (finish the existing connector) #575 wallet journeys on the published candidate.
  • Next owner: Sasha for the app and signing; Main for the Runtime contracts.

Activity

  1. added this to the 2.1.0 milestone on Nov 2, 2026
  2. andersalm commented on Nov 8, 2026

    @andersalm
    ContributorAuthor

    Launcher analysis (8 Nov): first principles, entropy, ElastOS alignment

    At Anders's request. Anders chose Elacity/elastos-launcher as the one desktop app on 7 Nov (not the lab app agent-host-spike#1386). Analysis of the test branches (Mac a66ca52 / draft #63, Jetson #65, Windows #64) by Codex (GPT) and Cursor (Grok), numbers checked by a Claude quality review.

    Bottom line

    The launcher is about four times bigger than its job: 14,116 lines of app code and 9,472 lines of tests (the old Personal Cloud launcher was 3,339). Most of it does work that belongs to ElastOS: it checks release signatures, owns and stops Home's processes, backs up and deletes Home data, and keeps its own update and version records. ElastOS's rule is that the Runtime is the only authority. The launcher should be a tray and a small window that ask the Runtime. Most of the review rounds on 7 and 8 November were about exactly this process-control code.

    The window

    • It is fixed at 500 x 860 (minimum height 560). The running screen's card is 495 px tall, so 337 px, about two fifths of the window, is empty below it (measured in Chromium at that size, not in the packaged app). The size was set on 16 Oct when the install screen was added and never follows the content.
    • A CSS bug: .hidden (styles.css:37) loses to later rules that set display: flex (.control-btn, .steps, .info-row), so things meant to be hidden still show: the Remove PC2 button even when no PC2 is found, an empty Browser row, a Fix it button with nothing to fix. Fixing only that still leaves about 420 px empty; the window size must follow the content too.
    • The "device" look (power-button panel, URL and version rows, Presented by footer) adds height without adding anything a person needs on the main screen.

    What it should be

    A tray icon and a small window: status, Start/Stop, Open Home, Update when one is offered, and Details (logs, uninstall). ElastOS does the rest through its own commands: Home as a background service with start, stop and status (#518, #519, #509), install from a signed release inside the app (#520), uninstall (install.sh --uninstall exists today). One desktop app (#521): Anders chose this launcher over the lab app on 7 Nov, so the three test branches (Mac, Jetson, Windows) must become one branch before anything is deleted.

    Where the lines are, and when they can go

    Part Lines now (Mac branch) Goes when
    Owning and stopping Home's processes (supervisor and Mac process helper; the Jetson branch adds about 760, Windows about 840) about 1,100 ElastOS runs Home as a service (#518)
    Install tooling (downloads Python, curl and sha256 stand-ins, its own signature checker, the install adapter) about 1,600 ElastOS installs from inside the app (#520)
    Home data maintenance (reset, backup, uninstall, path rules, Windows reset helper) about 3,400 Uninstall calls install.sh --uninstall; backup and reset need a decision
    Remove PC2 (it also holds the zip code backup uses) about 1,600 Backup moves, and old Personal Cloud installs are gone
    Windows setup and transport, controller, preflight, pin, types about 4,700 Stays, shrinks
    Screen and window about 1,700 About 500 once the maintenance dialogs leave

    Target: about 1,200 (Grok) to 2,200 to 3,000 (Codex, keeping the Windows setup code) lines of app code.

    Second sources of truth

    • Its own update-status and previous-release files (ElastOS should report both).
    • The launcher version hard-coded as 1.4.0 in diagnostics (launchController.ts:219).
    • Home's port and address compiled in.
    • Two different definitions of "installed".
    • "Uninstall" means two things: the launcher deletes Home data; install.sh --uninstall keeps it unless asked, which is what Signed desktop installer for macOS and Linux #521 requires. Same word, two effects, and the destructive one is in the app.

    Other bugs found

    • Try again after an error runs Install, even when ElastOS is installed and Home was running.
    • An old error message stays on screen after a successful Start; Reset stays clickable during Install.
    • No single-instance lock: two launcher windows can both try to control Home.
    • On the Mac branch, Linux and Windows still start gateway (no update controller, so System update cannot work) and Linux quit stops Home. The Jetson and Windows branches fixed this; another reason to make them one branch.

    Plan

    Now, launcher only, small and reversible:

    1. Fix .hidden with a test that every hidden element really is hidden in every state; size the window to its content; main screen shows status, Start/Stop, Open Home and Update; logs, Reset and Uninstall go behind Details; remove the unused CSS (about 100 lines); read the version from the app; add a single-instance lock; Try again starts Home when ElastOS is installed and installs only when it is not.
    2. Combine the Mac, Jetson and Windows test branches into one (still a test branch, nothing merged to main or released).
    3. Uninstall calls install.sh --uninstall (keeps Home data unless the person asks to delete it) instead of the launcher's own remover.

    Next, in ElastOS (milestone 2.1.0), each followed by deleting the launcher copy in the same change:
    4. #518 with #519 and #509: Home as a background service owned by ElastOS. The design is posted on #518 for Irzhy's and Sasha's review before any code. The launcher then calls elastos home start|stop|status on Mac, Linux and Windows and deletes its process code. It also keeps Home running after a terminal or SSH session closes and after a terminal update.
    5. #520: install from a signed release inside the app; delete the install tooling and the launcher's own signature checker.
    6. Backup and reset through ElastOS, or dropped; then delete the launcher copies and Remove PC2.

    Do not delete the bridge before the ElastOS commands exist: on 2.0.0 Home would no longer start from the launcher. Windows needs more than the Linux service: the Windows logon step and #66 (proving the program on port 8090 is the distro's Home) stay a Windows release gate.

    Strongest argument against

    Time. The current launcher already works around the missing ElastOS commands, and replacing that needs installed proofs on three platforms plus migration of existing Homes. #520 first would help new users sooner. The order above keeps everything working: the window now, the deletions only together with each ElastOS command.

  3. andersalm commented on Nov 8, 2026

    @andersalm
    ContributorAuthor

    Launcher architecture review (8 Nov): coherent, or pivot early?

    Verdict

    • The design is coherent: a menu-bar power switch and front door for Home (approved mock), the same on every platform.
    • The code is not stable, because responsibilities sit in the wrong place, not because of the toolkit. The launcher is a second Runtime: it checks release signatures itself, proves and stops Home's processes (libproc, pidfd, /proc), owns update restarts, and backs up, resets and deletes Home data. The Runtime already has some of this (elastos home --status and --json exist in 2.0.0) and the launcher never calls it. Most review findings on 7 and 8 Nov were in this duplicated code.
    • The repository is not one line either: main is still the old PC2 launcher (relicensed MIT on 26 Oct with a LICENSE file); the ElastOS launcher lives on a test branch built on 13 stacked, unmerged PRs since 16 Oct, with no LICENSE file and "license": "AGPL-3.0" in package.json.
    • Electron 28.3.3 is unsupported (Chromium 120, Node 18; current Electron is 45.2.3, 4 Nov 2026, and only the latest three majors get fixes). For an app that loads only local files with context isolation, moving to 45 is a mechanical upgrade.

    Early pivots, in order

    1. The Runtime owns Home's lifetime (Home stops when the terminal or SSH session that started it closes #518, Linux: keep Home running after the last SSH logout and start it at boot #519, Terminal update and Undo leave Home stopped #509): elastos home start|stop|status as a per-user service. The launcher deletes its supervisor and process code. Design posted on Home stops when the terminal or SSH session that started it closes #518, waiting for Irzhy's and Sasha's review.
    2. Use what the Runtime already has, now: the launcher reads Home's state from elastos home --json instead of its own probing.
    3. Install from a signed release inside the app (Install ElastOS from a signed release packed inside a desktop installer #520): delete the downloaded install.sh path, the Python and curl stand-ins and the second signature checker.
    4. One update path: the Runtime decides and reports the offer; the menu, System in Home and the terminal all run elastos update. No launcher-side update or previous-release records.
    5. One product line: when Anders accepts the Mac build, the test branch becomes the launcher's main (Sasha reviews), the stacked PRs close as superseded, and the license matches main's MIT decision.
    6. Upgrade Electron 28 to 45 right after test.4: security fixes, mechanical change.
    7. Windows stays in scope through WSL (Anders's order: Mac, Jetson, Windows). Signed desktop installer for macOS and Linux #521 still says "Windows: Windows: prove the installed Runtime journey under WSL2 #265" and must be updated to say so.

    Not now

    • A rewrite in Rust or another toolkit. It does not fix the root cause (responsibilities in the wrong place), it reverses Anders's 7 Nov choice of this repository without a new fact, it would mean two desktop apps on three platforms during the switch, and shipping a signed macOS app inside the Runtime release needs a Mac signing job and a bundle updater that do not exist. Revisit when pivots 1 to 4 have shrunk the app to about 1,000 to 2,000 lines; a port is then cheap and well informed.

    What stays

    The menu-bar design and words; the CI rules (branch-scoped jobs, no reruns, Main-only pushes); every safety rule (ownership checks before any signal, signed-release floor, data-keeping uninstall, Windows WSL setup and reboot resume), carried into the Runtime with its tests when each piece moves.

  4. andersalm commented on Nov 10, 2026

    @andersalm
    ContributorAuthor

    Decision (Anders, 10 Nov): the desktop app is the standalone Home app in Elacity/elastos-agent-host-spike#1386, where Home opens in the app's own window. It is no longer the menu-bar launcher. This supersedes the 7 Nov choice recorded above. Anders's review: Elacity/elastos-agent-host-spike#1386 (review) ("chosen product direction"; the PR stays a draft until the findings and installed acceptance are done).

    What follows:

    Anders's Mac trial of the lab DMG (sha256 9393cbca…) worked end to end. It also showed that an account created in the app cannot reach the browser without the terminal recovery, and that recovery replaces the passkey instead of adding one. That makes the #521 account-access requirement the first gate.

  5. andersalm commented on Nov 17, 2026

    @andersalm
    ContributorAuthor

    Main’s 17 Nov handoff relays Anders’s conditional2.0.2 inclusion of the desktop dependencies. Main owns bounded quiet start, fullscreen, the signed local-folder installer’s security/recovery work and installed qualification; full#518/#519 service scope stays2.1.0. Record the exact release slice and any installer deferral in the owning issue; draft#350 and lab90eb7bde4 remain porting inputs.
    Root gives a bounded source PASS for quiet-start 2ae83d0aeb1896361e7d3c27a1de24b6b239eb58, tree 96e607e3794aebc85e15ad1a11fafa488e9343da, on5075c84765: all eight changed files plus retained-controller/recovery consumers inspected; two Python syntax checks and whitespace pass. The explicit choice enters the existing launch arguments/hash; the retained controller consumes it before launching an older executable and maps it to the existing opener-only marker. Receipt/LaunchPlan field shapes, launch hashing and install_transaction bytes stay unchanged. CLI, ready callback, low-space, update/restoration and cold-recovery regressions were inspected; Rust execution remains owner evidence. Earlier fullscreen source PASS on195da55d/tree05046a6d retains its seven-file/five-syntax scope, with sandbox strings unchanged.
    Main reports Linux focused results15pass/1ignored,6pass/1ignored and104pass/3ignored; these filters overlap. The reviewer’s real2.0.0/2.0.1 Linux capability probes are owner evidence; macOS probe and exact installed app journeys remain open. Exit2 is a general usage error; apps must probe the same executable before every start, including after terminal Undo. Preserve the three plain-bin provider-fixture failures reported on both base and candidate. Main owns applicable integration/release checks, required human review, actual Safari/desktop fullscreen enter/exit/focus and Runtime/components-bound quiet-start/adoption, signed folder installation/refusal, passkeys, recovery/update/Undo and #575 wallet acceptance before final app packaging. Linux fullscreen permission-only proof stays diagnostic; Windows native-window behavior stays app-owned.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions