run-spaceapp 0.1.15-hostroot.2 → 0.1.18

package/README.md

@@ -41,6 +41,15 @@ The launcher defaults to the `light` profile on every system. Run
 `npx --yes run-spaceapp@latest install --profile standard` explicitly when
 managed Chromium is required and the host has the recommended resources.
 
+### First-install telemetry
+
+On a successful first install (not on upgrades or re-runs), the launcher sends
+one anonymous ping to `spaceapp.dev` with only: a random install ID, operating
+system and CPU architecture, launcher and runtime versions, and the install
+date. No personal data, files, or credentials are transmitted. Disable it with
+the environment variable `SPACEAPP_TELEMETRY=0` (or `false`); telemetry is
+otherwise on by default so the project can measure real adoption.
+
 Light mode retains every bundled CLI and the core data/workflow services while
 omitting managed Chromium. Resource limits are maximums, not immediate RAM or
 disk reservations. The launcher stores only non-secret configuration in the

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "run-spaceapp",
-  "version": "0.1.15-hostroot.2",
-  "spaceappRuntimeVersion": "0.1.15-hostroot.2",
+  "version": "0.1.18",
+  "spaceappRuntimeVersion": "0.1.18",
   "spaceappHostRootRuntimeCompatible": true,
   "description": "Cross-platform Docker launcher for the SpaceApp self-hosted agent workspace",
   "license": "Apache-2.0",
@@ -31,11 +31,12 @@
     "win32"
   ],
   "cpu": [
-    "x64"
+    "x64",
+    "arm64"
   ],
   "scripts": {
     "test": "node --test tests/*.test.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",
+    "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/telemetry.mjs && node --check src/prerequisites.mjs",
     "pack:dry-run": "npm pack --dry-run"
   },
   "repository": {
@@ -51,5 +52,5 @@
     "access": "public",
     "provenance": true
   },
-  "gitHead": "61c72544f7cb348803e2f1f71e467bf5aa86ded3"
+  "gitHead": "cf4692ac9bbf433e035042caba2c29a64c3d5827"
 }

package/src/cli.mjs

@@ -36,6 +36,10 @@ import {
   RUNTIME_VERSION,
   UNIVERSAL_COMMAND
 } from "./package-info.mjs";
+import {
+  INSTALL_PING_TIMEOUT_MS,
+  reportFirstInstallPing
+} from "./telemetry.mjs";
 
 const APPLICATION_READY_WAIT_MINUTES = 10;
 const APPLICATION_READY_WAIT_MS = APPLICATION_READY_WAIT_MINUTES * 60 * 1_000;
