Skip to content

Home stops when the terminal or SSH session that started it closes #518

Open
0 of 1 issue completed
Open

Description

@andersalm

Problem

In 2.0.0, Home runs only while the terminal that started it stays open. Closing the terminal, or the SSH session on a Jetson or Linux server, stops Home, and updates stop arriving too. The only workaround is tmux or screen.

Expected behaviour

  • The installer registers Home as a background service for the current user (systemd user service on Linux, LaunchAgent on macOS) and starts it.
  • elastos home and elastos home --browser open the running Home, starting it if needed. Closing them leaves Home running.
  • Stop ends the running Home. Autostart on/off changes only Home's own service, never account-wide settings; opening Home with autostart off does not turn it back on.
  • Status shows starting, ready, stopped or failed, with the reason. Ready means this installation's Home and its update controller run, not just that a port answers.
  • If the service cannot start, Home shows the failure and one repair step instead of quietly running in the terminal. Terminal mode stays as an explicit diagnostic option.
  • Update, Undo and interrupted-update recovery never leave two Runtimes or a restart loop.

Scope

Carry the needed behaviour from draft #350 onto current develop: 9 of its 11 files have changed since, and its last CI run failed the service-removal tests. Recheck install locks, data paths, the update controller and the recovery journal. Drop the terminal fall-back; add autostart on/off.

macOS: a LaunchAgent survives closing Terminal but not logout, and starts only at login. Running with nobody logged in needs a system daemon and a separate review.

Docs (INSTALL.md): what keeps running and when; the computer must stay awake; closing an SSH tunnel disconnects the browser but does not stop Home.

Acceptance

On Linux x86-64, Jetson and macOS:

  • Install, close the terminal or SSH session, reconnect: Home works.
  • Kill the Runtime: the service restarts it.
  • Stop: Home stays stopped until opened or the next login.
  • Autostart off: Home does not start at login; elastos home --browser still opens it.
  • Update and Undo: one Runtime afterwards, service still registered.
  • Interrupted update: recovery completes once, no loop.
  • Uninstall removes only this installation's service; data kept unless asked.
  • Linux: the sub-issue's logout and reboot journeys pass.

Out of scope

Tray or desktop app (#394). Isolation and service limits (#183).

Links

#350, failed CI run https://github.com/elastos/elastos-runtime/actions/runs/38211869253, #183, #394.

Activity

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

    @andersalm
    ContributorAuthor

    Design proposal: one owner keeps Home running (#518, #519, #509), and what the desktop launcher does now

    Written from the source at develop 30b166b, v2.0.0 7bc3704, draft #350 at 553b471 and the launcher test branch at b429223 (Cursor, Grok 4.7, second round). A GPT check of round 1 returned MODIFY; this round answers it: writer lock before stopping Home, recovery kept on the installed path, consented migration of elastos serve Homes, per-data-directory service identity, launcher login item separate from Home autostart, Browser helpers, logs, sleep, WSL. Design only, no code. For review by Irzhy (lifecycle and admin step) and Sasha (launcher).

    Changes from round 1

    Round 1 stopped the service and then ran the update. A download failure after that stop leaves Home offline. The current #350 head does the same kind of stop too early. UpdatePause::begin runs before InstallTransaction::acquire at update.rs:1456 on 553b471b. This design deletes that order.

    The service process is not what terminal update stops. exec keeps the pid, so the service's main process is the controller. System update already holds the writer lock and the restart journal before it stops the gateway child, at update.rs:1738, :1865, and :1885 on HEAD. Terminal update and Undo use that same order when the controller is live. systemctl stop during the replace would exit 0, from the signal handler at update_controller.rs:821. Restart=on-failure would not start the service again. The journal phases that exist today also cannot finish a committed candidate on a cold start. CandidatePending falls through to restore_for_restart. CandidateStartClaimed bails at update_controller.rs:1385. Keeping the controller alive is what makes the existing journal work.

    Journal recovery runs before any clean exit. On HEAD, main.rs:1372 calls resume_restart_recovery for home --browser. That function continues only when current_exe equals source.install_path, at update_controller.rs:114. The pending check that follows requires journal.restart, at install_transaction.rs:1752. The draft has no resume_restart_recovery. main.rs:1331 on 553b471b returns Ok(()) when start_refused_by_pending_install is true. That helper passes current_exe to has_pending_recovery, at home_service.rs:35 on the same head. has_pending_recovery is true for any journal beside that binary, at install_transaction.rs:373. Do not port that guard. A journal with no restart record may still exit 0, and only after recovery has already declined to run.

    The binary stays at the install path in sources.json. The default is $HOME/.local/bin/elastos, at sources.rs:39. The draft's <data>/bin/elastos, at home_service.rs:113 on 553b471b, is not ported. Because that path is shared, the draft's ownership check, which looks only for the binary string, would treat two data directories as one owner. Ownership is the data directory.

    Ctrl+C is not a defect. The controller treats SIGINT and SIGTERM as a clean stop, at update_controller.rs:821, and docs/INSTALL.md:64 tells the person to use Ctrl+C. The Mac launcher update path is not two restarters. It stops, runs the update, and starts one supervisor, at runtimeTarget.ts:117. The controller does not start a replacement child when the child exits. It returns the error at update_controller.rs:1254.

    elastos serve is not replaced by the next home start. Issue #541 records Anders's Jetson Home as that command. Migration waits for an explicit yes.

    The new section "Launcher now, on 2.0.0" is the bridge. elastos home start does not exist on v2.0.0 or on 2.0.1-rc.1.

    How Home stays up

    Overview

    Today, an installed elastos home --browser replaces itself with the update controller. The controller starts the gateway and waits. Close that terminal, or end that SSH session, and both processes die. elastos serve is a different host. It takes the same data-directory lock as role serve, at serve_cmd.rs:24, and it can keep running after its starter exits. No launchd agent and no systemd user unit is installed for Home.

    The design adds one user service and does not add a second supervisor in the launcher. The launcher calls Runtime. When the service exists, the launcher stops spawning a gateway.

    Key concepts

    The browser Home is the gateway on localhost:8090. BROWSER_HOME_PORT is 8090 at update_controller.rs:2322.

    The update controller is a copy at update-controller/runtime under the data directory. It survives a replace of the installed binary. It owns one gateway child.

    The install writer lock is InstallationGuard on the install directory, at install_transaction.rs:153. The restart intent is RestartRecord inside the install journal, at install_transaction.rs:136. The host lock is a separate flock on host-process.lock. One live host per data directory.

    The data directory is $XDG_DATA_HOME/elastos or $HOME/.local/share/elastos, at sources.rs:12.

    elastos home --status stays the probe that does not start Home.

    Ready means all of these are true. The controller pid and start time match update-controller/status.json. The host lock role is gateway. The lock address is localhost:8090. The Home health check matches this install. An open port by itself is not ready.

    Service parent

    macOS file: ~/Library/LaunchAgents/org.elastos.home.plist. Label org.elastos.home.

    Linux file: ~/.config/systemd/user/elastos-home.service, or under $XDG_CONFIG_HOME when that is set. Unit name elastos-home.service.

    Those names stay fixed. They are one service per user account, not one name per data directory. The file body names this install's data directory, as WorkingDirectory and as XDG_DATA_HOME when the data directory is not the default. ExecStart is the absolute install_path from sources.json, then the arguments home --browser. The environment includes ELASTOS_SERVICE=1.

    Spec takes the platform, the home directory, the data directory, and the install path as arguments. It does not look up the host by itself.

    On Linux the unit text keeps Restart=on-failure, RestartSec=5, StartLimitIntervalSec=300, StartLimitBurst=5, and KillMode=mixed. TimeoutStopSec stays 45 seconds, which is the draft's STOP_TIMEOUT minus 15. The controller's child grace is 12 seconds, at update_controller/child.rs:12. The service wait is longer than that grace, so the controller can stop the gateway before systemd sends SIGKILL.

    On macOS, KeepAlive is true only when the exit was not successful. ThrottleInterval stays 30. LimitLoadToSessionType stays Aqua.

    RunAtLoad and the systemd enable state follow Home autostart. They are not always on. Opening Home starts the service for this session and does not change autostart.

    ELASTOS_SERVICE goes on the controller launch allow-list at update_controller.rs:56. Without that, the child gateway still opens a browser and still prints the terminal sentence. In service mode the ready path does not open a browser and does not print Keep this terminal open.

    A source checkout does not get a unit. enter_browser_home already returns when current_exe is not the install path, at update_controller.rs:689.

    Commands

    Keep elastos home --status and elastos home --json.

    Add these commands on the installed binary. The draft's elastos service subcommand is not the product command. #518 names elastos home.

    • elastos home start. Write the unit if this data directory does not own one. Start it for this session. Do not change autostart.
    • elastos home stop. Stop the unit. Do not change autostart. A later login does not start Home unless autostart is on.
    • elastos home service-status. Print starting, ready, stopped, or failed, plus one reason. Also print autostart on or off, and one mode line. keeps running after you log out and starts at boot. runs only while you are logged in.
    • elastos home autostart on and elastos home autostart off. Change only this Home unit.
    • elastos home --browser. If the unit is stopped, start it for this session. When status is ready, open http://localhost:8090/home/ and exit. Closing the terminal does not stop Home.
    • elastos home --foreground. The current terminal controller. It is the diagnostic path from Home stops when the terminal or SSH session that started it closes #518. It refuses to start when the unit is already active. A service failure does not select this path by itself.

    elastos and elastos home with no flag open the terminal UI against the service gateway. They do not spawn a managed elastos serve when this install's unit holds the host lock. elastos serve stays the explicit operator command. It still fails when the unit holds the host lock.

    If the service cannot start, print the failure and one repair sentence. Do not start a terminal Home as a fallback. The draft does that in running_home_url. The fallback sentence is at home_service.rs:1100 on 553b471b. Do not port it.

    Update and recovery

    Two update paths share one journal and one controller.

    System update stays inside the live controller. The service pid does not change. The controller stops the gateway child and starts one new child, as it does now.

    Terminal elastos update and elastos update --rollback-to, when status() reports a live controller, use that controller as the restart owner. They do not use ApplyMode::Normal. Normal writes no RestartRecord and ends at home_stopped_line, at update.rs:1128 and :1725.

    queue_update accepts only a newer version, at update_controller.rs:899. A newer terminal update can queue to the live controller and wait until the status phase is updated, restored, or failed. Undo is older, so it cannot use that queue. Undo gets one controller operation with the same lock, the same journal, a stop of the child, a restore of the previous release, and a start of that child. Undo stays a terminal command. There is no System Undo.

    The order, for both, is the System order already on HEAD.

    1. Download and verify while the gateway child is still up. A download failure or a hash mismatch returns here. The child is still running. apply starts a child again only when self.child is none, at update_controller.rs:1337. The publish path marks the phase failed while the host is ready and the phase was staging, downloading, or verifying, at update_controller.rs:1218.
    2. Take InstallationGuard while the child is still up. On the System path this is InstallTransaction::acquire at update.rs:1738.
    3. Write RestartRecord with prepare_restart at update.rs:1865. The plan names the controller sha256 and the launch-plan sha256 already stored in the receipt, so reconcile_pending accepts it at update_controller.rs:1375. The record is on disk before the child stops.
    4. Stop the gateway child, owner.stop at update.rs:1885. Take the offline host lock only after that stop, at update.rs:1887.
    5. Activate. On success, start one child of the same controller and finish the journal when that child is ready.
    6. On activation failure or candidate start failure, restore the previous release and start it, at update.rs:1935. The previous release is started at most twice, PREVIOUS_START_ATTEMPTS at update_controller.rs:47 and :1459. The failed new release is not started again, at update_controller.rs:1447.

    When the controller is not live, Home was not running. Terminal update keeps today's Normal path and does not start Home. #509 applies when Home was running before the command.

    Crash windows when the controller is the owner:

    • Death before the restart record is durable. The child was not stopped. The next start finds no restart journal.
    • Death after the record and before the new child is ready. The process exit is a failure, not the clean SIGTERM path. Restart=on-failure starts one new controller. resume_restart_recovery runs first and execs that controller. reconcile_pending restores the previous release when the phase is not ready, then start_restored_previous brings that Home up.
    • Death after ready. finish_restart has cleared the restart record. A second start does not repeat it.

    The CLI must not leave CandidateStartClaimed or PreviousStartClaimed with no process receipt. reconcile_pending bails on those phases and Home stays down.

    transaction.recover refuses a journal that still has a restart record, at install_transaction.rs:590 on HEAD. A restart journal is finished by the controller, not by a second elastos update that tries to unwind it.

    A journal with no restart record is an interrupted install or an interrupted Normal update. After resume_restart_recovery returns because there is no restart record, service mode may exit 0 so Restart=on-failure does not loop. The sentence tells the person to run elastos update or install.sh. That exit is not a substitute for recovery.

    System update under the unit

    The unit starts home --browser. enter_browser_home execs update-controller/runtime, at update_controller.rs:166. The pid does not change. launchd and systemd keep tracking that pid. status.json stores that pid as controller_pid, at update_controller.rs:1203.

    System update calls run_restarting_update, at update.rs:867, with the controller as RestartOwner. The controller process stays in serve while apply runs, at update_controller.rs:1333. The child stop and the later child start happen inside that process. The unit does not see an exit.

    Exit 75 is the gateway host, not the controller. spawn_installed_binary_supersession_watch exits 75 when the binary it is running is replaced, at host_lock.rs:237. The gateway calls that watch at gateway_cmd.rs:71. The controller does not read code 75. Any observed child exit makes serve return Home stopped. Start Home again. at update_controller.rs:1254. A clean System update does not use that path, because the controller stops the child before the replace.

    If a replace does hit a live child, the controller's error exit is non-zero. The service starts one new controller. That process runs reconcile_pending before serve, at update_controller.rs:825 and :1344. The launcher does not also restart it.

    queue_update refuses to queue when no live controller status exists, at update_controller.rs:868. A service that has reached ready has that status, so System update from the Home page still queues.

    Migration from elastos serve

    elastos serve defaults to 0.0.0.0:3000, at main.rs:126. It holds host-process.lock as role serve. elastos gateway and elastos home --browser hold the same lock as role gateway, at gateway_cmd.rs:70. One lock, so both cannot stay up in one data directory.

    Issue #541 is the record for Anders's Jetson. The issue body says that elastos serve Home used 47 percent of one core over its lifetime. The comment on 6 Nov 2026 says the same Home, still elastos serve, used 43.5 percent of one core over 60 seconds and 43.7 percent over 5 minutes. This lane did not measure it. The migration exists so that Home can move to the service without an automatic kill. It is not the idle-CPU fix.

    No current command offers this move. elastos home start refuses when the lock role is serve. It prints the pid and the address from the lock. It does not signal that process.

    The only move is elastos home adopt-service. With no answer, it prints the plan and exits without a change. The plan names the pid, the current address, and http://localhost:8090/home/ as the address after the move. It says port 3000 will stop answering, including for other machines that used 0.0.0.0:3000. An interactive yes, or --yes on the command line, is the consent. Anything else is a no.

    On yes, the command records the lock address, stops that serve process, and waits until the host lock is free. It does not delete or rewrite the data directory. sources.json, the identity store, capsules, components.json, and provider config stay where they are. It then starts the user service.

    elastos serve does not call verify_auth_audit_chain_ready or verify_principal_roots_ready_and_report. The gateway does, at gateway_cmd.rs:72. If the new Home does not become ready, adopt-service starts elastos serve again on the saved address and prints the gateway's error. The data directory is unchanged either way. A failed adopt does not leave the host lock empty.

    A subordinate serve, the one started with ELASTOS_ALLOW_SUBORDINATE_RUNTIME_HOST=1, is not this Home. adopt-service does not treat it as a migration candidate.

    Carrier identity stays because the data directory stays. The move changes the listen address. It does not create a second Home.

    Service identity and lifetimes

    Two data directories

    The unit name is shared by the account. The draft refuses a second binary path at home_service.rs:611 on 553b471b, and installed looks for that binary string at home_service.rs:341. That works only because the draft binary is <data>/bin/elastos. This design keeps one install path, so the check must read the data directory out of the unit file and out of the loaded unit. A mismatch is an error. The command does not overwrite the file and does not stop the other Home. The sentence names both data directories.

    A lock file beside the unit definition stays, .elastos-home-service.lock at home_service.rs:24 on the draft. It serializes writers of that shared name. A busy lock is refused.

    Launcher login item

    The launcher login item is the Electron app, not Home. applyOpenAtLogin calls setLoginItemSettings at openAtLogin.ts:74. On Linux it writes ~/.config/autostart/elastos.desktop whose Exec is the launcher binary, at openAtLogin.ts:13. The label in the app is the sign-in checkbox. app.whenReady applies that setting again and does not call launch.start, at index.ts:274.

    Home autostart is only the user service. Turning the checkbox off does not stop Home and does not disable the unit. Turning Home autostart off does not remove the login item. The checkbox stays honest because it starts the launcher at sign-in, and the person still uses Start to start Home.

    Browser helpers and KillMode

    KillMode=mixed stays, at home_service.rs:191 on 553b471b. Systemd sends SIGTERM to the main pid first. That pid is the controller. The controller stops the gateway child and its process group, at update_controller/child.rs:39.

    The gateway's crosvm process is a child of the gateway, started at elastos-crosvm/src/vm.rs:120, with kill_on_drop set. The Home terminal session calls setsid at gateway_home_terminal.rs:816. A new session does not leave the service cgroup. This lane did not measure cgroup membership on a running host. The stop timeout still ends with SIGKILL for processes left in the cgroup. KillMode=process would leave the gateway and the VM up after the controller exits. A first signal to the whole group would skip the controller's ordered stop. Neither replaces mixed.

    Logs

    The controller already rotates update-controller/runtime.log at 16 MiB, MAX_RUNTIME_LOG at update_controller.rs:51. The draft's Linux unit sets no stdout path, so the user journal keeps the service output with no cap in the unit file. The draft's plist writes <data>/logs/home-service.log. StandardErrorPath is at home_service.rs:234 on 553b471b. The plist has no rotation.

    Both platforms write that same home-service.log. Linux sets StandardOutput and StandardError to append to it. Before the service execs, a file larger than 16 MiB is moved aside once, the same cap as runtime.log. No second retention policy.

    Mac sleep and wake

    Neither tree has a sleep or wake handler. #518 says the computer must stay awake, and the install docs keep that sentence. LimitLoadToSessionType Aqua ties the agent to the graphical session. Sleep freezes that session. Wake continues the same pids. The design adds no sleep hook and does not restart Home on wake. If a child has died across the sleep, the controller's existing error exit is what the service restarts. The consumer check is a GET of Home after wake.

    Linux logout and WSL

    A systemd user service stops at the last logout, and it does not start at boot, unless linger is on for the account. That is #519. On Linux install, ask once. Explain that the admin command lets this user's services stay up after logout and start at boot. If the person agrees and the command works, record in the data directory that this install turned linger on. If the person says no, or has no admin rights, finish the install. Status then says runs only while you are logged in and prints sudo loginctl enable-linger with the user name.

    The draft calls loginctl enable-linger with no question, at home_service.rs:791 on 553b471b. Do not port that.

    Autostart off does not change linger. Uninstall does not turn linger off. If this install turned it on, uninstall says so and prints the command that turns it off.

    macOS LaunchAgent stays up after Terminal quits. It does not stay up after logout, and it starts at login only when autostart is on. A Mac with nobody logged in needs a system daemon and a separate review. This design does not add that daemon.

    The launcher imports Ubuntu 24.04 WSL rootfs ubuntu-noble-wsl-amd64-wsl.rootfs.tar.gz dated 20240423, at windowsHost.ts:25, with wsl --import ElastOS, at windowsHost.ts:82. Canonical's 24.04 WSL note says systemd is on by default, including for an imported rootfs. This lane did not boot that tarball, and neither tree writes /etc/wsl.conf or calls systemctl inside the distro. docs/FIRST_RUN.md in the launcher says systemd is not used.

    What keeps the distro alive in the launcher today is the wsl.exe -d ElastOS process. Linger inside the distro does not start the Windows VM after a Windows reboot. A user service inside the distro runs only after something has started the distro. That something is a Windows logon task that runs wsl.exe -d ElastOS. The task runs elastos home start once that command exists. Until then it runs the launcher-now command below, and the wsl.exe process stays up. Native Windows stays out of scope, as docs/WINDOWS.md says. The update controller is Unix-only.

    docs/WINDOWS.md:27 names port 61180. The Runtime and the launcher name 8090. The doc change keeps 8090.

    Launcher now, on 2.0.0

    v2.0.0 and 2.0.1-rc.1 have home, home --browser, gateway, serve, update, and update --rollback-to. They do not have elastos home start, elastos home stop, or ELASTOS_SERVICE. HEAD's main.rs matches the 2.0.1 candidate for those commands. The launcher has to work with that command set.

    The Mac test branch already spawns home --browser on darwin, at runtimeGateway.ts:759. Everywhere else it spawns gateway --addr localhost:8090, at runtimeGateway.ts:22. Windows spawns that gateway inside wsl.exe -d ElastOS -u root, at windowsRuntime.ts:188.

    queue_update requires a live controller, at update_controller.rs:868. elastos gateway never calls enter_browser_home. A launcher that spawns gateway cannot take System updates. Linux, including a Jetson that uses this launcher, and WSL, spawn home --browser with the installed binary. That is the same argv as Mac. The controller then exists, and the Home page can queue a System update.

    Spawn stays detached: true with stdin ignored and stdout and stderr piped, as spawnGatewayProcess does at runtimeGateway.ts:558. The WSL wsl.exe spawn gains the same detach. Today it is not detached. The piped stderr stays, because exit 75 detection reads the replacement text at runtimeGateway.ts:67.

    No TTY does not suppress the browser or the sentence. On tag v2.0.0, main.rs:67 returns false when stdin or stdout is not a terminal, so home --browser isolates its process group. The test home_browser_process_group_keeps_the_terminal_frontdoor_policy records that, in the lines the brief marks at main.rs:2633. open_browser at v2.0.0 main.rs:2269 always tries wslview, then xdg-open, then open on macOS. It does not look at the TTY. On HEAD the same function starts at main.rs:2278.

    The ready callback prints Keep this terminal open and opens the browser unless ELASTOS_UPDATE_RESTART is 1, at gateway_entry.rs:38. The controller also prints that sentence at update_controller.rs:1059. The controller sets ELASTOS_UPDATE_RESTART itself on the child, at update_controller.rs:241, after env_clear. The name is not on the launch allow-list. The launcher cannot pass it through. runtimeChildEnv drops every ELASTOS_ name, at releaseHead.ts:363. Setting the variable in the launcher environment does nothing on 2.0.0 or 2.0.1.

    What the launcher does instead, with the commands that exist:

    • Spawn home --browser on Mac, Linux, Jetson, and WSL. Do not spawn gateway for Start.
    • Do not call openBrowser after start. Install does that today. start is at app.js:217. openBrowser is at app.js:219. On Mac that second call opens a second tab, because the runtime already opened one. The Open button still calls openBrowser when the person asks.
    • Keep the stderr pipe. Do not show the line Keep this terminal open. Press Ctrl+C to stop Home. in the launcher log. The process still writes it. The UI drops that line. The replacement text for exit 75 stays visible to the exit handler.
    • On a Jetson with no xdg-open handler, open_browser fails the spawn and returns. No tab opens. The Home page is the SSH tunnel, as docs/INSTALL.md:64 already says.
    • On WSL, open_browser tries wslview first. That can open one Windows tab. The launcher does not open another.
    • Closing the window is not Stop. On Mac, window-all-closed does not quit, at index.ts:277. On Linux it quits, and before-quit stops Home, at index.ts:292. Linux and WSL must leave the spawned process running when the window closes. Stop still stops it. The menu item Quit and stop Home still stops it.
    • The launcher Update button is terminal elastos update, not System update. System update is the Home page talking to the live controller. The launcher leaves that process running. For the Update button, Linux and WSL use the Mac sequence: stop, run elastos update --yes, then start home --browser again, at runtimeTarget.ts:117. They do not wait for exit 75. The controller's own exit after a child exit 75 is not code 75, so the current exit-75 restart would not run. Undo uses the same stop, elastos update --rollback-to, start sequence.
    • A Jetson with only SSH has no launcher process. home --browser with no TTY still dies when the SSH session ends, because setpgid does not leave the login session. The user service is what keeps that Home up. The launcher section does not claim to fix a machine that is not running the launcher.

    elastos serve on a Jetson stays until adopt-service. The launcher Start command, on 2.0.0, uses the same refusal. If the host lock role is serve, Start reports the pid and does not kill it.

    What the launcher changes when the service lands

    The launcher stops spawning home --browser and stops spawning gateway. Start calls elastos home start and does not open a browser. The service mode does not open one either. The Open button opens http://localhost:8090/home/ when status is ready. Stop calls elastos home stop. The menu reads elastos home service-status. The Update button calls elastos update --yes and does not stop or start around it. The live controller does that work. Undo calls elastos update --rollback-to the same way. Windows calls wsl.exe -d ElastOS -u root -- /root/.local/bin/elastos with home start, home stop, or home service-status. A logon task runs home start after Windows sign-in. Quit no longer owns the process lifetime.

    The exit 75 restart loop, signalProcessGroup as Stop, and spawnDistroGatewayProcess go away with that change. They stay for the 2.0.0 launcher above, because that launcher is still the process parent.

    Files

    Runtime repo, from develop at 30b166b05. Port from 553b471b, not from 1dcf51297.

    • elastos/crates/elastos-server/src/home_service.rs and home_service/tests.rs. Keep the unit names, ELASTOS_SERVICE, the restart limits, KillMode=mixed, the manager trait, the service lock, and the refusal of a foreign unit. Change ownership to the data directory, ExecStart to install_path, autostart to a real switch, linger to one question, logs to the 16 MiB file, and removal to an lstat check. Drop the terminal fallback, the <data>/bin path, and start_refused_by_pending_install.
    • elastos/crates/elastos-server/src/main.rs. The new home commands. resume_restart_recovery stays first. The clean exit for a journal with no restart record comes after it. ELASTOS_SERVICE=1 is not a TTY front door. --foreground is the diagnostic path.
    • elastos/crates/elastos-server/src/gateway_entry.rs. Service mode does not open a browser and does not print the terminal sentence.
    • elastos/crates/elastos-server/src/update_controller.rs. Add ELASTOS_SERVICE to the launch allow-list. Keep resume_restart_recovery keyed to install_path.
    • elastos/crates/elastos-server/src/update.rs and release_cmd.rs. A live controller owns terminal update and Undo. Do not port UpdatePause::begin before the writer lock.
    • elastos/crates/elastos-server/src/home_cmd.rs. The terminal UI attaches to the service gateway and does not start a second serve for that case. adopt-service lives with the service commands.
    • scripts/install.sh. Finish starts the service when the person is at a terminal, and does not wait in the foreground. Uninstall removes only the unit this install wrote.
    • docs/INSTALL.md, docs/GETTING_STARTED.md, docs/COMMAND_MATRIX.md, docs/WINDOWS.md. The Windows doc uses port 8090. Install docs say what stays up, that the computer must stay awake, and that closing an SSH tunnel disconnects the browser only.

    Removal uses lstat on the exact unit path. It refuses a symlink. It compares device and inode with the file this install wrote. It does not scan LaunchAgents or the systemd directory. The draft remove_file is fs::remove_file at home_service.rs:827 on 553b471b. #518 says the last #350 CI run failed the service-removal tests. This report did not open that log. The missing lstat check is a defect in the draft function. The new removal test has to fail when a neighbor file or a symlink would be touched.

    Launcher repo, from b429223e on test/launcher-mac-dmg.

    Now, before the service exists:

    • src/main/targets/runtimeGateway.ts
    • src/main/targets/runtimeTarget.ts
    • src/main/targets/windowsRuntime.ts
    • src/main/index.ts
    • src/renderer/app.js
    • test/runtime-gateway.test.js
    • test/windows-app-install.test.js

    When the service exists, those files drop the spawn and call home start, home stop, and home service-status.

    Consumer-path tests

    These observe what a person or a calling program can see. They do not assert private helper names. This lane did not run them.

    1. Install on Linux and on macOS. Exit the installer terminal. GET http://localhost:8090/home/ returns the Home page. One host lock. One controller pid, matching status.json.
    2. elastos home stop. The GET fails. A new shell still shows stopped. elastos home --browser returns while the page stays up after that command exits.
    3. Kill the gateway pid. The service starts one new listener. Status is ready. A second listener does not appear. The controller pid from before the kill is gone, and the new status.json pid matches the new service pid.
    4. With Home up, start a System update and fail the download. The same controller pid remains. The GET still returns the page. The status phase is the failure phase, not a stopped Home.
    5. With Home up, elastos update --yes for a newer release. Afterwards one controller, one gateway, the new version, and the page answers. The writer lock is taken while the GET still succeeds, and the gateway pid changes only after that. The same shape for elastos update --rollback-to of a saved head.
    6. Kill the controller after the restart record is on disk and before the new child is ready. The service starts one controller. That run finishes recovery once. The page answers on the previous release. A second start does not loop, and the failed new release is not started again.
    7. A pending restart journal and ELASTOS_SERVICE=1. The process execs the retained controller. It does not exit 0 before that exec. A journal with no restart record exits 0, and the service does not start again by itself.
    8. Autostart off. A new login does not start Home. elastos home --browser starts it and leaves autostart off. The launcher checkbox off leaves the unit as it was. The checkbox on does not start Home by itself.
    9. Linux, linger accepted. Log out of every SSH session. The tunnel still opens Home. Reboot with no login. The tunnel still opens Home.
    10. Linux, linger refused. Install finishes. Status says runs only while you are logged in and prints the one loginctl command. After an admin runs that command, status shows the boot mode with no reinstall.
    11. Uninstall removes the unit file only. A neighbor plist or unit remains. A symlink at the unit path is left in place and the command fails. Linger is unchanged. Data remains.
    12. elastos serve while the unit is ready. The command fails. The unit stays ready.
    13. elastos home start while a serve holds the lock. Serve's pid stays. The GET of port 8090 is unchanged. elastos home adopt-service with no answer does the same. elastos home adopt-service --yes ends on localhost:8090 with the same sources.json bytes, or serve is back on the saved address and the data directory bytes are unchanged.
    14. A second data directory on the same account. Its home start fails and names both directories. The first unit file is byte for byte the same.
    15. A non-ElastOS program holds port 8090. Start fails with the existing lsof sentence. The unit does not restart in a loop.
    16. Stop the service while a Browser VM is up. After the stop timeout, that VM process is gone.
    17. Mac sleep, then wake. One GET of Home. No extra controller pid appears unless the child had already exited.
    18. Launcher tests on the 2.0.0 command set. The argv is home --browser on darwin, linux, and the WSL command. The install flow does not call the Open URL after start. The captured log shown to the person does not contain Keep this terminal open. Closing the window does not signal the pid. The Update button's argv is stop, then update --yes, then home --browser, on Linux and on Mac.
    19. After the service patch, the same launcher tests fail if the argv is gateway or home --browser. They expect home start, home stop, home service-status, and update --yes with no stop around it.

    The unit-text test passes the platform in. It does not call uname inside the assertion.

    Risks

    macOS still stops Home at logout. #518 accepts that. Status says runs only while you are logged in.

    Linger is an account setting. Other services for that user also stay up. The installer says that before the question. Uninstall does not turn it off.

    Terminal update and System update share a gap while the gateway child is stopped. A download does not enter that gap. If the controller is killed after the record is durable, the service starts one controller and recovery runs once. If an operator stops the service on purpose during that window, the exit is 0 and the service stays stopped until elastos home start. The journal remains for that start.

    The controller exec means the service pid becomes update-controller/runtime. launchd and systemd allow that exec because the pid does not change. A unit type that refused exec would break System update. The unit stays Type=simple.

    adopt-service can fail the gateway's principal-root check and return to elastos serve. The person sees that error. The design does not weaken the gateway check to make the move succeed.

    WSL depends on a Windows process to start the distro. A user service and linger do not replace the logon task. This lane did not boot the pinned 20240423 rootfs, so systemd inside that image is Canonical's 24.04 statement, not a local observation.

    Two programs can still try to own one data directory if a person runs home --foreground or the 2.0.0 launcher while the service is up. --foreground refuses when the unit is active. The 2.0.0 launcher is replaced by the service calls when the service ships. The host lock remains the one listener lock.

    The strongest other design is still a daemonized controller with no unit file. That fixes a closed terminal. It does not start at boot, and it does not stay up after the last logout. #519 is those two things. The unit is the existing mechanism on macOS and Linux. The launcher-as-supervisor design is weaker for the same reason as round 1. It cannot see a Jetson that is not running the app, and a gateway spawn cannot run System update.

  3. andersalm commented on Nov 8, 2026

    @andersalm
    ContributorAuthor

    @irzhywau @SashaMIT the design comment above (one OS user service owned by ElastOS, elastos home start|stop|service-status) is now also the plan for the desktop launcher: the launcher analysis on #521 (comment 6722288081) shows about 1,100 lines of launcher process control on Mac, plus about 760 on the Jetson branch and 840 on Windows, exist only because this command is missing, and most launcher review rounds on 7 and 8 Nov were in that code. Could you review the design before any code? Irzhy: lifecycle, update journal and the one admin question for linger. Sasha: what the launcher calls, and Windows (the logon step).

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

    documentationImprovements or additions to documentationenhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions