run-spaceapp 0.1.14 → 0.1.15-hostroot.1

package/README.md

@@ -19,12 +19,14 @@ The launcher requires Node.js 20.11 or newer, 4 CPUs, 8 GB RAM, and 15 GiB free
 disk. Keep `@latest` in the command so npm resolves the current release instead
 of matching an existing local launcher. If Docker is missing, the universal
 install command automatically installs it from official Docker sources on
-Windows, macOS, Ubuntu, Debian, Fedora, RHEL, and CentOS, starts it, and waits
-for Engine and Compose readiness before pulling images. Windows prefers
+Windows, macOS, Ubuntu, Debian, Fedora, RHEL, and CentOS, or with native
+`pacman` packages on Arch-family Linux including CachyOS. It starts Docker and
+waits for Engine and Compose readiness before pulling images. Windows prefers
 Windows Package Manager's hash-pinned Docker Desktop
 manifest and retains a signed direct-download fallback. Docker Desktop license
-acceptance and Linux `docker` group membership require confirmation inside the
-same command. On Windows, approve any UAC prompt required by WSL2 or Docker
+acceptance still requires confirmation. On Linux, the same command explains
+the root-equivalent `docker` group and adds the current user automatically.
+On Windows, approve any UAC prompt required by WSL2 or Docker
 Desktop. Use the **Command Prompt** profile because a restricted PowerShell
 policy can block npm's `npx.ps1` before SpaceApp starts. On Docker Desktop's
 first launch, select **Skip** in the top-right of the **Welcome to Docker**
@@ -50,6 +52,21 @@ current user's platform config directory:
 
 Set `SPACEAPP_HOME` to an absolute path to use a dedicated installation root.
 
+The `0.1.15-hostroot.1` personal candidate tests installer fixes while reusing
+the existing `0.1.15-hostroot.0` runtime images:
+
+```bash
+npx --yes run-spaceapp@personal install
+```
+
+This launcher-only candidate accepts isolated access on Linux, macOS, and
+Windows. It rejects `--access host-root` because no matching runtime images
+were rebuilt. The launcher reports version `.1` while `runtime.env` remains
+pinned to `.0`.
+
+Use the same `npx --yes run-spaceapp@personal` prefix for follow-up commands
+while this prerelease is installed.
+
 Provider API keys are read from masked standard input and written to
 restrictive files outside Git. OAuth and device-code credentials remain in
 isolated Docker provider state. Neither credential source is included in
@@ -59,10 +76,10 @@ Claude Code is not redistributed in SpaceApp images. Install the reviewed
 package as an explicit owner action with:
 
 ```bash
-npx --yes run-spaceapp@latest provider install claude
+npx --yes run-spaceapp@personal provider install claude
 ```
 
-Run `npx --yes run-spaceapp@latest help` for the complete command list. Full
+Run `npx --yes run-spaceapp@personal help` for the complete command list. Full
 documentation:
 
 - [Getting started](https://github.com/oll4com/spaceapp/blob/main/docs/getting-started.md)
@@ -75,16 +92,16 @@ After the stack passes readiness checks, the install command prints the fresh
 it expires before the owner is created, run:
 
 ```bash
-npx --yes run-spaceapp@latest owner rotate-setup-token
+npx --yes run-spaceapp@personal owner rotate-setup-token
 ```
 
 Common follow-up commands use the same reliable launcher prefix:
 
 ```bash
-npx --yes run-spaceapp@latest doctor
-npx --yes run-spaceapp@latest status
-npx --yes run-spaceapp@latest credentials list
-npx --yes run-spaceapp@latest uninstall
+npx --yes run-spaceapp@personal doctor
+npx --yes run-spaceapp@personal status
+npx --yes run-spaceapp@personal credentials list
+npx --yes run-spaceapp@personal uninstall
 ```
 
 Uninstall retains data by default and prints the separate

package/package.json

@@ -1,6 +1,8 @@
 {
   "name": "run-spaceapp",
-  "version": "0.1.14",
+  "version": "0.1.15-hostroot.1",
+  "spaceappRuntimeVersion": "0.1.15-hostroot.0",
+  "spaceappHostRootRuntimeCompatible": false,
   "description": "Cross-platform Docker launcher for the SpaceApp self-hosted agent workspace",
   "license": "Apache-2.0",
   "type": "module",
@@ -30,7 +32,7 @@
   ],
   "scripts": {
     "test": "node --test tests/*.test.mjs",
-    "check": "node --check bin/spaceapp.mjs && node --check src/index.mjs && node --check src/cli.mjs && node --check src/prerequisites.mjs",
+    "check": "node --check bin/spaceapp.mjs && node --check src/package-info.mjs && node --check src/index.mjs && node --check src/cli.mjs && node --check src/prerequisites.mjs",
     "pack:dry-run": "npm pack --dry-run"
   },
   "repository": {
@@ -46,5 +48,5 @@
     "access": "public",
     "provenance": true
   },
-  "gitHead": "f6956f38649503f6a9dd5c232d3d51d7bf2fa258"
+  "gitHead": "7e0543f784e614cd588bf54cd3228de3912d03d6"
 }

package/src/cli.mjs