@@ -144,7 +148,7 @@ export async function run(argv, {
 
   if (["up", "down", "status", "logs"].includes(command)) {
     assertNoArgs(args, command);
-    return runtimeExecute(composeCommand(command, root, { profile: config.profile }), { stdin, stdout, stderr });
+    return runtimeExecute(composeCommand(command, root, { profile: config.profile, companionsEnabled: config.companionsEnabled }), { stdin, stdout, stderr });
   }
   if (command === "open") {
     assertNoArgs(args, "open");
@@ -193,12 +197,12 @@ export async function run(argv, {
       previousVersion: config.version
     };
     await writeRuntimeFiles(root, rollback);
-    const pullCode = await runtimeExecute(composeCommand("pull", root, { profile: rollback.profile }), { stdin, stdout, stderr });
+    const pullCode = await runtimeExecute(composeCommand("pull", root, { profile: rollback.profile, companionsEnabled: rollback.companionsEnabled }), { stdin, stdout, stderr });
     if (pullCode !== 0) {
       await writeRuntimeFiles(root, config);
       return pullCode;
     }
-    const upCode = await runtimeExecute(composeCommand("up", root, { profile: rollback.profile }), { stdin, stdout, stderr });
+    const upCode = await runtimeExecute(composeCommand("up", root, { profile: rollback.profile, companionsEnabled: rollback.companionsEnabled }), { stdin, stdout, stderr });
     if (upCode !== 0) {
       await writeRuntimeFiles(root, config);
       return upCode;
@@ -209,7 +213,7 @@ export async function run(argv, {
   }
   if (command === "backup") {
     assertNoArgs(args, command);
-    return runtimeExecute(composeCommand("backup", root, { profile: config.profile }), { stdin, stdout, stderr });
+    return runtimeExecute(composeCommand("backup", root, { profile: config.profile, companionsEnabled: config.companionsEnabled }), { stdin, stdout, stderr });
   }
   if (command === "restore") {
     assertNoArgs(args, command);
@@ -223,22 +227,22 @@ export async function run(argv, {
       throw new Error("Restore cancelled.");
     }
     const backupId = await selectLatestBackupId(root);
-    const backupCode = await runtimeExecute(composeCommand("backup", root, { profile: config.profile }), { stdin, stdout, stderr });
+    const backupCode = await runtimeExecute(composeCommand("backup", root, { profile: config.profile, companionsEnabled: config.companionsEnabled }), { stdin, stdout, stderr });
     if (backupCode !== 0) return backupCode;
-    const stopCode = await runtimeExecute(composeCommand("stopForRestore", root, { profile: config.profile }), { stdin, stdout, stderr });
+    const stopCode = await runtimeExecute(composeCommand("stopForRestore", root, { profile: config.profile, companionsEnabled: config.companionsEnabled }), { stdin, stdout, stderr });
     if (stopCode !== 0) return stopCode;
     const restoreCode = await runtimeExecute(
       composeCommand("restore", root, { backupId, profile: config.profile }),
       { stdin, stdout, stderr }
     );
     if (restoreCode !== 0) return restoreCode;
-    return runtimeExecute(composeCommand("up", root, { profile: config.profile }), { stdin, stdout, stderr });
+    return runtimeExecute(composeCommand("up", root, { profile: config.profile, companionsEnabled: config.companionsEnabled }), { stdin, stdout, stderr });
   }
   if (command === "uninstall") {
     if (args.length === 0) {
       stdout.write("Stopping and removing SpaceApp containers and network...\n");
       const code = await runtimeExecute(
-        composeCommand("down", root, { profile: config.profile }),
+        composeCommand("down", root, { profile: config.profile, companionsEnabled: config.companionsEnabled }),
         { stdin, stdout, stderr }
       );
       if (code === 0) {
@@ -260,7 +264,7 @@ export async function run(argv, {
       }
       stdout.write("Removing SpaceApp containers, network, and Docker volumes...\n");
       const code = await runtimeExecute(
-        composeCommand("purge", root, { profile: config.profile }),
+        composeCommand("purge", root, { profile: config.profile, companionsEnabled: config.companionsEnabled }),
         { stdin, stdout, stderr }
       );
       if (code === 0) {
@@ -299,7 +303,7 @@ async function installCommand(args, {
   sleep,
   persistSetupToken
 }) {
-  const { requestedProfile, requestedAccessMode, noOpen } = parseInstallArgs(args);
+  const { requestedProfile, requestedAccessMode, noOpen, companionsEnabled } = parseInstallArgs(args);
   const existingConfig = await loadExistingInstallation(root);
   const accessMode = resolveInstallAccessMode(
     requestedAccessMode,
@@ -324,7 +328,8 @@ async function installCommand(args, {
   const result = await prepareInstallation(root, {
     version: runtimeVersion,
     profile,
-    accessMode
+    accessMode,
+    ...(companionsEnabled ? { companionsEnabled } : {})
   });
 
   stdout.write(`Launcher version: ${launcherVersion}\n`);
@@ -417,6 +422,7 @@ async function installCommand(args, {
         stagedStateRoot,
         existingConfig,
         attemptedProfile: profile,
+        companionsEnabled,
         platform,
         stdin,
         stdout,
@@ -433,6 +439,7 @@ async function installCommand(args, {
       composeCommand(action, root, {
         profile,
         stateRoot: stagedStateRoot,
+        companionsEnabled,
         ...options
       });
     const pullCode = await executeWithDockerDiagnostics(
@@ -575,6 +582,23 @@ async function installCommand(args, {
 
     await commitInstallation(root, result.config);
     runtimeMutationAttempted = false;
+    try {
+      await reportFirstInstallPing({
+        existingConfig,
+        env,
+        platform,
+        arch,
+        launcherVersion,
+        runtimeVersion
+      }, {
+        request,
+        timeoutMs: INSTALL_PING_TIMEOUT_MS
+      });
+    } catch (error) {
+      stderr.write(
+        `SpaceApp installation report could not be sent: ${error?.message || String(error)}\n`
+      );
+    }
     stdout.write(`SpaceApp is ready at ${url}\n`);
     if (setupToken) {
       stdout.write(`One-time setup token: ${setupToken}\n`);
@@ -640,6 +664,7 @@ async function restoreRuntimeAfterFailedInstall({
   stagedStateRoot,
   existingConfig,
   attemptedProfile,
+  companionsEnabled,
   platform,
   stdin,
   stdout,
@@ -657,7 +682,8 @@ async function restoreRuntimeAfterFailedInstall({
       await commitInstallation(root, existingConfig);
       const restoreCode = await runtimeExecute(
         composeCommand("up", root, {
-          profile: existingConfig.profile
+          profile: existingConfig.profile,
+          companionsEnabled: existingConfig.companionsEnabled
         })
       );
       if (restoreCode === 0) {
@@ -684,7 +710,8 @@ async function restoreRuntimeAfterFailedInstall({
     const stopCode = await runtimeExecute(
       composeCommand("down", root, {
         profile: existingConfig?.profile ?? attemptedProfile,
-        stateRoot: existingConfig ? root : stagedStateRoot
+        stateRoot: existingConfig ? root : stagedStateRoot,
+        companionsEnabled: existingConfig?.companionsEnabled ?? companionsEnabled
       })
     );
     if (stopCode !== 0) {
@@ -703,12 +730,17 @@ function parseInstallArgs(args) {
   let requestedProfile = "auto";
   let requestedAccessMode;
   let noOpen = false;
+  let companionsEnabled = false;
   for (let index = 0; index < args.length; index += 1) {
     const argument = args[index];
     if (argument === "--no-open" && !noOpen) {
       noOpen = true;
       continue;
     }
+    if (argument === "--with-companions" && !companionsEnabled) {
+      companionsEnabled = true;
+      continue;
+    }
     if (argument === "--profile" && index + 1 < args.length) {
       requestedProfile = args[index + 1];
       index += 1;
@@ -728,7 +760,7 @@ function parseInstallArgs(args) {
       continue;
     }
     throw new Error(
-      `Usage: ${UNIVERSAL_COMMAND} install [--profile auto|light|standard] [--access isolated|host-root] [--no-open]`
+      `Usage: ${UNIVERSAL_COMMAND} install [--profile auto|light|standard] [--access isolated|host-root] [--with-companions] [--no-open]`
     );
   }
   if (
@@ -739,10 +771,10 @@ function parseInstallArgs(args) {
     )
   ) {
     throw new Error(
-      `Usage: ${UNIVERSAL_COMMAND} install [--profile auto|light|standard] [--access isolated|host-root] [--no-open]`
+      `Usage: ${UNIVERSAL_COMMAND} install [--profile auto|light|standard] [--access isolated|host-root] [--with-companions] [--no-open]`
     );
   }
-  return { requestedProfile, requestedAccessMode, noOpen };
+  return { requestedProfile, requestedAccessMode, noOpen, companionsEnabled };
 }
 
 async function loadExistingInstallation(root) {
@@ -804,7 +836,7 @@ async function credentialsCommand(args, { root, config, stdin, stdout, stderr, e
     const value = await readSecret(stdin, stdout, `Enter ${provider} credential: `);
     await writeCredential(root, provider, value);
     const syncCode = await execute(
-      composeCommand("syncCredentials", root, { profile: config.profile }),
+      composeCommand("syncCredentials", root, { profile: config.profile, companionsEnabled: config.companionsEnabled }),
       { stdin, stdout, stderr }
     );
     if (syncCode !== 0) {
@@ -820,7 +852,7 @@ async function credentialsCommand(args, { root, config, stdin, stdout, stderr, e
     }
     const removed = await removeCredential(root, provider);
     const syncCode = await execute(
-      composeCommand("syncCredentials", root, { profile: config.profile }),
+      composeCommand("syncCredentials", root, { profile: config.profile, companionsEnabled: config.companionsEnabled }),
       { stdin, stdout, stderr }
     );
     if (syncCode !== 0) {
@@ -838,13 +870,13 @@ async function providerCommand(args, { root, config, stdin, stdout, stderr, exec
     throw new Error(`Usage: ${UNIVERSAL_COMMAND} provider install claude`);
   }
   stdout.write("Installing Claude Code from Anthropic into this installation's private provider volume.\n");
-  return execute(composeCommand("installClaude", root, { profile: config.profile }), { stdin, stdout, stderr });
+  return execute(composeCommand("installClaude", root, { profile: config.profile, companionsEnabled: config.companionsEnabled }), { stdin, stdout, stderr });
 }
 
 async function ownerCommand(args, { root, config, stdin, stdout, stderr, execute }) {
   if (args.length === 1 && args[0] === "rotate-setup-token") {
     const token = randomBytes(32).toString("base64url");
-    const code = await execute(composeCommand("rotateOwnerSetupToken", root, { profile: config.profile }), {
+    const code = await execute(composeCommand("rotateOwnerSetupToken", root, { profile: config.profile, companionsEnabled: config.companionsEnabled }), {
       stdin,
       stdout,
       stderr,
@@ -865,7 +897,7 @@ async function ownerCommand(args, { root, config, stdin, stdout, stderr, execute
   if (password.length < 6) {
     throw new Error("Owner password must be at least 6 characters.");
   }
-  return execute(composeCommand("resetOwnerPassword", root, { profile: config.profile }), {
+  return execute(composeCommand("resetOwnerPassword", root, { profile: config.profile, companionsEnabled: config.companionsEnabled }), {
     stdin,
     stdout,
     stderr,
@@ -886,12 +918,12 @@ async function updateCommand(args, { root, config, version, stdin, stdout, stder
       previousVersion: config.version
     };
   await writeRuntimeFiles(root, updated);
-  const pullCode = await execute(composeCommand("pull", root, { profile: updated.profile }), { stdin, stdout, stderr });
+  const pullCode = await execute(composeCommand("pull", root, { profile: updated.profile, companionsEnabled: updated.companionsEnabled }), { stdin, stdout, stderr });
   if (pullCode !== 0) {
     await writeRuntimeFiles(root, config);
     return pullCode;
   }
-  const upCode = await execute(composeCommand("up", root, { profile: updated.profile }), { stdin, stdout, stderr });
+  const upCode = await execute(composeCommand("up", root, { profile: updated.profile, companionsEnabled: updated.companionsEnabled }), { stdin, stdout, stderr });
   if (upCode !== 0) {
     await writeRuntimeFiles(root, config);
     return upCode;
@@ -1258,7 +1290,7 @@ Usage: ${UNIVERSAL_COMMAND} <command>
        spaceapp <command>             Optional global launcher
 
   init                              Create a local SpaceApp installation
-  install [--profile auto|light|standard] [--access isolated|host-root] [--no-open]
+  install [--profile auto|light|standard] [--access isolated|host-root] [--with-companions] [--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

@@ -56,7 +56,7 @@ const SECRET_FIELD = /password|secret|token|api.?key|credential/i;
 const VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
 const BACKUP_ID_PATTERN = /^spaceapp-backup-\d{8}T\d{9}Z$/;
 const PROVIDERS = Object.freeze({
-  bundled: Object.freeze(["codex", "gemini", "opencode", "qwen", "kimi", "grok"]),
+  bundled: Object.freeze(["opencode", "codex", "gemini", "qwen", "kimi", "grok", "autohand", "cursor", "copilot"]),
   ownerInstalled: Object.freeze(["claude"]),
   experimental: Object.freeze(["deepseek"])
 });
@@ -70,7 +70,8 @@ const CONFIG_KEYS = new Set([
   "telemetry",
   "profile",
   "accessMode",
-  "workspaces"
+  "workspaces",
+  "companionsEnabled"
 ]);
 
 export function resolveSpaceAppHome({
@@ -153,7 +154,8 @@ export function installResourceChecks(resources) {
 export function createDefaultConfig({
   version,
   profile = "light",
-  accessMode = "isolated"
+  accessMode = "isolated",
+  companionsEnabled = false
 }) {
   assertVersion(version);
   if (profile !== "light" && profile !== "standard") {
@@ -169,6 +171,7 @@ export function createDefaultConfig({
     telemetry: false,
     profile,
     accessMode: resolvedAccessMode,
+    companionsEnabled,
     workspaces: []
   };
 }
@@ -207,6 +210,9 @@ export function validateConfig(config) {
   if (config.accessMode !== "isolated" && config.accessMode !== "host-root") {
     throw new Error("accessMode must be isolated or host-root.");
   }
+  if (typeof config.companionsEnabled !== "boolean") {
+    throw new Error("companionsEnabled must be boolean.");
+  }
   if (!Array.isArray(config.workspaces)) {
     throw new Error("workspaces must be an array.");
   }
@@ -234,7 +240,8 @@ function migrateConfig(config) {
     return {
       ...config,
       schemaVersion: CONFIG_SCHEMA_VERSION,
-      accessMode: "isolated"
+      accessMode: "isolated",
+      companionsEnabled: false
     };
   }
   if (config?.schemaVersion !== 1) {
@@ -248,7 +255,8 @@ function migrateConfig(config) {
     ...config,
     schemaVersion: CONFIG_SCHEMA_VERSION,
     profile: legacyProfiles[config.profile] ?? config.profile,
-    accessMode: "isolated"
+    accessMode: "isolated",
+    companionsEnabled: false
   };
 }
 
@@ -355,6 +363,7 @@ export function renderRuntimeEnv(config) {
     `SPACEAPP_POSTGRES_CPU_LIMIT=${settings.postgresCpuLimit}`,
     `SPACEAPP_TEMPORAL_MEMORY_LIMIT=${settings.temporalMemoryLimit}`,
     `SPACEAPP_TEMPORAL_CPU_LIMIT=${settings.temporalCpuLimit}`,
+    `SPACEAPP_COMPANIONS_ENABLED=${config.companionsEnabled ? "true" : "false"}`,
     ""
   ].join("\n");
 }
@@ -425,7 +434,8 @@ export function composeCommand(action, root, options = {}) {
     "-f", join(stateRoot, "compose.yml"),
     "-f", join(stateRoot, "compose.workspaces.yml"),
     "-f", join(stateRoot, "compose.host-access.yml"),
-    ...(profile === "standard" ? ["--profile", "standard"] : [])
+    ...(profile === "standard" ? ["--profile", "standard"] : []),
+    ...(options.companionsEnabled ? ["--profile", "companions"] : [])
   ];
   const actions = {
     up: ["up", "-d", "--remove-orphans"],
@@ -539,7 +549,8 @@ export async function writeRuntimeFiles(root, config) {
 export async function prepareInstallation(root, {
   version,
   profile,
-  accessMode
+  accessMode,
+  companionsEnabled
 }) {
   validateHome(root);
   await mkdir(root, { recursive: true, mode: 0o700 });
@@ -560,7 +571,8 @@ export async function prepareInstallation(root, {
     config = createDefaultConfig({
       version,
       profile: resolvedProfile ?? "light",
-      accessMode: resolveInstallAccessMode(accessMode)
+      accessMode: resolveInstallAccessMode(accessMode),
+      companionsEnabled
     });
   }
   if (config.version !== version) {
@@ -577,6 +589,9 @@ export async function prepareInstallation(root, {
   if (config.accessMode !== resolvedAccessMode) {
     config = { ...config, accessMode: resolvedAccessMode };
   }
+  if (companionsEnabled !== undefined && config.companionsEnabled !== companionsEnabled) {
+    config = { ...config, companionsEnabled };
+  }
   validateConfig(config);
 
   const postgresPasswordPath = join(root, "secrets", "postgres-password");

package/src/telemetry.mjs

@@ -0,0 +1,92 @@
+import { randomUUID } from "node:crypto";
+
+export const INSTALL_PING_ENDPOINT = "https://spaceapp.dev/install-ping.php";
+export const INSTALL_PING_TIMEOUT_MS = 5_000;
+export const TELEMETRY_DISABLED_VALUES = new Set(["0", "false", "no", "off"]);
+
+export function isTelemetryEnabled(env = process.env) {
+  const value = String(env.SPACEAPP_TELEMETRY ?? "").trim().toLowerCase();
+  if (value === "") {
+    return true;
+  }
+  return !TELEMETRY_DISABLED_VALUES.has(value);
+}
+
+export function normalizeOs(platform) {
+  if (platform === "win32") return "windows";
+  if (platform === "darwin") return "macos";
+  if (platform === "linux") return "linux";
+  return String(platform || "other");
+}
+
+export function buildInstallPing({
+  platform,
+  arch,
+  launcherVersion,
+  runtimeVersion,
+  now = new Date()
+}) {
+  return {
+    app: "spaceapp",
+    uid: randomUUID(),
+    os: normalizeOs(platform),
+    arch: String(arch || "unknown"),
+    version: String(launcherVersion || "unknown"),
+    runtime: String(runtimeVersion || "unknown"),
+    install_date: now.toISOString().slice(0, 10)
+  };
+}
+
+export async function sendInstallPing(
+  payload,
+  {
+    request = globalThis.fetch,
+    endpoint = INSTALL_PING_ENDPOINT,
+    timeoutMs = INSTALL_PING_TIMEOUT_MS
+  } = {}
+) {
+  if (typeof request !== "function") {
+    return false;
+  }
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await request(endpoint, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "user-agent": `spaceapp-launcher/${payload.version}`
+      },
+      body: JSON.stringify(payload),
+      signal: controller.signal
+    });
+    if (!response.ok) {
+      throw new Error(`install ping rejected with HTTP ${response.status}`);
+    }
+    return true;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export async function reportFirstInstallPing(
+  {
+    existingConfig,
+    env = process.env,
+    platform,
+    arch,
+    launcherVersion,
+    runtimeVersion
+  },
+  options = {}
+) {
+  if (existingConfig) {
+    return null;
+  }
+  if (!isTelemetryEnabled(env)) {
+    return null;
+  }
+  const payload = buildInstallPing({ platform, arch, launcherVersion, runtimeVersion });
+  const sent = await sendInstallPing(payload, options);
+  return sent ? payload : null;
+}

package/templates/compose.yml

@@ -117,6 +117,36 @@ services:
     networks:
       - spaceapp
 
+  codex-lb:
+    image: ghcr.io/soju06/codex-lb:1.22.0
+    profiles: ["companions"]
+    restart: unless-stopped
+    init: true
+    mem_limit: "768m"
+    cpus: "1.0"
+    ports:
+      - "${SPACEAPP_BIND_HOST}:2455:2455"
+      - "${SPACEAPP_BIND_HOST}:1455:1455"
+    volumes:
+      - spaceapp-codex-lb:/var/lib/codex-lb
+    networks:
+      - spaceapp
+
+  headroom:
+    image: ghcr.io/oll4com/headroom-codex-lb:code
+    profiles: ["companions"]
+    restart: unless-stopped
+    init: true
+    mem_limit: "768m"
+    cpus: "1.0"
+    environment:
+      HEADROOM_HOST: "0.0.0.0"
+      OPENAI_TARGET_API_URL: "${SPACEAPP_COMPANIONS_OPENAI_TARGET_API_URL:-}"
+    ports:
+      - "${SPACEAPP_BIND_HOST}:8787:8787"
+    networks:
+      - spaceapp
+
   postgres:
     image: pgvector/pgvector:0.8.3-pg17-trixie
     restart: unless-stopped
@@ -187,3 +217,4 @@ volumes:
   spaceapp-memory:
   spaceapp-postgres:
   spaceapp-workspaces:
+  spaceapp-codex-lb: