@kvbox/server 0.5.18 → 0.5.19

package/dist/kvbox-server.js

@@ -76,6 +76,8 @@ function paths(home = kvboxHome()) {
          * The next snapshot is a diff of the pages dirtied since, merged onto this. Absent after a boot.
          */
         memBase: join(dir, "mem.base"),
+        /** `kvbox vm fork` (#79): the source's VM state, captured here and gone once the box runs. Its memory is `memBase`. */
+        forkVmstate: join(dir, "fork.vmstate"),
         /** `kvbox hibernate`: the box's memory image and VM state while it is hibernated; gone again after `wake` or `stop`. */
         hibernateDir: join(dir, "hibernate"),
         hibernateVmstate: join(dir, "hibernate", "vmstate"),
@@ -214,8 +216,9 @@ function groupUsage(rows, window, pricing, live = /* @__PURE__ */ new Map()) {
     const status = live.get(id) ?? (removed ? "removed" : last.state);
     out.push({ id, name: last.name, owner: last.owner, status, ...totals });
   }
-  return out.sort((a, b) => a.owner.localeCompare(b.owner) || a.name.localeCompare(b.name) || (a.historyFrom ?? "").localeCompare(b.historyFrom ?? ""));
+  return out.sort(usageOrder);
 }
+var usageOrder = (a, b) => a.owner.localeCompare(b.owner) || a.name.localeCompare(b.name) || (a.historyFrom ?? "").localeCompare(b.historyFrom ?? "");
 
 // src/core/refs.ts
 import { userInfo } from "node:os";
@@ -257,6 +260,11 @@ function parseRef(text, caller) {
   }
   return { owner, name, display: owner === caller ? name : text };
 }
+function ownerFor(slug, caller) {
+  if (!LOCAL_OWNER_RE.test(slug)) throw new KvboxError(`invalid owner "${slug}": a bare slug, without '@' or '/'`);
+  const realm = realmOf(caller);
+  return realm === null ? slug : `${slug}@${realm}`;
+}
 function refKey(ref) {
   return `${ref.owner}/${ref.name}`;
 }
@@ -382,7 +390,7 @@ var MachineSchema = z3.object({
   // base image version the box's overlay stacks on
   createdAt: z3.string(),
   source: z3.string(),
-  // "base" or "snapshot:<name>"
+  // "base", "snapshot:<owner/name>" or "fork:<owner/name>" (#79)
   status: BoxStatusSchema,
   /**
    * Public TCP port on the host that reaches the box's SSH while it runs (#49). Only boxes made
@@ -418,6 +426,20 @@ var CreateMachineRequest = z3.object({
   /** Seconds without network traffic before the box is hibernated (#47); 0: never. Absent: the host's default. */
   autoHibernateSec: z3.number().int().min(0).optional()
 });
+var ForkMachineRequest = z3.object({
+  name: z3.string().optional(),
+  /**
+   * The new box's slug, bare (`acme`): the control plane sends the target of `--org` here; the host
+   * qualifies it with the caller's realm. Absent: the source's owner. A CLI leaves it out.
+   */
+  owner: z3.string().optional(),
+  /** A cold fork only: a warm one keeps the source's vCPU and memory. */
+  size: SizeSchema.optional(),
+  force: z3.boolean().optional(),
+  /** As in CreateMachineRequest: the control plane's CA line for the new box's owner. */
+  sshKeys: z3.array(z3.string()).optional(),
+  autoHibernateSec: z3.number().int().min(0).optional()
+});
 var SetSshKeysRequest = z3.object({
   sshKeys: z3.array(z3.string())
 });
@@ -533,7 +555,12 @@ var BoxUsageSchema = MachineUsageSchema.omit({ window: true, status: true }).ext
   id: z3.string(),
   status: UsageStatusSchema,
   /** Through a control plane: whether the owner slug is a user's or an org's (what `kvbox ls` shows). */
