alexandr 0.3.0 → 0.3.1

package/README.md

@@ -65,7 +65,8 @@ rotation), `up` and `update` offer a quick re-sign-in on the spot — or run
 | `alexandr connect` | Print the `alexandr://connect` link / paste-string |
 | `alexandr link` | Re-link this runtime to your account (`--force` re-registers) |
 | `alexandr login` | Refresh the runtime-image pull credential (sign in, no re-register) |
-| `alexandr update` | Update the runtime image (`--to <tag>`, `--rollback`); auto-snapshots `/data` first (`--no-backup` to skip) |
+| `alexandr update` | Update the runtime image (`--to <tag>`, `--rollback`); auto-snapshots `/data` first (`--no-backup` to skip); keeps the newest 3 snapshots |
+| `alexandr updater serve` | The updater sidecar's entrypoint — runs inside its container; `up` starts it, so the desktop app's update sheet can press "Update now" (`--no-updater` on `up` opts out) |
 | `alexandr backup` / `restore <f>` | Archive / restore the data volume |
 | `alexandr config set <k> <v>` | Edit config (`ai.url`, `model`, `port`, `domain`, …) |
 | `alexandr init` | Write a committable `./alexandr` config folder |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alexandr",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Run the alexandr workspace runtime locally (npx alexandr up), and develop alexandr apps against a workspace (alexandr app link | dev | build | deploy).",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -57,6 +57,8 @@ const TABLE = {
   ls: cmd.ls, logs: cmd.logs, config: cmd.config, init: cmd.init,
   update: cmd.update, connect: cmd.connect, link: cmd.link, login: cmd.login, backup: cmd.backup,
   restore: cmd.restore, completion, doctor: cmd.doctor, version,
+  // The sidecar's entrypoint (`alexandr updater serve`) — the same package, in a container.
+  updater: cmd.updater,
 };
 
 export async function run(argv = process.argv.slice(2)) {

package/src/commands.js

@@ -15,8 +15,9 @@ import {
 } from "./docker.js";
 import {
   resolveInstance, isMaterialized, materialize, readEnv, envHas, setEnv,
-  unsetEnv, kernelPort,
+  unsetEnv, kernelPort, pruneSnapshots,
 } from "./instance.js";
+export { updater } from "./updater.js";
 import { kernelUrl, health, version as kVersion, waitHealthy, waitPosture } from "./probe.js";
 import { buildConnect } from "./connect.js";
 import {
@@ -79,6 +80,71 @@ function archiveVolume(vol, outPath) {
   return r.status === 0;
 }
 
+/** Snapshots kept per box (owner, 2026-09-08): the newest three `pre-update-*.tgz`. */
+const SNAPSHOT_KEEP = 3;
+
+/**
+ * The compose PROFILES this instance runs with — every `up`/`down` must pass the same set, or
+ * a profiled service is left behind (a `down` without the profile leaves the updater running).
+ *
+ *  · `public`  — Caddy, when a domain is configured.
+ *  · `updater` — the updater sidecar (self-host-update-sidecar.md), unless the operator opted
+ *    out (`ALEXANDR_UPDATER=off`, written by `--no-updater`) — or unless THIS process is the
+ *    sidecar's own child (`ALEXANDR_UPDATER_INSIDE=1`): a container cannot recreate itself
+ *    mid-run, so the recipe run from inside leaves the `updater` service alone.
+ */
+function profileArgs(dir) {
+  const env = readEnv(dir);
+  const args = [];
+  if (envHas(dir, "ALEXANDR_DOMAIN")) args.push("--profile", "public");
+  const updaterOff = (env.ALEXANDR_UPDATER || "").trim().toLowerCase() === "off";
+  if (!updaterOff && process.env.ALEXANDR_UPDATER_INSIDE !== "1") args.push("--profile", "updater");
+  return args;
+}
+
+/**
+ * What the updater sidecar needs written into `.env` before compose can start it: the instance
+ * dir at its host path (mounted at the same path inside), the compose project name (so the
+ * recipe run from inside drives THIS project, not a re-derived one), and the sidecar's image
+ * tag — pinned to the CLI that installed it, so the sidecar's version is the CLI's version.
+ */
+function stampUpdaterEnv(inst) {
+  setEnv(inst.dir, "ALEXANDR_INSTANCE_DIR", hostPath(inst.dir));
+  setEnv(inst.dir, "ALEXANDR_COMPOSE_PROJECT", inst.projectName);
+  if (process.env.ALEXANDR_UPDATER_INSIDE !== "1") setEnv(inst.dir, "ALEXANDR_UPDATER_IMAGE_TAG", pkgVersion());
+}
+
+/**
+ * ⚠ THE SIDECAR MUST NEVER COST A BOOT. With the `updater` profile on, a `compose up` that
+ * cannot pull the updater image (the tag not yet published for this CLI version, an
+ * air-gapped host, a registry that serves the kernel but not this package) fails the WHOLE
+ * `up` — kernel included. So when `up` fails and the profile was on, probe the updater's
+ * pull alone; if THAT is what failed, say so once and retry without the sidecar. Nothing is
+ * persisted: the next `up` tries the sidecar again. Returns the compose status.
+ */
+function composeUpWithoutSidecarIfNeeded(inst, args, offline) {
+  if (!args.includes("updater")) return 1;
+  if (!offline) {
+    const probe = composeCapture(inst.dir, inst.projectName, ["--profile", "updater", "pull", "updater"]);
+    if (probe.status === 0) return 1; // the sidecar image is fine — the failure is elsewhere
+  }
+  warn("The updater sidecar's image isn't available yet — starting without it (the terminal `alexandr update` still works; the sidecar comes back on the next `alexandr up`).");
+  const without = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--profile" && args[i + 1] === "updater") {
+      i++;
+      continue;
+    }
+    without.push(args[i]);
+  }
+  return compose(inst.dir, inst.projectName, without).status;
+}
+
+function pkgVersion() {
+  const p = path.resolve(fileURLToPath(import.meta.url), "..", "..", "package.json");
+  return JSON.parse(fs.readFileSync(p, "utf8")).version;
+}
+
 function isRunning(dir, projectName) {
   const r = composeCapture(dir, projectName, ["ps", "--status", "running", "-q", "kernel"]);
   return r.status === 0 && r.stdout !== "";
@@ -182,6 +248,11 @@ export async function up(flags) {
   if (typeof flags.name === "string" && flags.name.trim()) {
     setEnv(inst.dir, "ALEXANDR_WORKSPACE_NAME", flags.name.trim());
   }
+  // The updater sidecar (self-host-update-sidecar.md): on by default, `--no-updater` records
+  // the opt-out in .env so every later compose call agrees; `--updater` turns it back on.
+  if (flags["no-updater"]) setEnv(inst.dir, "ALEXANDR_UPDATER", "off");
+  else if (flags.updater === true) unsetEnv(inst.dir, "ALEXANDR_UPDATER");
+  stampUpdaterEnv(inst);
 
   // Sign-in comes FIRST (account-required-runtimes D3) — now literally: the entitlement
   // gate fires before anything system-mutating, so a refused account walks away from a
@@ -209,9 +280,7 @@ export async function up(flags) {
   }
 
   const offline = Boolean(flags.offline || flags["no-pull"]);
-  const args = [];
-  if (hasDomain) args.push("--profile", "public");
-  args.push("up", "-d", "--pull", offline ? "never" : "missing");
+  const args = [...profileArgs(inst.dir), "up", "-d", "--pull", offline ? "never" : "missing"];
 
   step(`Starting alexandr (${inst.mode} · ${inst.dir})…`);
   let r = compose(inst.dir, inst.projectName, args);
@@ -219,7 +288,9 @@ export async function up(flags) {
     step("Retrying the start…");
     r = compose(inst.dir, inst.projectName, args);
   }
-  if (r.status !== 0) fail("`docker compose up` failed — see the output above. Try `alexandr doctor`.", EXIT.RUNTIME);
+  if (r.status !== 0 && composeUpWithoutSidecarIfNeeded(inst, args, offline) !== 0) {
+    fail("`docker compose up` failed — see the output above. Try `alexandr doctor`.", EXIT.RUNTIME);
+  }
 
   const base = kernelUrl(port);
   step("Waiting for the kernel to come up…");
@@ -236,7 +307,7 @@ export async function up(flags) {
     );
     await runLinkCeremony(inst, flags);
     step("Restarting the runtime with the fresh credentials…");
-    const restartArgs = hasDomain ? ["--profile", "public", "up", "-d"] : ["up", "-d"];
+    const restartArgs = [...profileArgs(inst.dir), "up", "-d"];
     if (compose(inst.dir, inst.projectName, restartArgs).status !== 0) {
       fail("`docker compose up` failed after re-linking — see the output above.", EXIT.RUNTIME);
     }
@@ -298,7 +369,7 @@ export async function down(flags) {
   const inst = resolveInstance(flags);
   if (!isMaterialized(inst.dir)) fail("No alexandr instance here. Run `alexandr up` first.", EXIT.NO_INSTANCE);
   step("Stopping alexandr (data preserved)…");
-  const r = compose(inst.dir, inst.projectName, ["down"]);
+  const r = compose(inst.dir, inst.projectName, [...profileArgs(inst.dir), "down"]);
   if (r.status === 0) ok("Stopped. Your data volume is untouched — `alexandr up` to resume.");
 }
 
@@ -351,7 +422,7 @@ export async function destroy(flags) {
     else warn("Couldn't remove it from your account — remove it from your account page instead.");
   }
   step(wipe ? "Removing alexandr AND its data volume…" : "Removing alexandr containers (data preserved)…");
-  const r = compose(inst.dir, inst.projectName, wipe ? ["down", "-v"] : ["down"]);
+  const r = compose(inst.dir, inst.projectName, [...profileArgs(inst.dir), "down", ...(wipe ? ["-v"] : [])]);
   if (r.status === 0) ok(wipe ? "Destroyed, including /data." : "Containers removed; /data volume kept.");
 }
 
@@ -530,6 +601,15 @@ export async function update(flags) {
     await ensureLinked(inst, flags);
   }
 
+  // The compose file is the CLI's template, re-staged on every `up`; an update re-stages it
+  // too, so the FIRST update after the updater sidecar shipped installs the sidecar
+  // (self-host-update-sidecar.md §6) — the image pin lives in .env, never in the file.
+  // ⚠ Not from inside the sidecar: its own compose run must not rewrite the file it is
+  // executing against, and it never carries the newer template anyway.
+  if (process.env.ALEXANDR_UPDATER_INSIDE !== "1") {
+    materialize(inst.dir);
+    stampUpdaterEnv(inst);
+  }
   const prevImage = readEnv(inst.dir).ALEXANDR_IMAGE || `${IMAGE_BASE}:latest`;
   const base = kernelUrl(kernelPort(inst.dir));
   const before = (await kVersion(base))?.version ?? "?";
@@ -580,14 +660,19 @@ export async function update(flags) {
       fail("Pull failed — check your network / the image tag.", EXIT.RUNTIME);
     }
   }
