run-spaceapp 0.1.13 → 0.1.15-hostroot.0

package/README.md

@@ -19,8 +19,9 @@ 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
@@ -50,6 +51,27 @@ current user's platform config directory:
 
 Set `SPACEAPP_HOME` to an absolute path to use a dedicated installation root.
 
+Linux installations are isolated by default. A trusted single owner can opt
+into the personal host-root prerelease with:
+
+```bash
+npx --yes run-spaceapp@personal install --access host-root
+```
+
+This mounts the Linux `/` at `/host` read/write in the CLI service and runs CLI
+sessions as container root. The core service receives `/host` read-only. It can
+expose every host credential or make the operating system unbootable. It does
+not mount the Docker socket or enable a privileged container. Profiles control
+resources and managed Chromium, not access. Return to isolation without
+deleting persistent data with:
+
+```bash
+npx --yes run-spaceapp@personal install --access isolated
+```
+
+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 +81,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 +97,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,6 @@
 {
   "name": "run-spaceapp",
-  "version": "0.1.13",
+  "version": "0.1.15-hostroot.0",
   "description": "Cross-platform Docker launcher for the SpaceApp self-hosted agent workspace",
   "license": "Apache-2.0",
   "type": "module",
@@ -30,7 +30,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 +46,5 @@
     "access": "public",
     "provenance": true
   },
-  "gitHead": "14a0f1117141c24c3436768c23e819f482eaed70"
+  "gitHead": "5a8c1b92709bbd9f88b5ed869adb7ddfaea9092f"
 }

package/src/cli.mjs

@@ -16,6 +16,7 @@ import {
   removeCredential,
   removeWorkspace,
   prepareInstallation,
+  resolveInstallAccessMode,
   resolveInstallProfile,
   resolveSpaceAppHome,
   saveConfig,
@@ -29,12 +30,15 @@ import {
   prepareDockerCliPath,
   windowsPowerShellArgs
 } from "./prerequisites.mjs";
+import {
+  PACKAGE_VERSION,
+  UNIVERSAL_COMMAND
+} from "./package-info.mjs";
 
 const APPLICATION_READY_WAIT_MS = 3 * 60 * 1_000;
 const APPLICATION_READY_POLL_MS = 2_000;
 const APPLICATION_READY_MAX_ATTEMPTS = APPLICATION_READY_WAIT_MS / APPLICATION_READY_POLL_MS;
 const SETUP_STATUS_TIMEOUT_MS = 10_000;
-const UNIVERSAL_COMMAND = "npx --yes run-spaceapp@latest";
 const trustedCommands = new Set([
   "codesign",
   "docker",
@@ -70,11 +74,13 @@ export async function run(argv, {
   sleep = wait,
   persistSetupToken = writeSetupToken
 } = {}) {
-  await prepareDockerPath({ platform, env });
   const [command = "help", ...args] = argv;
   const root = resolveSpaceAppHome({ env, platform });
-  const version = await packageVersion();
+  const version = PACKAGE_VERSION;
 
+  if (command !== "install") {
+    await prepareDockerPath({ platform, env });
+  }
   if (command === "help" || command === "--help" || command === "-h") {
     stdout.write(helpText());
     return 0;
@@ -96,6 +102,7 @@ export async function run(argv, {
       execute,
       inspectResources,
       ensureDocker,
+      prepareDockerPath,
       request,
       sleep,
       persistSetupToken
@@ -268,15 +275,29 @@ 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.");
+  }
+  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, profile, accessMode });
 
   stdout.write(`Launcher version: ${version}\n`);
   stdout.write(
@@ -285,6 +306,9 @@ async function installCommand(args, {
   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");
@@ -317,7 +341,7 @@ 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) {
@@ -346,6 +370,24 @@ 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 restoreRuntimeAfterFailedInstall({
+        root,
+        stagedStateRoot,
+        existingConfig,
+        attemptedProfile: profile,
+        platform,
+        stdin,
+        stdout,
+        stderr,
+        execute
+      });
+      runtimeMutationAttempted = false;
+    }
+    return code;
+  };
   try {
     await commitInstallation(stagedStateRoot, result.config);
     const stagedComposeCommand = (action) =>
@@ -357,13 +399,14 @@ 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");
@@ -377,7 +420,7 @@ async function installCommand(args, {
         "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`
       );
-      return 1;
+      return await failAfterRuntimeMutation(1);
     }
 
     let setupStatus;
@@ -388,7 +431,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,8 +452,29 @@ 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);
+      }
+    }
+
+    if (profile === "light") {
+      const removeBrowserCode = await executeWithDockerDiagnostics(
+        execute,
+        composeCommand("removeBrowser", root, {
+          profile: "standard",
+          stateRoot: stagedStateRoot
+        }),
+        { stdin, stdout, stderr },
+        { platform, stderr }
+      );
+      if (removeBrowserCode !== 0) {
+        stderr.write(
+          "SpaceApp is ready, but the managed browser container could not be removed for the light profile.\n"
+        );
+        return await failAfterRuntimeMutation(removeBrowserCode);
       }
+    }
+
+    if (setupToken) {
       try {
         await persistSetupToken(root, setupToken);
       } catch {
@@ -418,11 +482,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`);
@@ -439,13 +504,81 @@ 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 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];
@@ -462,16 +595,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) {
@@ -968,11 +1116,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
 
@@ -980,7 +1123,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,8 +17,9 @@ 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";
@@ -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 });
@@ -138,11 +150,16 @@ export function installResourceChecks(resources) {
   ];
 }
 
-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 = {
@@ -413,6 +472,7 @@ export function composeCommand(action, root, options = {}) {
       "scripts/rotate-owner-setup-token.mjs",
       "--stdin"
     ],
+    removeBrowser: ["rm", "--stop", "--force", "spaceapp-browser"],
     purge: ["down", "--volumes", "--remove-orphans"]
   };
   let selected = actions[action];
@@ -461,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;
@@ -473,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 });
@@ -495,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 = {
@@ -507,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,12 @@
+import { readFileSync } from "node:fs";
+
+const manifest = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8")
+);
+
+export const PACKAGE_VERSION = manifest.version;
+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"
@@ -644,6 +644,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 +663,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 +677,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 +814,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 +831,7 @@ function linuxReentryCommand({ requestedProfile = "auto", noOpen = false } = {})
     "install",
     "--profile",
     requestedProfile,
+    ...installAccessArgs(requestedAccessMode, "Docker group re-entry"),
     ...(noOpen ? ["--no-open"] : [])
   ].map(shellQuote).join(" ");
 }
@@ -807,6 +840,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 +864,7 @@ export function windowsResumeScript({
     "install",
     "--profile",
     requestedProfile,
+    ...installAccessArgs(requestedAccessMode, "Windows resume"),
     ...(noOpen ? ["--no-open"] : [])
   ].join(" ");
   return [
@@ -847,6 +882,7 @@ export function windowsResumeScript({
 async function scheduleWindowsInstallResume({
   root,
   requestedProfile = "auto",
+  requestedAccessMode,
   noOpen = false,
   execute,
   stdin,
@@ -865,7 +901,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 +918,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("'", "'\\''")}'`;
 }