@@ -16,6 +16,7 @@ import {
   removeCredential,
   removeWorkspace,
   prepareInstallation,
+  resolveInstallAccessMode,
   resolveInstallProfile,
   resolveSpaceAppHome,
   saveConfig,
@@ -29,12 +30,20 @@ import {
   prepareDockerCliPath,
   windowsPowerShellArgs
 } from "./prerequisites.mjs";
+import {
+  HOST_ROOT_RUNTIME_COMPATIBLE,
+  PACKAGE_VERSION,
+  RUNTIME_VERSION,
+  UNIVERSAL_COMMAND
+} from "./package-info.mjs";
 
-const APPLICATION_READY_WAIT_MS = 3 * 60 * 1_000;
+const APPLICATION_READY_WAIT_MINUTES = 10;
+const APPLICATION_READY_WAIT_MS = APPLICATION_READY_WAIT_MINUTES * 60 * 1_000;
 const APPLICATION_READY_POLL_MS = 2_000;
 const APPLICATION_READY_MAX_ATTEMPTS = APPLICATION_READY_WAIT_MS / APPLICATION_READY_POLL_MS;
+const APPLICATION_READY_PROGRESS_ATTEMPTS = 30_000 / APPLICATION_READY_POLL_MS;
+const APPLICATION_READY_LOG_INTERVAL_SECONDS = 120;
 const SETUP_STATUS_TIMEOUT_MS = 10_000;
-const UNIVERSAL_COMMAND = "npx --yes run-spaceapp@latest";
 const trustedCommands = new Set([
   "codesign",
   "docker",
@@ -68,25 +77,31 @@ export async function run(argv, {
   prepareDockerPath = prepareDockerCliPath,
   request = globalThis.fetch,
   sleep = wait,
-  persistSetupToken = writeSetupToken
+  persistSetupToken = writeSetupToken,
+  launcherVersion = PACKAGE_VERSION,
+  runtimeVersion = RUNTIME_VERSION,
+  hostRootRuntimeCompatible = HOST_ROOT_RUNTIME_COMPATIBLE
 } = {}) {
-  await prepareDockerPath({ platform, env });
   const [command = "help", ...args] = argv;
   const root = resolveSpaceAppHome({ env, platform });
-  const version = await packageVersion();
 
+  if (command !== "install") {
+    await prepareDockerPath({ platform, env });
+  }
   if (command === "help" || command === "--help" || command === "-h") {
     stdout.write(helpText());
     return 0;
   }
   if (command === "--version" || command === "-v") {
-    stdout.write(`${version}\n`);
+    stdout.write(`${launcherVersion}\n`);
     return 0;
   }
   if (command === "install") {
     return installCommand(args, {
       root,
-      version,
+      launcherVersion,
+      runtimeVersion,
+      hostRootRuntimeCompatible,
       platform,
       arch,
       env,
@@ -96,6 +111,7 @@ export async function run(argv, {
       execute,
       inspectResources,
       ensureDocker,
+      prepareDockerPath,
       request,
       sleep,
       persistSetupToken
@@ -103,7 +119,7 @@ export async function run(argv, {
   }
   if (command === "init") {
     assertNoArgs(args, "init");
-    const result = await initializeInstallation(root, { version });
+    const result = await initializeInstallation(root, { version: runtimeVersion });
     stdout.write(`SpaceApp initialized at ${root}\n`);
     if (result.setupToken) {
       stdout.write(`One-time setup token: ${result.setupToken}\n`);
@@ -156,7 +172,15 @@ export async function run(argv, {
     return ownerCommand(args, { root, config, stdin, stdout, stderr, execute: runtimeExecute });
   }
   if (command === "update") {
-    return updateCommand(args, { root, config, version, stdin, stdout, stderr, execute: runtimeExecute });
+    return updateCommand(args, {
+      root,
+      config,
+      version: runtimeVersion,
+      stdin,
+      stdout,
+      stderr,
+      execute: runtimeExecute
+    });
   }
   if (command === "rollback") {
     assertNoArgs(args, "rollback");
@@ -258,7 +282,9 @@ export async function run(argv, {
 
 async function installCommand(args, {
   root,
-  version,
+  launcherVersion,
+  runtimeVersion,
+  hostRootRuntimeCompatible,
   platform,
   arch,
   env,
@@ -268,28 +294,54 @@ async function installCommand(args, {
   execute,
   inspectResources,
   ensureDocker,
+  prepareDockerPath,
   request,
   sleep,
   persistSetupToken
 }) {
-  const { requestedProfile, noOpen } = parseInstallArgs(args);
+  const { requestedProfile, requestedAccessMode, noOpen } = parseInstallArgs(args);
+  const existingConfig = await loadExistingInstallation(root);
+  const accessMode = resolveInstallAccessMode(
+    requestedAccessMode,
+    existingConfig?.accessMode ?? "isolated"
+  );
+  if (accessMode === "host-root" && platform !== "linux") {
+    throw new Error("Host-root access is supported only on Linux.");
+  }
+  if (accessMode === "host-root" && !hostRootRuntimeCompatible) {
+    throw new Error(
+      "Host-root access is disabled for this launcher-only candidate because its runtime images were not rebuilt. Use --access isolated."
+    );
+  }
+  await prepareDockerPath({ platform, env });
   const resources = await inspectResources(root);
   const profile = resolveInstallProfile(requestedProfile, resources.totalMemoryBytes);
-  const existingConfig = await loadExistingInstallation(root);
-  const result = await prepareInstallation(root, { version, profile });
+  if (accessMode === "host-root") {
+    stderr.write(
+      "WARNING: host-root access lets SpaceApp CLI sessions read and modify the entire Linux host through /host, including credentials and system files.\n"
+    );
+  }
+  const result = await prepareInstallation(root, {
+    version: runtimeVersion,
+    profile,
+    accessMode
+  });
 
-  stdout.write(`Launcher version: ${version}\n`);
+  stdout.write(`Launcher version: ${launcherVersion}\n`);
   stdout.write(
-    `SpaceApp version: ${existingConfig?.version ?? "not installed"} -> ${result.config.version}\n`
+    `Runtime image version: ${existingConfig?.version ?? "not installed"} -> ${result.config.version}\n`
   );
   stdout.write(
     `Profile: ${existingConfig?.profile ?? "not configured"} -> ${result.config.profile}\n`
   );
+  stdout.write(
+    `Access: ${existingConfig?.accessMode ?? "not configured"} -> ${result.config.accessMode}\n`
+  );
   stdout.write(existingConfig
     ? "Preserved existing data, workspaces, credentials, secrets, and persistent Docker volumes.\n"
     : "Future refreshes preserve data, workspaces, credentials, secrets, and persistent Docker volumes.\n");
   stdout.write(
-    `Selected profile: ${profile} (${formatGigabytes(resources.totalMemoryBytes)} GB system memory detected).\n`
+    `Selected profile: ${profile} (${formatGibibytes(resources.totalMemoryBytes)} GiB system memory detected).\n`
   );
   stdout.write(`SpaceApp installation root: ${root}\n`);
   if (installResourceChecks(resources).some((check) => !check.ok)) {
@@ -317,14 +369,15 @@ async function installCommand(args, {
     stdout,
     stderr,
     execute,
-    installArgs: { root, requestedProfile, noOpen }
+    installArgs: { root, requestedProfile, requestedAccessMode, noOpen }
   });
-  if (prerequisiteResult.reexecuted || prerequisiteResult.code !== 0) {
-    if (prerequisiteResult.code !== 0) {
-      stderr.write(
-        `Installation stopped before downloading images. Fix the failed checks and run "${UNIVERSAL_COMMAND} install" again.\n`
-      );
-    }
+  if (prerequisiteResult.reexecuted) {
+    return prerequisiteResult.code;
+  }
+  if (prerequisiteResult.code !== 0) {
+    stderr.write(
+      `Installation stopped before downloading images. Fix the failed checks and run "${UNIVERSAL_COMMAND} install" again.\n`
+    );
     return prerequisiteResult.code;
   }
 
@@ -346,10 +399,42 @@ async function installCommand(args, {
     return doctorCode;
   }
   const stagedStateRoot = await mkdtemp(join(tmpdir(), "run-spaceapp-install-"));
+  let runtimeMutationAttempted = false;
+  const failAfterRuntimeMutation = async (code) => {
+    if (runtimeMutationAttempted) {
+      await reportInstallDiagnostics({
+        root,
+        stateRoot: stagedStateRoot,
+        profile,
+        platform,
+        stdin,
+        stdout,
+        stderr,
+        execute
+      });
+      await restoreRuntimeAfterFailedInstall({
+        root,
+        stagedStateRoot,
+        existingConfig,
+        attemptedProfile: profile,
+        platform,
+        stdin,
+        stdout,
+        stderr,
+        execute
+      });
+      runtimeMutationAttempted = false;
+    }
+    return code;
+  };
   try {
     await commitInstallation(stagedStateRoot, result.config);
-    const stagedComposeCommand = (action) =>
-      composeCommand(action, root, { profile, stateRoot: stagedStateRoot });
+    const stagedComposeCommand = (action, options = {}) =>
+      composeCommand(action, root, {
+        profile,
+        stateRoot: stagedStateRoot,
+        ...options
+      });
     const pullCode = await executeWithDockerDiagnostics(
       execute,
       stagedComposeCommand("pull"),
@@ -357,27 +442,72 @@ async function installCommand(args, {
       { platform, stderr }
     );
     if (pullCode !== 0) return pullCode;
+    runtimeMutationAttempted = true;
     const upCode = await executeWithDockerDiagnostics(
       execute,
       stagedComposeCommand("up"),
       { stdin, stdout, stderr },
       { platform, stderr }
     );
-    if (upCode !== 0) return upCode;
+    if (upCode !== 0) return await failAfterRuntimeMutation(upCode);
 
     const url = `http://${result.config.bindHost}:${result.config.port}`;
-    stdout.write("Waiting for SpaceApp services to become ready...\n");
+    stdout.write(
+      `Waiting up to ${APPLICATION_READY_WAIT_MINUTES} minutes for SpaceApp services to become ready...\n`
+    );
     const ready = await waitForApplicationReady({
       url,
       request,
-      sleep
+      sleep,
+      onProgress: async ({ elapsedSeconds }) => {
+        stdout.write(
+          `Still waiting for SpaceApp services (${elapsedSeconds} seconds elapsed; ` +
+          `up to ${APPLICATION_READY_WAIT_MINUTES} minutes)...\n`
+        );
+        try {
+          const statusCode = await executeWithDockerDiagnostics(
+            execute,
+            stagedComposeCommand("status"),
+            { stdin, stdout, stderr },
+            { platform, stderr }
+          );
+          if (statusCode !== 0) {
+            stderr.write(`SpaceApp service status check failed with Docker exit ${statusCode}.\n`);
+          }
+        } catch (error) {
+          stderr.write(
+            `SpaceApp could not collect status diagnostics: ${error?.message || String(error)}.\n`
+          );
+        }
+        if (
+          elapsedSeconds % APPLICATION_READY_LOG_INTERVAL_SECONDS === 0 &&
+          elapsedSeconds < APPLICATION_READY_WAIT_MINUTES * 60
+        ) {
+          stdout.write(`Showing recent startup logs after ${elapsedSeconds} seconds...\n`);
+          try {
+            const logsCode = await executeWithDockerDiagnostics(
+              execute,
+              stagedComposeCommand("logs", { lines: 50 }),
+              { stdin, stdout, stderr },
+              { platform, stderr }
+            );
+            if (logsCode !== 0) {
+              stderr.write(`SpaceApp startup log check failed with Docker exit ${logsCode}.\n`);
+            }
+          } catch (error) {
+            stderr.write(
+              `SpaceApp could not collect logs diagnostics: ${error?.message || String(error)}.\n`
+            );
+          }
+        }
+      }
     });
     if (!ready) {
       stderr.write(
-        "SpaceApp containers started, but the application did not become ready within 3 minutes.\n" +
-        `Run "${UNIVERSAL_COMMAND} status" and "${UNIVERSAL_COMMAND} logs", then run "${UNIVERSAL_COMMAND} install" again.\n`
+        `SpaceApp containers started, but the application did not become ready within ` +
+        `${APPLICATION_READY_WAIT_MINUTES} minutes.\n`
       );
-      return 1;
+      return await failAfterRuntimeMutation(1);
     }
 
     let setupStatus;
@@ -388,7 +518,7 @@ async function installCommand(args, {
         `SpaceApp is ready, but owner setup status could not be verified: ${error?.message || String(error)}\n` +
         `Run "${UNIVERSAL_COMMAND} status" and "${UNIVERSAL_COMMAND} logs", then run "${UNIVERSAL_COMMAND} install" again.\n`
       );
-      return 1;
+      return await failAfterRuntimeMutation(1);
     }
 
     let setupToken = null;
@@ -409,7 +539,7 @@ async function installCommand(args, {
         stderr.write(
           `SpaceApp is ready, but a fresh owner setup token could not be created. Run "${UNIVERSAL_COMMAND} owner rotate-setup-token".\n`
         );
-        return rotateCode;
+        return await failAfterRuntimeMutation(rotateCode);
       }
     }
 
@@ -427,7 +557,7 @@ async function installCommand(args, {
         stderr.write(
           "SpaceApp is ready, but the managed browser container could not be removed for the light profile.\n"
         );
-        return removeBrowserCode;
+        return await failAfterRuntimeMutation(removeBrowserCode);
       }
     }
 
@@ -439,11 +569,12 @@ async function installCommand(args, {
           "SpaceApp accepted a new setup token, but it could not be saved locally.\n" +
           `Run "${UNIVERSAL_COMMAND} owner rotate-setup-token" to obtain a usable token.\n`
         );
-        return 1;
+        return await failAfterRuntimeMutation(1);
       }
     }
 
     await commitInstallation(root, result.config);
+    runtimeMutationAttempted = false;
     stdout.write(`SpaceApp is ready at ${url}\n`);
     if (setupToken) {
       stdout.write(`One-time setup token: ${setupToken}\n`);
@@ -460,13 +591,117 @@ async function installCommand(args, {
       stderr.write(`Could not open SpaceApp automatically. Open ${url} manually.\n`);
     }
     return 0;
+  } catch (error) {
+    await failAfterRuntimeMutation(1);
+    throw error;
   } finally {
     await rm(stagedStateRoot, { recursive: true, force: true });
   }
 }
 
+async function reportInstallDiagnostics({
+  root,
+  stateRoot,
+  profile,
+  platform,
+  stdin,
+  stdout,
+  stderr,
+  execute
+}) {
+  stderr.write("Collecting SpaceApp service status and recent logs before rollback...\n");
+  for (const action of ["status", "logs"]) {
+    try {
+      const code = await executeWithDockerDiagnostics(
+        execute,
+        composeCommand(action, root, {
+          profile,
+          stateRoot,
+          lines: 200
+        }),
+        { stdin, stdout, stderr },
+        { platform, stderr }
+      );
+      if (code !== 0) {
+        stderr.write(
+          `SpaceApp could not collect ${action} diagnostics (Docker exit ${code}).\n`
+        );
+      }
+    } catch (error) {
+      stderr.write(
+        `SpaceApp could not collect ${action} diagnostics: ${error?.message || String(error)}.\n`
+      );
+    }
+  }
+}
+
+async function restoreRuntimeAfterFailedInstall({
+  root,
+  stagedStateRoot,
+  existingConfig,
+  attemptedProfile,
+  platform,
+  stdin,
+  stdout,
+  stderr,
+  execute
+}) {
+  const runtimeExecute = (spec) => executeWithDockerDiagnostics(
+    execute,
+    spec,
+    { stdin, stdout, stderr },
+    { platform, stderr }
+  );
+  try {
+    if (existingConfig) {
+      await commitInstallation(root, existingConfig);
+      const restoreCode = await runtimeExecute(
+        composeCommand("up", root, {
+          profile: existingConfig.profile
+        })
+      );
+      if (restoreCode === 0) {
+        if (existingConfig.profile === "light") {
+          const cleanupCode = await runtimeExecute(
+            composeCommand("removeBrowser", root, {
+              profile: "standard"
+            })
+          );
+          if (cleanupCode !== 0) {
+            stderr.write(
+              "The previous SpaceApp runtime was restored, but an inactive browser container may remain.\n"
+            );
+          }
+        }
+        stderr.write("The previous SpaceApp runtime and access mode were restored.\n");
+        return;
+      }
+      stderr.write(
+        "The previous SpaceApp runtime could not be restored; stopping the partially updated runtime.\n"
+      );
+    }
+
+    const stopCode = await runtimeExecute(
+      composeCommand("down", root, {
+        profile: existingConfig?.profile ?? attemptedProfile,
+        stateRoot: existingConfig ? root : stagedStateRoot
+      })
+    );
+    if (stopCode !== 0) {
+      stderr.write(
+        "The partially updated SpaceApp runtime could not be stopped automatically. Run the install command again immediately.\n"
+      );
+    }
+  } catch (error) {
+    stderr.write(
+      `SpaceApp could not restore or stop the partially updated runtime: ${error?.message || String(error)}\n`
+    );
+  }
+}
+
 function parseInstallArgs(args) {
   let requestedProfile = "auto";
+  let requestedAccessMode;
   let noOpen = false;
   for (let index = 0; index < args.length; index += 1) {
     const argument = args[index];
@@ -483,16 +718,31 @@ function parseInstallArgs(args) {
       requestedProfile = argument.slice("--profile=".length);
       continue;
     }
+    if (argument === "--access" && index + 1 < args.length) {
+      requestedAccessMode = args[index + 1];
+      index += 1;
+      continue;
+    }
+    if (argument.startsWith("--access=")) {
+      requestedAccessMode = argument.slice("--access=".length);
+      continue;
+    }
     throw new Error(
-      `Usage: ${UNIVERSAL_COMMAND} install [--profile auto|light|standard] [--no-open]`
+      `Usage: ${UNIVERSAL_COMMAND} install [--profile auto|light|standard] [--access isolated|host-root] [--no-open]`
     );
   }
-  if (!["auto", "light", "standard"].includes(requestedProfile)) {
+  if (
+    !["auto", "light", "standard"].includes(requestedProfile) ||
+    (
+      requestedAccessMode !== undefined &&
+      !["isolated", "host-root"].includes(requestedAccessMode)
+    )
+  ) {
     throw new Error(
-      `Usage: ${UNIVERSAL_COMMAND} install [--profile auto|light|standard] [--no-open]`
+      `Usage: ${UNIVERSAL_COMMAND} install [--profile auto|light|standard] [--access isolated|host-root] [--no-open]`
     );
   }
-  return { requestedProfile, noOpen };
+  return { requestedProfile, requestedAccessMode, noOpen };
 }
 
 async function loadExistingInstallation(root) {
@@ -612,8 +862,8 @@ async function ownerCommand(args, { root, config, stdin, stdout, stderr, execute
     );
   }
   const password = await readSecret(stdin, stdout, "New owner password: ");
-  if (password.length < 12) {
-    throw new Error("Owner password must be at least 12 characters.");
+  if (password.length < 6) {
+    throw new Error("Owner password must be at least 6 characters.");
   }
   return execute(composeCommand("resetOwnerPassword", root, { profile: config.profile }), {
     stdin,
@@ -628,11 +878,13 @@ async function updateCommand(args, { root, config, version, stdin, stdout, stder
     throw new Error(`Usage: ${UNIVERSAL_COMMAND} update [version]`);
   }
   const targetVersion = args[0] || version;
-  const updated = {
-    ...config,
-    version: targetVersion,
-    previousVersion: config.version
-  };
+  const updated = targetVersion === config.version
+    ? config
+    : {
+      ...config,
+      version: targetVersion,
+      previousVersion: config.version
+    };
   await writeRuntimeFiles(root, updated);
   const pullCode = await execute(composeCommand("pull", root, { profile: updated.profile }), { stdin, stdout, stderr });
   if (pullCode !== 0) {
@@ -720,6 +972,7 @@ async function waitForApplicationReady({
   url,
   request,
   sleep,
+  onProgress,
   maxAttempts = APPLICATION_READY_MAX_ATTEMPTS
 }) {
   if (typeof request !== "function") {
@@ -749,6 +1002,15 @@ async function waitForApplicationReady({
       }
       if (attempt < maxAttempts && !controller.signal.aborted) {
         await sleep(APPLICATION_READY_POLL_MS);
+        const completedAttempts = attempt + 1;
+        if (
+          typeof onProgress === "function" &&
+          completedAttempts % APPLICATION_READY_PROGRESS_ATTEMPTS === 0
+        ) {
+          await onProgress({
+            elapsedSeconds: completedAttempts * APPLICATION_READY_POLL_MS / 1_000
+          });
+        }
       }
     }
     return false;
@@ -981,7 +1243,7 @@ function dockerEngineHelp(platform) {
   return `Start Docker Engine, verify the current user can access it, then run "${UNIVERSAL_COMMAND} doctor" again.`;
 }
 
-function formatGigabytes(bytes) {
+function formatGibibytes(bytes) {
   return Math.floor((bytes / 1024 ** 3) * 10) / 10;
 }
 
@@ -989,11 +1251,6 @@ function wait(milliseconds) {
   return new Promise((resolve) => setTimeout(resolve, milliseconds));
 }
 
-async function packageVersion() {
-  const packageJson = new URL("../package.json", import.meta.url);
-  return JSON.parse(await readFile(packageJson, "utf8")).version;
-}
-
 function helpText() {
   return `SpaceApp self-hosted launcher
 
@@ -1001,7 +1258,7 @@ Usage: ${UNIVERSAL_COMMAND} <command>
        spaceapp <command>             Optional global launcher
 
   init                              Create a local SpaceApp installation
-  install [--profile auto|light|standard] [--no-open]
+  install [--profile auto|light|standard] [--access isolated|host-root] [--no-open]
                                     Install prerequisites, initialize, and start
   up | down | status | logs         Manage the Docker application
   open                              Open the local web application

package/src/index.mjs

@@ -17,11 +17,12 @@ import {
   normalizeWorkspaceName,
   stripTrailingLineEndings
 } from "./string-utils.mjs";
+import { UNIVERSAL_COMMAND } from "./package-info.mjs";
 
-const CONFIG_SCHEMA_VERSION = 2;
+const CONFIG_SCHEMA_VERSION = 3;
 const MIN_INSTALL_CPU_COUNT = 4;
-const MIN_INSTALL_MEMORY_BYTES = 8_000_000_000;
-const MIN_INSTALL_MEMORY_LABEL = "8 GB";
+const MIN_INSTALL_MEMORY_BYTES = 7 * 1024 ** 3;
+const MIN_INSTALL_MEMORY_LABEL = "7 GiB usable (8 GB-class system)";
 const MIN_INSTALL_FREE_DISK_BYTES = 15 * 1024 ** 3;
 const PROFILE_RUNTIME_SETTINGS = Object.freeze({
   light: Object.freeze({
@@ -68,6 +69,7 @@ const CONFIG_KEYS = new Set([
   "port",
   "telemetry",
   "profile",
+  "accessMode",
   "workspaces"
 ]);
 
@@ -101,6 +103,16 @@ export function resolveInstallProfile(requestedProfile, totalMemoryBytes) {
   return "light";
 }
 
+export function resolveInstallAccessMode(requestedMode, existingMode = "isolated") {
+  if (requestedMode === undefined) {
+    return existingMode;
+  }
+  if (requestedMode === "isolated" || requestedMode === "host-root") {
+    return requestedMode;
+  }
+  throw new Error("Install access mode must be isolated or host-root.");
+}
+
 export async function inspectSystemResources(root) {
   validateHome(root);
   await mkdir(root, { recursive: true, mode: 0o700 });
@@ -128,21 +140,26 @@ export function installResourceChecks(resources) {
     {
       name: "Memory",
       ok: totalMemoryBytes >= MIN_INSTALL_MEMORY_BYTES,
-      detail: `${formatGibibytes(totalMemoryBytes)} GB available; ${MIN_INSTALL_MEMORY_LABEL} required`
+      detail: `${formatGibibytes(totalMemoryBytes)} GiB available; ${MIN_INSTALL_MEMORY_LABEL} required`
     },
     {
       name: "Free disk",
       ok: freeDiskBytes >= MIN_INSTALL_FREE_DISK_BYTES,
-      detail: `${formatGibibytes(freeDiskBytes)} GB available; ${formatGibibytes(MIN_INSTALL_FREE_DISK_BYTES)} GB required`
+      detail: `${formatGibibytes(freeDiskBytes)} GiB available; ${formatGibibytes(MIN_INSTALL_FREE_DISK_BYTES)} GiB required`
     }
   ];
 }
 
-export function createDefaultConfig({ version, profile = "light" }) {
+export function createDefaultConfig({
+  version,
+  profile = "light",
+  accessMode = "isolated"
+}) {
   assertVersion(version);
   if (profile !== "light" && profile !== "standard") {
     throw new Error("Default config requires a resolved light or standard profile.");
   }
+  const resolvedAccessMode = resolveInstallAccessMode(accessMode);
   return {
     schemaVersion: CONFIG_SCHEMA_VERSION,
     version,
@@ -151,6 +168,7 @@ export function createDefaultConfig({ version, profile = "light" }) {
     port: 4911,
     telemetry: false,
     profile,
+    accessMode: resolvedAccessMode,
     workspaces: []
   };
 }
@@ -186,6 +204,9 @@ export function validateConfig(config) {
   if (!["light", "standard"].includes(config.profile)) {
     throw new Error("profile must be light or standard.");
   }
+  if (config.accessMode !== "isolated" && config.accessMode !== "host-root") {
+    throw new Error("accessMode must be isolated or host-root.");
+  }
   if (!Array.isArray(config.workspaces)) {
     throw new Error("workspaces must be an array.");
   }
@@ -209,6 +230,13 @@ export async function loadConfig(root) {
 }
 
 function migrateConfig(config) {
+  if (config?.schemaVersion === 2) {
+    return {
+      ...config,
+      schemaVersion: CONFIG_SCHEMA_VERSION,
+      accessMode: "isolated"
+    };
+  }
   if (config?.schemaVersion !== 1) {
     return config;
   }
@@ -219,7 +247,8 @@ function migrateConfig(config) {
   return {
     ...config,
     schemaVersion: CONFIG_SCHEMA_VERSION,
-    profile: legacyProfiles[config.profile] ?? config.profile
+    profile: legacyProfiles[config.profile] ?? config.profile,
+    accessMode: "isolated"
   };
 }
 
@@ -351,6 +380,35 @@ export function renderWorkspaceCompose(config) {
   ].join("\n");
 }
 
+export function renderHostAccessCompose(config) {
+  validateConfig(config);
+  if (config.accessMode === "isolated") {
+    return "services: {}\n";
+  }
+  const hostMount = (readOnly) => [
+    "      - type: bind",
+    '        source: "/"',
+    '        target: "/host"',
+    `        read_only: ${readOnly}`,
+    "        bind:",
+    "          propagation: rslave"
+  ];
+  return [
+    "services:",
+    "  spaceapp-core:",
+    "    environment:",
+    '      SPACE_CLI_WORKSPACE_ROOT: "/host"',
+    "    volumes:",
+    ...hostMount(true),
+    "  spaceapp-cli:",
+    "    environment:",
+    '      SPACEAPP_CLI_HOST_ROOT_ACCESS: "true"',
+    "    volumes:",
+    ...hostMount(false),
+    ""
+  ].join("\n");
+}
+
 export function composeCommand(action, root, options = {}) {
   validateHome(root);
   const stateRoot = options.stateRoot ?? root;
@@ -366,6 +424,7 @@ export function composeCommand(action, root, options = {}) {
     "--env-file", join(stateRoot, "runtime.env"),
     "-f", join(stateRoot, "compose.yml"),
     "-f", join(stateRoot, "compose.workspaces.yml"),
+    "-f", join(stateRoot, "compose.host-access.yml"),
     ...(profile === "standard" ? ["--profile", "standard"] : [])
   ];
   const actions = {
@@ -462,7 +521,7 @@ export async function selectLatestBackupId(root) {
     .at(-1);
   if (!backupId) {
     throw new Error(
-      'No portable backup exists. Run "npx --yes run-spaceapp@latest backup" before restore.'
+      `No portable backup exists. Run "${UNIVERSAL_COMMAND} backup" before restore.`
     );
   }
   return backupId;
@@ -474,11 +533,13 @@ export async function writeRuntimeFiles(root, config) {
   await mkdir(root, { recursive: true, mode: 0o700 });
   await atomicWrite(join(root, "runtime.env"), renderRuntimeEnv(config));
   await atomicWrite(join(root, "compose.workspaces.yml"), renderWorkspaceCompose(config));
+  await atomicWrite(join(root, "compose.host-access.yml"), renderHostAccessCompose(config));
 }
 
 export async function prepareInstallation(root, {
   version,
-  profile
+  profile,
+  accessMode
 }) {
   validateHome(root);
   await mkdir(root, { recursive: true, mode: 0o700 });
@@ -496,7 +557,11 @@ export async function prepareInstallation(root, {
     if (error?.code !== "ENOENT") {
       throw error;
     }
-    config = createDefaultConfig({ version, profile: resolvedProfile ?? "light" });
+    config = createDefaultConfig({
+      version,
+      profile: resolvedProfile ?? "light",
+      accessMode: resolveInstallAccessMode(accessMode)
+    });
   }
   if (config.version !== version) {
     config = {
@@ -508,6 +573,10 @@ export async function prepareInstallation(root, {
   if (resolvedProfile !== undefined) {
     config = { ...config, profile: resolvedProfile };
   }
+  const resolvedAccessMode = resolveInstallAccessMode(accessMode, config.accessMode);
+  if (config.accessMode !== resolvedAccessMode) {
+    config = { ...config, accessMode: resolvedAccessMode };
+  }
   validateConfig(config);
 
   const postgresPasswordPath = join(root, "secrets", "postgres-password");

package/src/package-info.mjs

@@ -0,0 +1,32 @@
+import { readFileSync } from "node:fs";
+
+const manifest = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8")
+);
+
+const VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+
+function requireVersion(value, field) {
+  if (typeof value !== "string" || !VERSION_PATTERN.test(value)) {
+    throw new Error(`run-spaceapp package.json must declare a valid ${field}.`);
+  }
+  return value;
+}
+
+export const PACKAGE_VERSION = requireVersion(manifest.version, "version");
+export const RUNTIME_VERSION = requireVersion(
+  manifest.spaceappRuntimeVersion,
+  "spaceappRuntimeVersion"
+);
+if (typeof manifest.spaceappHostRootRuntimeCompatible !== "boolean") {
+  throw new Error(
+    "run-spaceapp package.json must declare spaceappHostRootRuntimeCompatible as a boolean."
+  );
+}
+export const HOST_ROOT_RUNTIME_COMPATIBLE =
+  manifest.spaceappHostRootRuntimeCompatible;
+export const LAUNCHER_DIST_TAG = PACKAGE_VERSION.includes("-hostroot.")
+  ? "personal"
+  : "latest";
+export const UNIVERSAL_COMMAND = `npx --yes run-spaceapp@${LAUNCHER_DIST_TAG}`;
+export const UNIVERSAL_INSTALL_COMMAND = `${UNIVERSAL_COMMAND} install`;

package/src/prerequisites.mjs

@@ -8,10 +8,10 @@ import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { UNIVERSAL_INSTALL_COMMAND } from "./package-info.mjs";
 
 const DOCKER_TERMS_URL = "https://www.docker.com/legal/docker-subscription-service-agreement/";
 const DOWNLOAD_TIMEOUT_MS = 30 * 60 * 1_000;
-const UNIVERSAL_INSTALL_COMMAND = "npx --yes run-spaceapp@latest install";
 const WINDOWS_DOCKER_DOWNLOADS = Object.freeze({
   x64: "https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe",
   arm64: "https://desktop.docker.com/win/main/arm64/Docker%20Desktop%20Installer.exe"
@@ -20,6 +20,8 @@ const MAC_DOCKER_DOWNLOADS = Object.freeze({
   x64: "https://desktop.docker.com/mac/main/amd64/Docker.dmg",
   arm64: "https://desktop.docker.com/mac/main/arm64/Docker.dmg"
 });
+const MAC_ADMIN_PASSWORD_PROMPT =
+  "SpaceApp Mac administrator password (input hidden): ";
 // Sources:
 // https://learn.microsoft.com/windows/package-manager/winget/install
 // https://github.com/microsoft/winget-pkgs/tree/master/manifests/d/Docker/DockerDesktop
@@ -444,8 +446,8 @@ async function ensureMacDocker({
       mounted = true;
       const signatureCode = await execute({
         command: "codesign",
-        args: ["--verify", "--deep", "--strict", "--verbose=2", mountedApplication]
-      }, { stdin, stdout: null, stderr });
+        args: ["--verify", "--deep", "--strict", mountedApplication]
+      }, { stdin, stdout: null, stderr: null });
       if (signatureCode !== 0) {
         stderr.write("The Docker Desktop application signature is not valid. Installation was stopped.\n");
         return { code: 1, reexecuted: false };
@@ -453,17 +455,33 @@ async function ensureMacDocker({
       const gatekeeperCode = await execute({
         command: "spctl",
         args: ["--assess", "--type", "execute", "--verbose=4", mountedApplication]
-      }, { stdin, stdout: null, stderr });
+      }, { stdin, stdout: null, stderr: null });
       if (gatekeeperCode !== 0) {
         stderr.write("macOS Gatekeeper did not accept Docker Desktop. Installation was stopped.\n");
         return { code: 1, reexecuted: false };
       }
+      stdout.write("Docker Desktop signature and macOS trust verification passed.\n");
+      stdout.write(
+        "macOS administrator authorization is required to install Docker Desktop.\n" +
+        "Enter the password for your Mac administrator account—not a Docker or SpaceApp password.\n" +
+        "Characters are not displayed while you type. SpaceApp does not read, store, or log this password.\n"
+      );
       const installCode = await execute({
         command: "sudo",
-        args: [installer, "--accept-license", `--user=${username}`]
+        args: [
+          "-p",
+          MAC_ADMIN_PASSWORD_PROMPT,
+          installer,
+          "--accept-license",
+          `--user=${username}`
+        ]
       }, { stdin, stdout, stderr });
       if (installCode !== 0) {
-        stderr.write("Docker Desktop installation failed before SpaceApp downloaded any images.\n");
+        stderr.write(
+          "macOS authorization failed. Docker Desktop must be installed by a Mac administrator account.\n" +
+          "Enter that account's password—not a Docker or SpaceApp password—and rerun the same SpaceApp install command.\n" +
+          "No SpaceApp images were downloaded.\n"
+        );
         return { code: installCode, reexecuted: false };
       }
     } finally {
@@ -553,24 +571,19 @@ async function ensureLinuxDocker({
     stderr.write("A valid non-root Linux username is required for Docker Engine access.\n");
     return { code: 1, reexecuted: false };
   }
-  const accepted = await confirmQuestion({
-    stdin,
-    stdout,
-    question: [
+  stdout.write(
+    [
       "Docker's official post-install flow uses the docker group.",
       "Membership grants root-level privileges on this host.",
-      `Add ${username} to the docker group and continue? [y/N] `
-    ].join("\n")
-  });
-  if (!accepted) {
-    stderr.write("Docker group membership was not changed.\n");
-    return { code: 1, reexecuted: false };
-  }
+      `Adding ${username} to the docker group automatically and continuing.`
+    ].join("\n") + "\n"
+  );
   const groupCode = await execute(
     { command: "sudo", args: ["usermod", "-aG", "docker", username] },
     { stdin, stdout, stderr }
   );
   if (groupCode !== 0) {
+    stderr.write(`SpaceApp could not add ${username} to the docker group.\n`);
     return { code: groupCode, reexecuted: false };
   }
 
@@ -644,6 +657,10 @@ async function installLinuxDockerEngine({
   download
 }) {
   const id = String(release?.ID || "").toLowerCase();
+  const idFamily = new Set([
+    id,
+    ...String(release?.ID_LIKE || "").toLowerCase().split(/\s+/).filter(Boolean)
+  ]);
   if (id === "ubuntu" || id === "debian") {
     return installAptDockerEngine({
       arch,
@@ -659,6 +676,13 @@ async function installLinuxDockerEngine({
   if (id === "fedora" || id === "rhel" || id === "centos") {
     return installDnfDockerEngine({ id, stdin, stdout, stderr, execute });
   }
+  if (
+    idFamily.has("arch") ||
+    idFamily.has("archlinux") ||
+    idFamily.has("cachyos")
+  ) {
+    return installPacmanDockerEngine({ stdin, stdout, stderr, execute });
+  }
   stderr.write(
     `Automatic Docker Engine installation is not yet supported for Linux distribution "${id || "unknown"}". ` +
     "Install Docker Engine and the Compose plugin from https://docs.docker.com/engine/install/ and rerun the same command.\n"
@@ -666,6 +690,23 @@ async function installLinuxDockerEngine({
   return 1;
 }
 
+function installPacmanDockerEngine({ stdin, stdout, stderr, execute }) {
+  return execute(
+    {
+      command: "sudo",
+      args: [
+        "pacman",
+        "-S",
+        "--needed",
+        "--noconfirm",
+        "docker",
+        "docker-compose"
+      ]
+    },
+    { stdin, stdout, stderr }
+  );
+}
+
 async function installAptDockerEngine({
   arch,
   id,
@@ -786,7 +827,11 @@ async function readLinuxOsRelease() {
   return values;
 }
 
-function linuxReentryCommand({ requestedProfile = "auto", noOpen = false } = {}) {
+function linuxReentryCommand({
+  requestedProfile = "auto",
+  requestedAccessMode,
+  noOpen = false
+} = {}) {
   if (!["auto", "light", "standard"].includes(requestedProfile)) {
     throw new Error("Invalid SpaceApp profile for Docker group re-entry.");
   }
@@ -799,6 +844,7 @@ function linuxReentryCommand({ requestedProfile = "auto", noOpen = false } = {})
     "install",
     "--profile",
     requestedProfile,
+    ...installAccessArgs(requestedAccessMode, "Docker group re-entry"),
     ...(noOpen ? ["--no-open"] : [])
   ].map(shellQuote).join(" ");
 }
@@ -807,6 +853,7 @@ export function windowsResumeScript({
   executable = process.execPath,
   entrypoint = fileURLToPath(new URL("../bin/spaceapp.mjs", import.meta.url)),
   requestedProfile = "auto",
+  requestedAccessMode,
   noOpen = false
 } = {}) {
   if (!["auto", "light", "standard"].includes(requestedProfile)) {
@@ -830,6 +877,7 @@ export function windowsResumeScript({
     "install",
     "--profile",
     requestedProfile,
+    ...installAccessArgs(requestedAccessMode, "Windows resume"),
     ...(noOpen ? ["--no-open"] : [])
   ].join(" ");
   return [
@@ -847,6 +895,7 @@ export function windowsResumeScript({
 async function scheduleWindowsInstallResume({
   root,
   requestedProfile = "auto",
+  requestedAccessMode,
   noOpen = false,
   execute,
   stdin,
@@ -865,7 +914,7 @@ async function scheduleWindowsInstallResume({
   await mkdir(root, { recursive: true, mode: 0o700 });
   await writeFile(
     resumePath,
-    windowsResumeScript({ requestedProfile, noOpen }),
+    windowsResumeScript({ requestedProfile, requestedAccessMode, noOpen }),
     { encoding: "utf8", mode: 0o600 }
   );
   const code = await execute(
@@ -882,6 +931,16 @@ async function scheduleWindowsInstallResume({
   return code;
 }
 
+function installAccessArgs(requestedAccessMode, context) {
+  if (requestedAccessMode === undefined) {
+    return [];
+  }
+  if (requestedAccessMode === "isolated" || requestedAccessMode === "host-root") {
+    return ["--access", requestedAccessMode];
+  }
+  throw new Error(`Invalid SpaceApp access mode for ${context}.`);
+}
+
 function shellQuote(value) {
   return `'${String(value).replaceAll("'", "'\\''")}'`;
 }