-  const args = [];
-  if (envHas(inst.dir, "ALEXANDR_DOMAIN")) args.push("--profile", "public");
-  args.push("up", "-d", "--pull", offline ? "never" : "missing");
+  const args = [...profileArgs(inst.dir), "up", "-d", "--pull", offline ? "never" : "missing"];
   step("Applying the update (data preserved)…");
-  if (compose(inst.dir, inst.projectName, args).status !== 0) fail("Update failed — see output above.", EXIT.RUNTIME);
+  if (compose(inst.dir, inst.projectName, args).status !== 0 && composeUpWithoutSidecarIfNeeded(inst, args, offline) !== 0) {
+    fail("Update failed — see output above.", EXIT.RUNTIME);
+  }
 
   const after = (await waitHealthy(base))?.version ?? "?";
   ok(`Updated: ${before} → ${after}`);
+  // The newest three snapshots stay (owner, 2026-09-08); a box updated from the app every
+  // train would otherwise fill its disk with tarballs. Pruned AFTER the update is verified, so
+  // a failed update never deletes the snapshot it may need.
+  const pruned = pruneSnapshots(inst.dir, SNAPSHOT_KEEP);
+  if (pruned.length) log(dim(`  Pruned ${pruned.length} older snapshot(s); the newest ${SNAPSHOT_KEEP} are kept in backups/.`));
 }
 
 // ---------------------------------------------------------------- connect

package/src/completion.js

@@ -29,6 +29,7 @@ export const COMMANDS = [
   { name: "link", usage: "link", summary: "Re-link this runtime to your alexandr account (--force re-registers)" },
   { name: "login", usage: "login", summary: "Refresh the runtime-image pull credential (sign in, no re-register)" },
   { name: "update", usage: "update", summary: "Update the runtime image (--to <tag>, --rollback)" },
+  { name: "updater", usage: "updater serve", summary: "Run the updater sidecar (inside its container; `up` starts it)" },
   { name: "backup", usage: "backup", summary: "Archive the data volume (--out <file>)" },
   { name: "restore", usage: "restore <f>", summary: "Restore a data-volume archive (--yes)" },
   { name: "config", usage: "config", summary: "get | set | list | unset  (e.g. alexandr config set ai.url …)" },

package/src/instance.js

@@ -24,7 +24,12 @@ export function resolveInstance(flags = {}) {
   const cwdProject = path.resolve(process.cwd(), "alexandr");
   if (flags.dir) {
     const dir = path.resolve(String(flags.dir));
-    return { dir, mode: "project", name: path.basename(dir), projectName: `alexandr-${sha8(dir)}` };
+    // `--project` pins the compose project NAME beside `--dir`: the updater sidecar runs the
+    // recipe from inside a container where the instance dir is mounted at its host path, and
+    // the project it must drive is the one the host created — a name re-derived in there
+    // (a global instance's is not the dir hash) would make compose start a SECOND copy.
+    const pinned = typeof flags.project === "string" && flags.project.trim() ? flags.project.trim() : null;
+    return { dir, mode: "project", name: path.basename(dir), projectName: pinned ?? `alexandr-${sha8(dir)}` };
   }
   if (fs.existsSync(path.join(cwdProject, "docker-compose.yml"))) {
     return { dir: cwdProject, mode: "project", name: path.basename(path.dirname(cwdProject)), projectName: `alexandr-${sha8(cwdProject)}` };
@@ -95,6 +100,34 @@ export function unsetEnv(dir, key) {
 }
 
 // The loopback kernel port for this instance (host side), honoring the .env.
+/**
+ * Keep the newest `keep` pre-update snapshots in `<dir>/backups` and delete the rest
+ * (owner, 2026-09-08: keep 3). Every update — the terminal verb and the sidecar's button —
+ * snapshots /data first, and a box that is updated often would otherwise fill its disk with
+ * tarballs nobody will restore. Returns the paths removed. Only `pre-update-*.tgz` is touched:
+ * a snapshot the operator took with `alexandr backup` is theirs to keep.
+ */
+export function pruneSnapshots(dir, keep = 3) {
+  const backups = path.join(dir, "backups");
+  if (!fs.existsSync(backups)) return [];
+  const snaps = fs
+    .readdirSync(backups)
+    .filter((f) => /^pre-update-.*\.tgz$/.test(f))
+    .map((f) => ({ f, at: fs.statSync(path.join(backups, f)).mtimeMs }))
+    .sort((a, b) => b.at - a.at);
+  const removed = [];
+  for (const { f } of snaps.slice(Math.max(0, keep))) {
+    const p = path.join(backups, f);
+    try {
+      fs.unlinkSync(p);
+      removed.push(p);
+    } catch {
+      /* a snapshot that will not go is not worth failing an update over */
+    }
+  }
+  return removed;
+}
+
 export function kernelPort(dir) {
   const v = readEnv(dir).ALEXANDR_KERNEL_PORT;
   const n = v ? Number(v) : 3030;

package/src/updater.js

@@ -0,0 +1,276 @@
+// `alexandr updater serve` — the self-host UPDATER SIDECAR (self-host-update-sidecar.md).
+//
+// The kernel runs inside the container an update replaces and must never hold the Docker
+// socket (untrusted app code makes the container the security boundary). So the box carries
+// ONE more process that may: this server, running as the `updater` service of the instance's
+// compose file with the socket mounted, listening on a private unix socket the kernel mounts
+// read-only. Two verbs — `GET /status`, `POST /update` — and nothing else.
+//
+// ⚠ ONE RECIPE, TWO DOORS. This does not implement an update. `POST /update` spawns the SAME
+// `alexandr update` the operator types, as a child process (`update()` calls `fail()`, which
+// exits — a child keeps the server alive), and reads its progress off its own step lines. A
+// change to the recipe is therefore a change to both doors, by construction.
+//
+// ⚠ THE SIDECAR NAMES THE TARGET, NEVER THE CALLER. The kernel may ask for `to`, but the
+// version that runs is the release FEED's current one (or the recorded previous image, for a
+// rollback); a request naming anything else is refused. A compromised kernel cannot make the
+// host pull an image of its choosing.
+
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { readEnv } from "./instance.js";
+import { log, warn, fail, dim } from "./util.js";
+import { EXIT } from "./exit.js";
+
+export const STATE_FILE = ".update-state.json";
+const DEFAULT_SOCKET = "/run/alexandr/updater.sock";
+const DEFAULT_FEED = "https://api.alexandr.so/releases/stable";
+
+const pkg = JSON.parse(
+  fs.readFileSync(path.resolve(fileURLToPath(import.meta.url), "..", "..", "package.json"), "utf8"),
+);
+
+/** The feed a linked box reads — the same derivation the kernel's update check uses. */
+export function feedUrlFor(env) {
+  const explicit = (env.ALEXANDR_RELEASES_URL || "").trim();
+  if (explicit) return explicit;
+  const cp = (env.ALEXANDR_CP_URL || "").trim().replace(/\/+$/, "");
+  return cp ? `${cp}/releases/stable` : DEFAULT_FEED;
+}
+
+/** The phase a `alexandr update` step line announces — the sidecar's progress is the CLI's own words. */
+export function phaseOf(line) {
+  if (/Snapshotting/i.test(line)) return "snapshotting";
+  if (/Pulling the runtime image|Offline update/i.test(line)) return "pulling";
+  if (/Applying the update/i.test(line)) return "restarting";
+  if (/Updated:/i.test(line)) return "done";
+  return null;
+}
+
+/**
+ * The request handler, separated from the socket so a test can drive it with a fake runner
+ * and a fake feed. `deps.runUpdate({ to, rollback, onPhase })` resolves `{ ok, error?, from?, to? }`.
+ */
+export function createUpdaterHandler(deps) {
+  const {
+    instanceDir,
+    feedUrl,
+    runUpdate,
+    fetchImpl = fetch,
+    updaterVersion = pkg.version,
+    now = () => new Date().toISOString(),
+  } = deps;
+  const statePath = path.join(instanceDir, STATE_FILE);
+  let state = readState(statePath) ?? { state: "idle" };
+  let running = null;
+
+  function write(next) {
+    state = { ...next, updaterVersion };
+    try {
+      fs.mkdirSync(instanceDir, { recursive: true });
+      fs.writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`);
+    } catch {
+      // The state file is a courtesy to a kernel that restarts mid-update; losing it is not fatal.
+    }
+    return state;
+  }
+
+  async function feedCurrent() {
+    const res = await fetchImpl(feedUrl, { signal: AbortSignal.timeout(10_000) });
+    if (!res.ok) throw new Error(`the release feed answered ${res.status}`);
+    const body = await res.json();
+    const v = body?.current?.version;
+    if (typeof v !== "string" || !v) throw new Error("the release feed names no current version");
+    return v;
+  }
+
+  async function status() {
+    return { status: 200, body: { ...state, updaterVersion } };
+  }
+
+  async function update(body) {
+    if (running) return { status: 409, body: { error: "an update is already running", ...state } };
+    const rollback = body?.rollback === true;
+    let to = null;
+    if (!rollback) {
+      let current;
+      try {
+        current = await feedCurrent();
+      } catch (e) {
+        return { status: 502, body: { error: `could not read the release feed: ${e.message}` } };
+      }
+      const asked = typeof body?.to === "string" && body.to.trim() ? body.to.trim().replace(/^v/, "") : null;
+      if (asked && asked !== current) {
+        return {
+          status: 409,
+          body: { error: `refused: ${asked} is not the feed's current version (${current})`, current },
+        };
+      }
+      to = current;
+    }
+    const startedAt = now();
+    write({ state: "updating", phase: "starting", to, rollback, startedAt });
+    running = (async () => {
+      let result;
+      try {
+        result = await runUpdate({
+          to,
+          rollback,
+          onPhase: (phase) => write({ ...state, state: "updating", phase }),
+        });
+      } catch (e) {
+        result = { ok: false, error: e?.message || String(e) };
+      }
+      if (result.ok) {
+        write({ state: "done", phase: "done", to: result.to ?? to, from: result.from ?? null, rollback, startedAt, finishedAt: now() });
+      } else {
+        write({ state: "failed", phase: state.phase ?? "starting", to, rollback, startedAt, finishedAt: now(), error: result.error || "update failed" });
+      }
+      running = null;
+    })();
+    return { status: 202, body: { started: true, to, rollback, startedAt } };
+  }
+
+  return {
+    async handle(method, urlPath, body) {
+      if (method === "GET" && urlPath === "/status") return status();
+      if (method === "POST" && urlPath === "/update") return update(body ?? {});
+      return { status: 404, body: { error: "not found" } };
+    },
+    /** Test seam: wait for an in-flight update to settle. */
+    settled: () => running ?? Promise.resolve(),
+  };
+}
+
+function readState(p) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(p, "utf8"));
+    // A box that restarted mid-update: the child is gone with the old process, so "updating" is stale.
+    return parsed?.state === "updating" ? { ...parsed, state: "failed", error: "the updater restarted mid-update" } : parsed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * THE recipe, as a child: `alexandr update --dir <instance> --project <name> [--to v|--rollback] --yes`.
+ * `ALEXANDR_UPDATER_INSIDE=1` tells `update` it is running from the sidecar, so its compose
+ * calls leave the `updater` service alone (a container cannot recreate itself mid-run).
+ */
+export function spawnUpdate({ instanceDir, projectName, bin }) {
+  return ({ to, rollback, onPhase }) =>
+    new Promise((resolve) => {
+      const args = [bin, "update", "--dir", instanceDir, "--project", projectName, "--yes"];
+      if (rollback) args.push("--rollback");
+      else if (to) args.push("--to", `v${to}`);
+      const child = spawn(process.execPath, args, {
+        env: { ...process.env, ALEXANDR_UPDATER_INSIDE: "1", FORCE_COLOR: "0", NO_COLOR: "1" },
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+      let out = "";
+      let from = null;
+      let after = null;
+      const onData = (chunk) => {
+        const text = String(chunk);
+        out += text;
+        process.stdout.write(text);
+        for (const line of text.split("\n")) {
+          const phase = phaseOf(line);
+          if (phase) onPhase(phase);
+          const m = /Updated:\s*(\S+)\s*→\s*(\S+)/.exec(line);
+          if (m) [, from, after] = m;
+        }
+      };
+      child.stdout.on("data", onData);
+      child.stderr.on("data", onData);
+      child.on("close", (code) => {
+        if (code === 0) resolve({ ok: true, from, to: after ?? to });
+        else resolve({ ok: false, error: lastLine(out) || `alexandr update exited ${code}` });
+      });
+      child.on("error", (e) => resolve({ ok: false, error: e.message }));
+    });
+}
+
+// The child's last line, without colour codes or the CLI's own status glyph (`✗ `, `▸ `): the
+// words are the operator's, the decoration was the terminal's.
+const lastLine = (s) =>
+  s
+    .split("\n")
+    .map((l) => l.replace(/\x1b\[[0-9;]*m/g, "").replace(/^[✗✓▸!]\s*/u, "").trim())
+    .filter(Boolean)
+    .pop() ?? "";
+
+// ---------------------------------------------------------------- the verb
+export async function updater(flags) {
+  const sub = flags._.shift();
+  if (sub !== "serve") fail("usage: alexandr updater serve  (runs inside the `updater` sidecar)", EXIT.USAGE);
+  const instanceDir = String(flags.dir || process.env.ALEXANDR_INSTANCE_DIR || "").trim();
+  const projectName = String(flags.project || process.env.ALEXANDR_COMPOSE_PROJECT || "").trim();
+  if (!instanceDir || !projectName) {
+    fail("updater serve needs the instance directory and compose project (ALEXANDR_INSTANCE_DIR / ALEXANDR_COMPOSE_PROJECT).", EXIT.USAGE);
+  }
+  const socketPath = String(flags.socket || process.env.ALEXANDR_UPDATER_SOCKET || DEFAULT_SOCKET);
+  const env = readEnv(instanceDir);
+  const feedUrl = feedUrlFor({ ...env, ...process.env });
+  const bin = path.resolve(fileURLToPath(import.meta.url), "..", "..", "bin.js");
+  const handler = createUpdaterHandler({
+    instanceDir,
+    feedUrl,
+    runUpdate: spawnUpdate({ instanceDir, projectName, bin }),
+  });
+
+  fs.mkdirSync(path.dirname(socketPath), { recursive: true });
+  try {
+    fs.unlinkSync(socketPath);
+  } catch {
+    /* no stale socket */
+  }
+  const server = http.createServer(async (req, res) => {
+    let body = "";
+    req.on("data", (c) => {
+      body += c;
+      if (body.length > 4096) req.destroy();
+    });
+    req.on("end", async () => {
+      let parsed = {};
+      if (body) {
+        try {
+          parsed = JSON.parse(body);
+        } catch {
+          res.writeHead(400, { "content-type": "application/json" });
+          res.end(JSON.stringify({ error: "bad json" }));
+          return;
+        }
+      }
+      const out = await handler.handle(req.method, (req.url || "/").split("?")[0], parsed);
+      res.writeHead(out.status, { "content-type": "application/json" });
+      res.end(JSON.stringify(out.body));
+    });
+  });
+  server.listen(socketPath, () => {
+    // Group-readable + writable so the kernel (a different uid) can connect; the volume is the ACL.
+    try {
+      fs.chmodSync(socketPath, 0o666);
+    } catch {
+      /* best effort */
+    }
+    log(`alexandr updater v${pkg.version} — listening on ${socketPath}`);
+    log(dim(`  instance ${instanceDir} · project ${projectName} · feed ${feedUrl}`));
+  });
+  const stop = () => {
+    server.close();
+    try {
+      fs.unlinkSync(socketPath);
+    } catch {
+      /* gone */
+    }
+    process.exit(0);
+  };
+  process.on("SIGTERM", stop);
+  process.on("SIGINT", stop);
+  await new Promise(() => {});
+  warn("unreachable");
+}

package/templates/docker-compose.yml

@@ -16,15 +16,47 @@ services:
       # The HOST side of the port map below — inside the container the kernel only
       # knows its internal port, and must not advertise that as its reachable URL.
       ALEXANDR_ADVERTISED_PORT: ${ALEXANDR_KERNEL_PORT:-3030}
+      # Where the updater sidecar listens (a read-only mount below). The kernel reports
+      # `updater.available` from whether something answers here — never assumes.
+      ALEXANDR_UPDATER_SOCKET: /run/alexandr/updater.sock
     env_file:
       - path: ./.env
         required: false            # every var is optional; the CLI writes this file
     volumes:
       - data:/data                 # instance state: OS db, installed apps, blobs
+      # The updater sidecar's socket (below) — read-only: the kernel may ASK for an
+      # update over it and holds no Docker of its own.
+      - updater_run:/run/alexandr:ro
     ports:
       - "127.0.0.1:${ALEXANDR_KERNEL_PORT:-3030}:3030"   # loopback only
     restart: unless-stopped
 
+  # THE UPDATER SIDECAR (self-host-update-sidecar.md): the `alexandr` CLI in a container, the
+  # ONE process on this host allowed to hold the Docker socket, so the desktop app's update
+  # sheet can say "Update now" instead of handing over a command to copy. It runs the same
+  # `alexandr update` the operator would type — snapshot /data, pin, pull, restart, verify —
+  # when the kernel asks over the private socket in `updater_run`, and it resolves the target
+  # from the release feed itself (the kernel never names an image).
+  #
+  # Under the `updater` profile: the CLI passes `--profile updater` unless the operator set
+  # `alexandr up --no-updater` (ALEXANDR_UPDATER=off). Inside the container the instance
+  # directory is mounted at its HOST path, so compose's relative files resolve identically.
+  updater:
+    image: ghcr.io/alexandrco/alexandr-updater:${ALEXANDR_UPDATER_IMAGE_TAG:-latest}
+    profiles: ["updater"]
+    environment:
+      ALEXANDR_INSTANCE_DIR: ${ALEXANDR_INSTANCE_DIR:-/nonexistent}
+      ALEXANDR_COMPOSE_PROJECT: ${ALEXANDR_COMPOSE_PROJECT:-alexandr}
+      ALEXANDR_UPDATER_SOCKET: /run/alexandr/updater.sock
+    env_file:
+      - path: ./.env
+        required: false            # ALEXANDR_CP_URL / ALEXANDR_RELEASES_URL → the feed it reads
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock                 # THE socket. Only here.
+      - ${ALEXANDR_INSTANCE_DIR:-/nonexistent}:${ALEXANDR_INSTANCE_DIR:-/nonexistent}
+      - updater_run:/run/alexandr
+    restart: unless-stopped
+
   # Public front door. Only started under the "public" profile — i.e. when a
   # domain is configured (`alexandr up --domain …`). Pure-local runs skip it, so
   # no root is needed for :80/:443 and there's no TLS machinery to babysit.
@@ -49,3 +81,4 @@ volumes:
   data:
   caddy_data:
   caddy_config:
+  updater_run:                     # the updater's unix socket; the kernel mounts it read-only

package/templates/env.example

@@ -9,6 +9,16 @@
 
 # ---- image (the CLI pins this for `update --to <tag>` / `--rollback`) -------
 # ALEXANDR_IMAGE=ghcr.io/alexandrco/alexandr-kernel:latest
+# ---- the updater sidecar (self-host-update-sidecar.md) ----------------------
+# The `updater` service lets the desktop app's update sheet say "Update now": the
+# alexandr CLI in a container, the one process on this host holding the Docker
+# socket, running the same `alexandr update` you would type. On by default; opt out
+# with `alexandr up --no-updater` (writes the line below). The three vars after it
+# are WRITTEN BY THE CLI on every `up`/`update` — never fill them by hand.
+# ALEXANDR_UPDATER=off
+# ALEXANDR_INSTANCE_DIR=        # this directory, at its host path (mounted at the same path)
+# ALEXANDR_COMPOSE_PROJECT=     # the compose project the sidecar drives (the host's, verbatim)
+# ALEXANDR_UPDATER_IMAGE_TAG=   # the CLI version that installed it (= the sidecar's version)
 
 # ---- account link (REQUIRED — the runtime refuses to serve unlinked) --------
 # Every runtime must be linked to an alexandr account before it serves anyone