-  ownerKind: z3.enum(["user", "org"]).optional()
+  ownerKind: z3.enum(["user", "org"]).optional(),
+  /**
+   * Through a control plane: the username that made the box (#60), absent when the box is gone from
+   * the index (removed), was found by reconcile, or its maker was deleted. The ledger does not record it.
+   */
+  createdBy: z3.string().optional()
 });
 var UsageReportSchema = z3.object({
   window: z3.object({ from: z3.string(), to: z3.string() }),
@@ -929,8 +956,8 @@ async function requireKvm(device = KVM_DEVICE, groupFile = "/etc/group") {
 
 // src/core/machines.ts
 import { spawn } from "node:child_process";
-import { closeSync as closeSync2, existsSync as existsSync2, openSync as openSync2, statSync } from "node:fs";
-import { link, mkdir as mkdir3, readFile as readFile5, realpath, rm, truncate, writeFile as writeFile3 } from "node:fs/promises";
+import { closeSync as closeSync2, existsSync as existsSync3, openSync as openSync2, statSync } from "node:fs";
+import { link as link2, mkdir as mkdir4, readFile as readFile5, realpath, rm as rm2, truncate, writeFile as writeFile3 } from "node:fs/promises";
 import { basename } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 
@@ -1352,6 +1379,10 @@ function locked(fn) {
   return (...args) => withBoxLock(args[0], () => fn(...args));
 }
 
+// src/core/snapshots.ts
+import { existsSync } from "node:fs";
+import { link, mkdir as mkdir3, readdir as readdir2, rename as rename2, rm, stat as stat2 } from "node:fs/promises";
+
 // src/core/firecracker.ts
 import { Agent, request as request2 } from "undici";
 var FirecrackerClient = class {
@@ -1461,9 +1492,137 @@ var FirecrackerClient = class {
   }
 };
 
+// src/core/snapshots.ts
+var NAME_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+function toSnapshot(meta) {
+  return {
+    name: meta.name,
+    owner: meta.owner,
+    source: meta.source,
+    base: meta.base,
+    vcpu: meta.vcpu,
+    memMib: meta.memMib,
+    sizeBytes: meta.sizeBytes,
+    createdAt: meta.createdAt
+  };
+}
+async function listSnapshots(scope, p = paths()) {
+  const out = [];
+  for (const ref of await listSnapshotRefs(p)) {
+    if (!inScope(ref.owner, scope)) continue;
+    try {
+      out.push(toSnapshot(await readSnapshotMeta(ref, p)));
+    } catch (err) {
+      console.error(`warning: skipping snapshots/${refKey(ref)}: ${err.message}`);
+    }
+  }
+  return out;
+}
+async function usedBytes(dir) {
+  let total = 0;
+  for (const entry of await readdir2(dir)) {
+    total += (await stat2(`${dir}/${entry}`)).blocks * 512;
+  }
+  return total;
+}
+async function readBox(ref, p) {
+  try {
+    return await readMachineMeta(ref, p);
+  } catch (err) {
+    if (err.code === "ENOENT") throw new NotFoundError(`box ${shown(ref)}`);
+    throw err;
+  }
+}
+async function saveSnapshot(req, owner, p = paths()) {
+  if (!NAME_RE.test(req.name)) {
+    throw new KvboxError(`invalid snapshot name "${req.name}": 1-64 chars, lowercase letters, digits, '.', '_' and '-', starting with a letter or digit`);
+  }
+  const ref = parseRef(req.box, owner);
+  return withBoxLock(ref, () => snapshotBox(ref, req, owner, p));
+}
+async function snapshotBox(ref, req, owner, p) {
+  const box = await readBox(ref, p);
+  if (!vmAlive(box)) {
+    if (existsSync(p.machine(box.owner, box.name).hibernateVmstate)) {
+      throw new KvboxError(`box ${req.box} is hibernated; a snapshot freezes a running box (kvbox wake ${req.box} first)`);
+    }
+    throw new KvboxError(`box ${req.box} is not running; a snapshot freezes a running box (kvbox start ${req.box} first)`);
+  }
+  const s = p.snapshot(owner, req.name);
+  if (existsSync(s.dir)) throw new KvboxError(`snapshot ${req.name} already exists`);
+  const cfg = await loadConfig(p);
+  await mkdir3(s.dir, { recursive: true, mode: 448 });
+  try {
+    await captureBox(box, s, cfg, p);
+    const meta = {
+      name: req.name,
+      owner,
+      source: refKey(box),
+      base: box.base,
+      vcpu: box.vcpu,
+      memMib: box.memMib,
+      sizeBytes: await usedBytes(s.dir),
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await writeSnapshotMeta(meta, p);
+    return toSnapshot(meta);
+  } catch (err) {
+    await rm(s.dir, { recursive: true, force: true });
+    throw err;
+  }
+}
+async function captureBox(box, to, cfg, p) {
+  const m = p.machine(box.owner, box.name);
+  const fc = new FirecrackerClient(m.sock);
+  let lineageTouched = false;
+  try {
+    const since = box.memSnapshots ?? 0;
+    const mode = since === 0 || existsSync(m.memBase) ? "Diff" : "Full";
+    let failure2;
+    await fc.pause();
+    try {
+      await fc.snapshotCreate(to.vmstate, to.mem, mode);
+      lineageTouched = true;
+      await run(["cp", "--sparse=always", "--reflink=auto", m.overlay, to.overlay]);
+    } catch (err) {
+      failure2 = err;
+    } finally {
+      if (!box.paused) await fc.resume();
+    }
+    if (lineageTouched) {
+      await writeMachineMeta({ ...box, memSnapshots: since + 1 }, p);
+    }
+    if (failure2 !== void 0) throw failure2;
+    if (mode === "Full") {
+      await run(["fallocate", "--dig-holes", to.mem]);
+    } else if (since > 0) {
+      await mergeOntoPrevious(m.memBase, to.mem, cfg.snapshotEditor ?? p.snapshotEditor);
+    }
+    await rm(m.memBase, { force: true });
+    await link(to.mem, m.memBase);
+  } catch (err) {
+    if (lineageTouched) await rm(m.memBase, { force: true }).catch(() => void 0);
+    throw err;
+  } finally {
+    await fc.close();
+  }
+}
+async function mergeOntoPrevious(previous, diffFile, editor) {
+  if (!existsSync(editor)) throw new KvboxError(`snapshot-editor missing at ${editor}; rerun install-server.sh`);
+  const merged = `${diffFile}.merged`;
+  await run(["cp", "--sparse=always", "--reflink=auto", previous, merged]);
+  await run([editor, "edit-memory", "rebase", "--memory-path", merged, "--diff-path", diffFile]);
+  await rename2(merged, diffFile);
+}
+async function deleteSnapshot(ref, p = paths()) {
+  const dir = p.snapshot(ref.owner, ref.name).dir;
+  if (!existsSync(dir)) throw new NotFoundError(`snapshot ${shown(ref)}`);
+  await rm(dir, { recursive: true, force: true });
+}
+
 // src/core/network.ts
 import { randomInt } from "node:crypto";
-import { existsSync } from "node:fs";
+import { existsSync as existsSync2 } from "node:fs";
 import { fileURLToPath } from "node:url";
 var TAP_PREFIX = "kv-";
 var PRIVILEGED_SCRIPT = "/usr/local/lib/kvbox/net-setup.sh";
@@ -1473,15 +1632,15 @@ function tapName(box) {
 function netSetupScript() {
   const override = process.env["KVBOX_NET_SETUP"];
   if (override) return override;
-  if (existsSync(PRIVILEGED_SCRIPT)) return PRIVILEGED_SCRIPT;
+  if (existsSync2(PRIVILEGED_SCRIPT)) return PRIVILEGED_SCRIPT;
   for (const rel of ["../scripts/net-setup.sh", "../../scripts/net-setup.sh"]) {
     const candidate = fileURLToPath(new URL(rel, import.meta.url));
-    if (existsSync(candidate)) return candidate;
+    if (existsSync2(candidate)) return candidate;
   }
   throw new KvboxError("net-setup.sh not found next to kvbox-server");
 }
 function bridgeExists(bridge) {
-  return existsSync(`/sys/class/net/${bridge}`);
+  return existsSync2(`/sys/class/net/${bridge}`);
 }
 function netRun(cfg, args) {
   return run([netSetupScript(), ...args], {
@@ -1576,7 +1735,7 @@ function macFor(ip) {
 }
 
 // src/core/machines.ts
-var NAME_RE = /^[a-z0-9][a-z0-9-]{0,11}$/;
+var NAME_RE2 = /^[a-z0-9][a-z0-9-]{0,11}$/;
 var AUTO_PREFIX = "box";
 var GUEST_CID = 3;
 var OVERLAY_REL = "overlay.ext4";
@@ -1633,7 +1792,7 @@ function recordState(meta, state, by, p, at = (/* @__PURE__ */ new Date()).toISO
   }
 }
 function isHibernated(meta, p) {
-  return !vmAlive(meta) && existsSync2(p.machine(meta.owner, meta.name).hibernateVmstate);
+  return !vmAlive(meta) && existsSync3(p.machine(meta.owner, meta.name).hibernateVmstate);
 }
 function statusOf(meta, p = paths()) {
   if (vmAlive(meta)) return meta.paused ? "standby" : "running";
@@ -1692,7 +1851,7 @@ async function getMachine(ref, p = paths()) {
 }
 function pickName(requested, taken) {
   if (requested !== void 0) {
-    if (!NAME_RE.test(requested)) {
+    if (!NAME_RE2.test(requested)) {
       throw new KvboxError(`invalid box name "${requested}": 1-12 chars, lowercase letters, digits and '-', starting with a letter or digit`);
     }
     if (taken.has(requested)) throw new KvboxError(`box ${requested} already exists`);
@@ -1739,7 +1898,7 @@ async function currentBase(cfg, p) {
 }
 function baseFileFor(meta, p) {
   const file = p.baseImage(meta.base);
-  if (!existsSync2(file)) throw new KvboxError(`box ${meta.name} runs on base image ${meta.base}, which is gone from ${p.assets}`);
+  if (!existsSync3(file)) throw new KvboxError(`box ${meta.name} runs on base image ${meta.base}, which is gone from ${p.assets}`);
   return file;
 }
 var overlayCapable = /* @__PURE__ */ new Map();
@@ -1774,8 +1933,8 @@ async function tailOf(file, lines = 5) {
 }
 async function spawnFirecracker(ref, cfg, p) {
   const m = p.machine(ref.owner, ref.name);
-  await rm(m.sock, { force: true });
-  await rm(m.vsock, { force: true });
+  await rm2(m.sock, { force: true });
+  await rm2(m.vsock, { force: true });
   const logFd = openSync2(m.log, "a");
   let child;
   try {
@@ -1790,7 +1949,7 @@ async function spawnFirecracker(ref, cfg, p) {
   child.unref();
   const pid = child.pid;
   if (pid === void 0) throw new KvboxError("could not start firecracker");
-  if (!await waitFor(() => existsSync2(m.sock), 3e3)) {
+  if (!await waitFor(() => existsSync3(m.sock), 3e3)) {
     killQuietly(pid);
     throw new KvboxError(`firecracker did not open its API socket; last log lines:
 ${await tailOf(m.log)}`);
@@ -1861,7 +2020,7 @@ async function readHostPubkey(p) {
 }
 function assertAssets(cfg) {
   for (const [what, file] of [["kernel", cfg.kernel], ["base image", cfg.rootfs], ["firecracker", cfg.firecracker]]) {
-    if (!existsSync2(file)) throw new KvboxError(`${what} missing at ${file}; run install-server.sh`);
+    if (!existsSync3(file)) throw new KvboxError(`${what} missing at ${file}; run install-server.sh`);
   }
 }
 async function createMachine(req, owner, p = paths()) {
@@ -1872,33 +2031,43 @@ async function createMachine(req, owner, p = paths()) {
   const size = SIZES[sizeName];
   assertAssets(cfg);
   await assertRoomFor(size.vcpu, size.memMib, req.force ?? false, p);
-  const cloud = isCloudBox(owner);
-  const sshKeys = cloud && req.sshKeys !== void 0 && req.sshKeys.length > 0 ? req.sshKeys : void 0;
-  const keysB64 = authorizedKeysB64(await readHostPubkey(p), sshKeys ?? []);
+  const sshKeys = isCloudBox(owner) && req.sshKeys !== void 0 && req.sshKeys.length > 0 ? req.sshKeys : void 0;
+  authorizedKeysB64(await readHostPubkey(p), sshKeys ?? []);
   const existing = await readAllMeta(p);
-  const name = pickName(req.name, new Set(existing.filter((m2) => m2.owner === owner).map((m2) => m2.name)));
+  const name = pickName(req.name, new Set(existing.filter((m) => m.owner === owner).map((m) => m.name)));
   const id = newBoxId(idsInUse(existing));
-  const ip = nextFreeIp(cfg.subnet, [...existing.map((m2) => m2.ip), cfg.gateway]);
-  const mac = macFor(ip);
-  const m = p.machine(owner, name);
+  const ip = nextFreeIp(cfg.subnet, [...existing.map((m) => m.ip), cfg.gateway]);
   const base = await currentBase(cfg, p);
   await assertOverlayCapable(base.file, base.version);
+  return bootInto(
+    { id, name, owner, ip, mac: macFor(ip), vcpu: size.vcpu, memMib: size.memMib, base: base.version, sshKeys },
+    // The base image is shared read-only by every box; only the box's own writes land in its overlay.
+    (m) => createOverlay(m.overlay, size.diskGib),
+    { source: "base", autoHibernateSec: autoHibernateFor(req, cfg) },
+    cfg,
+    p
+  );
+}
+async function bootInto(box, prepare, origin, cfg, p) {
+  const { id, ip, owner, name } = box;
+  const keysB64 = authorizedKeysB64(await readHostPubkey(p), box.sshKeys ?? []);
+  const m = p.machine(owner, name);
   await ensureHostNetwork(cfg);
-  await mkdir3(m.dir, { recursive: true, mode: 448 });
+  await mkdir4(m.dir, { recursive: true, mode: 448 });
   let tapCreated = false;
   let pid;
   let sshPort;
   let drawn;
   try {
-    drawn = cloud ? await drawPorts(1, p) : void 0;
+    drawn = isCloudBox(owner) ? await drawPorts(1, p) : void 0;
     sshPort = drawn?.ports[0];
-    await createOverlay(m.overlay, size.diskGib);
+    await prepare(m);
     const tap = await createTap(id, cfg);
     tapCreated = true;
-    const spec = { id, name, owner, ip, mac, vcpu: size.vcpu, memMib: size.memMib, base: base.version, sshKeys, sshPort };
+    const spec = { ...box, sshPort };
     pid = await launch(spec, tap, cfg, keysB64, p);
     await openPorts(spec, cfg);
-    const meta = { ...spec, pid, bootId: currentBootId(), createdAt: (/* @__PURE__ */ new Date()).toISOString(), source: "base", autoHibernateSec: autoHibernateFor(req, cfg) };
+    const meta = { ...spec, pid, bootId: currentBootId(), createdAt: (/* @__PURE__ */ new Date()).toISOString(), ...origin };
     await writeMachineMeta(meta, p);
     recordState(meta, "running", "new", p, meta.createdAt);
     return toMachine(meta, p);
@@ -1906,7 +2075,7 @@ async function createMachine(req, owner, p = paths()) {
     if (pid !== void 0) killQuietly(pid);
     await closePorts({ id, ip, sshPort }, cfg);
     if (tapCreated) await deleteTap(id, cfg).catch(() => void 0);
-    await rm(m.dir, { recursive: true, force: true });
+    await rm2(m.dir, { recursive: true, force: true });
     throw err;
   } finally {
     drawn?.release();
@@ -1930,44 +2099,56 @@ async function restoreMachine(fromText, owner, req, cfg, p) {
     throw new KvboxError(`--size cannot be combined with --from: a restored box has the snapshot's size (${shown(from)}: ${snap.vcpu} vCPU, ${snap.memMib} MiB)`);
   }
   assertAssets(cfg);
-  if (!existsSync2(p.baseImage(snap.base))) {
+  if (!existsSync3(p.baseImage(snap.base))) {
     throw new KvboxError(`snapshot ${shown(from)} stacks on base image ${snap.base}, which is gone from ${p.assets}`);
   }
   await assertRoomFor(snap.vcpu, snap.memMib, req.force ?? false, p);
-  const cloud = isCloudBox(owner);
-  const sshKeys = cloud && req.sshKeys !== void 0 && req.sshKeys.length > 0 ? req.sshKeys : void 0;
+  const sshKeys = isCloudBox(owner) && req.sshKeys !== void 0 && req.sshKeys.length > 0 ? req.sshKeys : void 0;
   authorizedKeysB64(await readHostPubkey(p), sshKeys ?? []);
   const existing = await readAllMeta(p);
-  const name = pickName(req.name, new Set(existing.filter((m2) => m2.owner === owner).map((m2) => m2.name)));
+  const name = pickName(req.name, new Set(existing.filter((m) => m.owner === owner).map((m) => m.name)));
   const id = newBoxId(idsInUse(existing));
-  const ip = nextFreeIp(cfg.subnet, [...existing.map((m2) => m2.ip), cfg.gateway]);
-  const mac = macFor(ip);
-  const m = p.machine(owner, name);
+  const ip = nextFreeIp(cfg.subnet, [...existing.map((m) => m.ip), cfg.gateway]);
   const s = p.snapshot(from.owner, from.name);
+  return restoreInto(
+    { id, name, owner, ip, mac: macFor(ip), vcpu: snap.vcpu, memMib: snap.memMib, base: snap.base, sshKeys },
+    async (m) => {
+      await run(["cp", "--sparse=always", "--reflink=auto", s.overlay, m.overlay]);
+      await link2(s.mem, m.memBase);
+      return { vmstate: s.vmstate, mem: s.mem, label: shown(from) };
+    },
+    { source: `snapshot:${refKey(from)}`, autoHibernateSec: autoHibernateFor(req, cfg) },
+    cfg,
+    p
+  );
+}
+async function restoreInto(box, prepare, origin, cfg, p, keysOrFail) {
+  const { id, ip, owner, name } = box;
+  const m = p.machine(owner, name);
   await ensureHostNetwork(cfg);
-  await mkdir3(m.dir, { recursive: true, mode: 448 });
+  await mkdir4(m.dir, { recursive: true, mode: 448 });
   let tapCreated = false;
   let pid;
   let sshPort;
   let drawn;
   try {
-    drawn = cloud ? await drawPorts(1, p) : void 0;
+    drawn = isCloudBox(owner) ? await drawPorts(1, p) : void 0;
     sshPort = drawn?.ports[0];
-    await run(["cp", "--sparse=always", "--reflink=auto", s.overlay, m.overlay]);
-    await link(s.mem, m.memBase);
+    const image = await prepare(m);
     const tap = await createTap(id, cfg, { detached: true });
     tapCreated = true;
-    const spec = { id, name, owner, ip, mac, vcpu: snap.vcpu, memMib: snap.memMib, base: snap.base, sshKeys, sshPort };
-    pid = await loadSnapshot(spec, { vmstate: s.vmstate, mem: s.mem, label: shown(from) }, tap, cfg, p);
+    const spec = { ...box, sshPort };
+    pid = await loadSnapshot(spec, image, tap, cfg, p);
     await resumeVm(m.sock);
     await introduce(spec, m.vsock, cfg, {
       silent: `nothing answered on the restored box's control channel for 3 s; the restored box was discarded, try again`,
       noAnswer: "the restored box was discarded. kvbox-agent inside it took the request but gave no answer; try again, and if it keeps happening look at the box's journal (kvbox exec <box> -- sudo journalctl -u kvbox-agent) on a box started from the same snapshot."
     });
-    const stale = await pushAuthorizedKeys({ owner, name, sshKeys }, m.vsock, p);
+    const stale = await pushAuthorizedKeys(box, m.vsock, p);
+    if (stale && keysOrFail) throw new KvboxError(`${keysOrFail}: ${stale}`);
     await attachTap(id, cfg);
     await openPorts(spec, cfg);
-    const meta = { ...spec, pid, bootId: currentBootId(), createdAt: (/* @__PURE__ */ new Date()).toISOString(), source: `snapshot:${refKey(from)}`, memSnapshots: 1, sshKeysStale: stale ? true : void 0, autoHibernateSec: autoHibernateFor(req, cfg) };
+    const meta = { ...spec, pid, bootId: currentBootId(), createdAt: (/* @__PURE__ */ new Date()).toISOString(), ...origin, memSnapshots: 1, sshKeysStale: stale ? true : void 0 };
     await writeMachineMeta(meta, p);
     recordState(meta, "running", "new", p, meta.createdAt);
     return toMachine(meta, p);
@@ -1975,12 +2156,71 @@ async function restoreMachine(fromText, owner, req, cfg, p) {
     if (pid !== void 0) killQuietly(pid);
     await closePorts({ id, ip, sshPort }, cfg);
     if (tapCreated) await deleteTap(id, cfg).catch(() => void 0);
-    await rm(m.dir, { recursive: true, force: true });
+    await rm2(m.dir, { recursive: true, force: true });
     throw err;
   } finally {
     drawn?.release();
   }
 }
+var forkMachine = locked(async function forkMachine2(ref, owner, req, p = paths()) {
+  const src = await readMeta(ref, p);
+  const cfg = await loadConfig(p);
+  const status = statusOf(src, p);
+  if (status === "hibernated") throw new KvboxError(`${stateMessage(ref, status)}; a fork copies a running or a stopped box (kvbox wake ${shown(ref)} first)`);
+  const warm = status !== "stopped";
+  const srcDisk = p.machine(src.owner, src.name).overlay;
+  let shape = { vcpu: src.vcpu, memMib: src.memMib };
+  let growTo;
+  if (req.size !== void 0) {
+    if (warm) {
+      throw new KvboxError(`--size cannot be combined with forking a running box: the copy keeps its memory, so its size (${shown(ref)}: ${src.vcpu} vCPU, ${src.memMib} MiB); kvbox vm rescale the copy afterwards`);
+    }
+    if (!isSizeName(req.size)) throw new KvboxError(`unknown size "${req.size}"; use one of ${Object.keys(SIZES).join(", ")}`);
+    const preset = SIZES[req.size];
+    const diskGib = Math.round(statSync(srcDisk).size / 1024 ** 3);
+    if (preset.diskGib < diskGib) throw new KvboxError(`box ${shown(ref)} has a ${diskGib} GB disk and a disk cannot shrink; size ${req.size} has ${preset.diskGib} GB`);
+    shape = { vcpu: preset.vcpu, memMib: preset.memMib };
+    growTo = preset.diskGib > diskGib ? preset.diskGib : void 0;
+  }
+  assertAssets(cfg);
+  baseFileFor(src, p);
+  await assertRoomFor(shape.vcpu, shape.memMib, req.force ?? false, p);
+  const sshKeys = isCloudBox(owner) && req.sshKeys !== void 0 && req.sshKeys.length > 0 ? req.sshKeys : void 0;
+  authorizedKeysB64(await readHostPubkey(p), sshKeys ?? []);
+  const existing = await readAllMeta(p);
+  const name = pickName(req.name, new Set(existing.filter((m) => m.owner === owner).map((m) => m.name)));
+  const id = newBoxId(idsInUse(existing));
+  const ip = nextFreeIp(cfg.subnet, [...existing.map((m) => m.ip), cfg.gateway]);
+  const box = { id, name, owner, ip, mac: macFor(ip), ...shape, base: src.base, sshKeys };
+  const origin = { source: `fork:${refKey(src)}`, autoHibernateSec: (req.autoHibernateSec ?? src.autoHibernateSec) || void 0 };
+  if (!warm) {
+    return bootInto(
+      box,
+      async (m) => {
+        await run(["cp", "--sparse=always", "--reflink=auto", srcDisk, m.overlay]);
+        if (growTo !== void 0) await growDisk(m.overlay, growTo);
+      },
+      origin,
+      cfg,
+      p
+    );
+  }
+  const machine = await restoreInto(
+    box,
+    async (m) => {
+      await captureBox(src, { vmstate: m.forkVmstate, mem: m.memBase, overlay: m.overlay }, cfg, p);
+      return { vmstate: m.forkVmstate, mem: m.memBase, label: `box ${shown(ref)}` };
+    },
+    origin,
+    cfg,
+    p,
+    // The copy froze the source slug's CA line; left in place, that slug's members could open a box of
+    // another slug. Such a fork is discarded rather than kept stale; a cold fork boots with the new line.
+    owner === src.owner ? void 0 : `box ${shown(ref)} was not forked into ${owner}: the copy would still let ${src.owner} in (stop the box and fork it cold, which boots with ${owner}'s keys)`
+  );
+  await rm2(p.machine(owner, name).forkVmstate, { force: true });
+  return machine;
+});
 var AGENT_REPLY_MS = 2e4;
 async function introduce(spec, vsock, cfg, failure2) {
   const id = { name: spec.name, ip: spec.ip, prefixLen: prefixLenOf(cfg.subnet), gateway: cfg.gateway, mac: spec.mac, time: Math.floor(Date.now() / 1e3) };
@@ -2047,8 +2287,8 @@ async function cleanupProcess(meta, cfg, p) {
   await closePorts(meta, cfg);
   await deleteTap(meta.id, cfg);
   const m = p.machine(meta.owner, meta.name);
-  await rm(m.sock, { force: true });
-  await rm(m.vsock, { force: true });
+  await rm2(m.sock, { force: true });
+  await rm2(m.vsock, { force: true });
 }
 var stopMachine = locked(async function stopMachine2(ref, p = paths()) {
   const meta = await readMeta(ref, p);
@@ -2056,8 +2296,8 @@ var stopMachine = locked(async function stopMachine2(ref, p = paths()) {
   const m = p.machine(ref.owner, ref.name);
   if (!vmAlive(meta) && !isHibernated(meta, p)) throw new KvboxError(`box ${shown(ref)} is already stopped`);
   await shutdown(meta, cfg, p, 1e4);
-  await rm(m.hibernateDir, { recursive: true, force: true });
-  await rm(m.memBase, { force: true });
+  await rm2(m.hibernateDir, { recursive: true, force: true });
+  await rm2(m.memBase, { force: true });
   const stopped = { ...meta, pid: null, memSnapshots: void 0, paused: void 0 };
   await writeMachineMeta(stopped, p);
   recordState(stopped, "stopped", "stop", p);
@@ -2175,15 +2415,15 @@ var hibernateMachine = locked(async function hibernateMachine2(ref, p = paths(),
   if (status === "hibernated") throw new KvboxError(`${stateMessage(ref, status)} already`);
   if (status === "stopped") throw new KvboxError(`${stateMessage(ref, status)}; only a running box can be hibernated (there is no memory to keep)`);
   const m = p.machine(ref.owner, ref.name);
-  await rm(m.hibernateDir, { recursive: true, force: true });
-  await mkdir3(m.hibernateDir, { recursive: true, mode: 448 });
+  await rm2(m.hibernateDir, { recursive: true, force: true });
+  await mkdir4(m.hibernateDir, { recursive: true, mode: 448 });
   const fc = new FirecrackerClient(m.sock);
   try {
     try {
       await fc.pause();
       await fc.snapshotCreate(m.hibernateVmstate, m.hibernateMem, "Full");
     } catch (err) {
-      await rm(m.hibernateDir, { recursive: true, force: true });
+      await rm2(m.hibernateDir, { recursive: true, force: true });
       if (!meta.paused) await fc.resume().catch(() => void 0);
       throw err;
     }
@@ -2194,7 +2434,7 @@ var hibernateMachine = locked(async function hibernateMachine2(ref, p = paths(),
   await waitFor(() => !pidAlive(meta.pid), 5e3, 50);
   await cleanupProcess(meta, cfg, p);
   await run(["fallocate", "--dig-holes", m.hibernateMem]);
-  await rm(m.memBase, { force: true });
+  await rm2(m.memBase, { force: true });
   const hibernated = { ...meta, pid: null, memSnapshots: void 0, paused: void 0 };
   await writeMachineMeta(hibernated, p);
   recordState(hibernated, "hibernated", by, p);
@@ -2207,7 +2447,7 @@ var wakeMachine = locked(async function wakeMachine2(ref, p = paths()) {
   if (status === "running" || status === "standby") throw new KvboxError(`${stateMessage(ref, status)}, not hibernated`);
   if (status === "stopped") throw new KvboxError(`${stateMessage(ref, status)}, not hibernated; kvbox start ${shown(ref)} boots it`);
   assertAssets(cfg);
-  if (!existsSync2(p.baseImage(meta.base))) {
+  if (!existsSync3(p.baseImage(meta.base))) {
     throw new KvboxError(`box ${shown(ref)} stacks on base image ${meta.base}, which is gone from ${p.assets}`);
   }
   const m = p.machine(ref.owner, ref.name);
@@ -2232,9 +2472,9 @@ var wakeMachine = locked(async function wakeMachine2(ref, p = paths()) {
     await deleteTap(meta.id, cfg).catch(() => void 0);
     throw err;
   }
-  await rm(m.memBase, { force: true });
-  await link(m.hibernateMem, m.memBase);
-  await rm(m.hibernateDir, { recursive: true, force: true });
+  await rm2(m.memBase, { force: true });
+  await link2(m.hibernateMem, m.memBase);
+  await rm2(m.hibernateDir, { recursive: true, force: true });
   const running = { ...meta, pid, bootId: currentBootId(), memSnapshots: 1, paused: void 0, sshKeysStale: stale ? true : void 0 };
   await writeMachineMeta(running, p);
   recordState(running, "running", "wake", p);
@@ -2244,7 +2484,7 @@ async function applyAtNextBoot(meta, changes, by, cfg, p, whileStopped) {
   const wasRunning = vmAlive(meta);
   if (wasRunning) {
     await shutdown(meta, cfg, p, 1e4);
-    await rm(p.machine(meta.owner, meta.name).memBase, { force: true });
+    await rm2(p.machine(meta.owner, meta.name).memBase, { force: true });
   }
   const updated = { ...meta, ...changes, pid: null, memSnapshots: void 0, paused: void 0 };
   await writeMachineMeta(updated, p);
@@ -2366,7 +2606,7 @@ var destroyMachine = locked(async function destroyMachine2(ref, p = paths()) {
   const cfg = await loadConfig(p);
   await shutdown(meta, cfg, p, 2e3);
   recordState(meta, "stopped", "rm", p);
-  await rm(p.machine(ref.owner, ref.name).dir, { recursive: true, force: true });
+  await rm2(p.machine(ref.owner, ref.name).dir, { recursive: true, force: true });
 });
 var RECOVERY_CONCURRENCY = 2;
 async function settleDeadBoxes(p = paths()) {
@@ -2381,7 +2621,7 @@ async function settleDeadBoxes(p = paths()) {
     } catch (err) {
       console.error(`warning: usage ledger: ${err.message}`);
     }
-    await rm(p.machine(meta.owner, meta.name).memBase, { force: true });
+    await rm2(p.machine(meta.owner, meta.name).memBase, { force: true });
     if (meta.paused) {
       await writeMachineMeta({ ...meta, pid: null, bootId: void 0, memSnapshots: void 0, paused: void 0 }, p);
       leftStopped.push(refKey(meta));
@@ -2430,7 +2670,7 @@ async function bootRecovered(settled, p = paths()) {
 }
 
 // src/core/relay.ts
-import { chmod as chmod3, mkdir as mkdir4, rm as rm2, writeFile as writeFile4 } from "node:fs/promises";
+import { chmod as chmod3, mkdir as mkdir5, rm as rm3, writeFile as writeFile4 } from "node:fs/promises";
 
 // ../shared/src/relay.ts
 import { z as z5 } from "zod";
@@ -2494,7 +2734,7 @@ async function useRelay(joinString, p = paths()) {
       `${cfg.controlPlane.name} reaches this host at ${cfg.relay.publicIp}, not ${join2.publicIp}; run kvbox server leave first, then join again`
     );
   }
-  await mkdir4(p.relay, { recursive: true, mode: 448 });
+  await mkdir5(p.relay, { recursive: true, mode: 448 });
   await writeFile4(p.relayConf, relayConf(join2), { mode: 384 });
   await chmod3(p.relayConf, 384);
   await netSetup(cfg, ["relay", "up", p.relayConf, String(cfg.controlPlane?.port ?? DEFAULT_HTTPS_PORT)]);
@@ -2510,7 +2750,7 @@ async function dropRelay(p = paths()) {
     throw new KvboxError(`${cfg.controlPlane.name} reaches this host through the relay (${relay.publicIp}); run kvbox server leave first`);
   }
   await netSetup(cfg, ["relay", "down"]);
-  await rm2(p.relayConf, { force: true });
+  await rm3(p.relayConf, { force: true });
   const { relay: _gone, ...rest } = cfg;
   await saveConfig(rest, p);
   return relay;
@@ -2685,7 +2925,7 @@ function versionOf(srcFileUrl, injected) {
 }
 
 // src/version.ts
-var VERSION = versionOf(import.meta.url, true ? "0.5.18" : void 0);
+var VERSION = versionOf(import.meta.url, true ? "0.5.19" : void 0);
 
 // src/caller.ts
 import { createHash as createHash2, timingSafeEqual } from "node:crypto";
@@ -3053,6 +3293,12 @@ function machineRoutes() {
     const body = CreateMachineRequest.parse(await c.req.json().catch(() => ({})));
     return c.json(await createMachine(body, c.get("owner")), 201);
   });
+  r.post("/:name/fork", async (c) => {
+    const body = ForkMachineRequest.parse(await c.req.json().catch(() => ({})));
+    const caller = c.get("owner");
+    const into = body.owner === void 0 ? caller : ownerFor(body.owner, caller);
+    return c.json(await forkMachine(parseRef(c.req.param("name"), caller), into, body), 201);
+  });
   r.post("/:name/stop", async (c) => c.json(await stopMachine(parseRef(c.req.param("name"), c.get("owner")))));
   r.post("/:name/start", async (c) => c.json(await startMachine(parseRef(c.req.param("name"), c.get("owner")))));
   r.post("/:name/pause", async (c) => c.json(await pauseMachine(parseRef(c.req.param("name"), c.get("owner")))));
@@ -3104,131 +3350,6 @@ function machineRoutes() {
 
 // src/routes/snapshots.ts
 import { Hono as Hono4 } from "hono";
-
-// src/core/snapshots.ts
-import { existsSync as existsSync3 } from "node:fs";
-import { link as link2, mkdir as mkdir5, readdir as readdir2, rename as rename2, rm as rm3, stat as stat2 } from "node:fs/promises";
-var NAME_RE2 = /^[a-z0-9][a-z0-9._-]{0,63}$/;
-function toSnapshot(meta) {
-  return {
-    name: meta.name,
-    owner: meta.owner,
-    source: meta.source,
-    base: meta.base,
-    vcpu: meta.vcpu,
-    memMib: meta.memMib,
-    sizeBytes: meta.sizeBytes,
-    createdAt: meta.createdAt
-  };
-}
-async function listSnapshots(scope, p = paths()) {
-  const out = [];
-  for (const ref of await listSnapshotRefs(p)) {
-    if (!inScope(ref.owner, scope)) continue;
-    try {
-      out.push(toSnapshot(await readSnapshotMeta(ref, p)));
-    } catch (err) {
-      console.error(`warning: skipping snapshots/${refKey(ref)}: ${err.message}`);
-    }
-  }
-  return out;
-}
-async function usedBytes(dir) {
-  let total = 0;
-  for (const entry of await readdir2(dir)) {
-    total += (await stat2(`${dir}/${entry}`)).blocks * 512;
-  }
-  return total;
-}
-async function readBox(ref, p) {
-  try {
-    return await readMachineMeta(ref, p);
-  } catch (err) {
-    if (err.code === "ENOENT") throw new NotFoundError(`box ${shown(ref)}`);
-    throw err;
-  }
-}
-async function saveSnapshot(req, owner, p = paths()) {
-  if (!NAME_RE2.test(req.name)) {
-    throw new KvboxError(`invalid snapshot name "${req.name}": 1-64 chars, lowercase letters, digits, '.', '_' and '-', starting with a letter or digit`);
-  }
-  const ref = parseRef(req.box, owner);
-  return withBoxLock(ref, () => snapshotBox(ref, req, owner, p));
-}
-async function snapshotBox(ref, req, owner, p) {
-  const box = await readBox(ref, p);
-  if (!vmAlive(box)) {
-    if (existsSync3(p.machine(box.owner, box.name).hibernateVmstate)) {
-      throw new KvboxError(`box ${req.box} is hibernated; a snapshot freezes a running box (kvbox wake ${req.box} first)`);
-    }
-    throw new KvboxError(`box ${req.box} is not running; a snapshot freezes a running box (kvbox start ${req.box} first)`);
-  }
-  const s = p.snapshot(owner, req.name);
-  if (existsSync3(s.dir)) throw new KvboxError(`snapshot ${req.name} already exists`);
-  const cfg = await loadConfig(p);
-  const m = p.machine(box.owner, box.name);
-  await mkdir5(s.dir, { recursive: true, mode: 448 });
-  const fc = new FirecrackerClient(m.sock);
-  let lineageTouched = false;
-  try {
-    const since = box.memSnapshots ?? 0;
-    const mode = since === 0 || existsSync3(m.memBase) ? "Diff" : "Full";
-    let failure2;
-    await fc.pause();
-    try {
-      await fc.snapshotCreate(s.vmstate, s.mem, mode);
-      lineageTouched = true;
-      await run(["cp", "--sparse=always", "--reflink=auto", m.overlay, s.overlay]);
-    } catch (err) {
-      failure2 = err;
-    } finally {
-      if (!box.paused) await fc.resume();
-    }
-    if (lineageTouched) {
-      await writeMachineMeta({ ...box, memSnapshots: since + 1 }, p);
-    }
-    if (failure2 !== void 0) throw failure2;
-    if (mode === "Full") {
-      await run(["fallocate", "--dig-holes", s.mem]);
-    } else if (since > 0) {
-      await mergeOntoPrevious(m.memBase, s.mem, cfg.snapshotEditor ?? p.snapshotEditor);
-    }
-    await rm3(m.memBase, { force: true });
-    await link2(s.mem, m.memBase);
-    const meta = {
-      name: req.name,
-      owner,
-      source: refKey(box),
-      base: box.base,
-      vcpu: box.vcpu,
-      memMib: box.memMib,
-      sizeBytes: await usedBytes(s.dir),
-      createdAt: (/* @__PURE__ */ new Date()).toISOString()
-    };
-    await writeSnapshotMeta(meta, p);
-    return toSnapshot(meta);
-  } catch (err) {
-    if (lineageTouched) await rm3(m.memBase, { force: true }).catch(() => void 0);
-    await rm3(s.dir, { recursive: true, force: true });
-    throw err;
-  } finally {
-    await fc.close();
-  }
-}
-async function mergeOntoPrevious(previous, diffFile, editor) {
-  if (!existsSync3(editor)) throw new KvboxError(`snapshot-editor missing at ${editor}; rerun install-server.sh`);
-  const merged = `${diffFile}.merged`;
-  await run(["cp", "--sparse=always", "--reflink=auto", previous, merged]);
-  await run([editor, "edit-memory", "rebase", "--memory-path", merged, "--diff-path", diffFile]);
-  await rename2(merged, diffFile);
-}
-async function deleteSnapshot(ref, p = paths()) {
-  const dir = p.snapshot(ref.owner, ref.name).dir;
-  if (!existsSync3(dir)) throw new NotFoundError(`snapshot ${shown(ref)}`);
-  await rm3(dir, { recursive: true, force: true });
-}
-
-// src/routes/snapshots.ts
 function snapshotRoutes() {
   const r = new Hono4();
   r.get("/", async (c) => c.json(await listSnapshots(c.get("listScope"))));