@ghalex/kvbox-server 0.0.14 → 0.0.16

package/dist/kvbox-server.js

@@ -13,12 +13,6 @@ var KvboxError = class extends Error {
   }
   exitCode;
 };
-var NotImplementedError = class extends KvboxError {
-  constructor(what) {
-    super(`${what}: not implemented yet`, 2);
-    this.name = "NotImplementedError";
-  }
-};
 var NotFoundError = class extends KvboxError {
   constructor(what) {
     super(`${what}: not found`, 1);
@@ -53,31 +47,40 @@ function paths(home = kvboxHome()) {
     baseImage: (version) => join(home, "assets", `rootfs-${version}.ext4`),
     machines: join(home, "machines"),
     snapshots: join(home, "snapshots"),
-    machine: (name) => ({
-      dir: join(home, "machines", name),
-      meta: join(home, "machines", name, "meta.json"),
-      /** The box's writable layer, stacked on the read-only base image inside the guest. */
-      overlay: join(home, "machines", name, "overlay.ext4"),
-      /** Boxes made before overlays: a full copy of the base image. Kept bootable, never created anymore. */
-      disk: join(home, "machines", name, "disk.ext4"),
-      /**
-       * The box's memory as of its last snapshot (a hard link to that snapshot's `mem`, never modified).
-       * The next snapshot is a diff of the pages dirtied since, merged onto this. Absent after a boot.
-       */
-      memBase: join(home, "machines", name, "mem.base"),
-      sock: join(home, "machines", name, "fc.sock"),
-      /** Firecracker's vsock endpoint: the host connects here to reach kvbox-agent inside the box (core/agent.ts). */
-      vsock: join(home, "machines", name, "vsock.sock"),
-      log: join(home, "machines", name, "fc.log")
-    }),
-    snapshot: (name) => ({
-      dir: join(home, "snapshots", name),
-      meta: join(home, "snapshots", name, "meta.json"),
-      vmstate: join(home, "snapshots", name, "vmstate"),
-      mem: join(home, "snapshots", name, "mem"),
-      /** Copy of the box's overlay at the moment of the snapshot; the base image is referenced by version in meta.json. */
-      overlay: join(home, "snapshots", name, "overlay.ext4")
-    })
+    /** Boxes and snapshots are filed by owner: machines/<owner>/<name>. The owner is part of a box's identity. */
+    ownerMachines: (owner) => join(home, "machines", owner),
+    ownerSnapshots: (owner) => join(home, "snapshots", owner),
+    machine: (owner, name) => {
+      const dir = join(home, "machines", owner, name);
+      return {
+        dir,
+        meta: join(dir, "meta.json"),
+        /** The box's writable layer, stacked on the read-only base image inside the guest. */
+        overlay: join(dir, "overlay.ext4"),
+        /** Boxes made before overlays: a full copy of the base image. Kept bootable, never created anymore. */
+        disk: join(dir, "disk.ext4"),
+        /**
+         * The box's memory as of its last snapshot (a hard link to that snapshot's `mem`, never modified).
+         * The next snapshot is a diff of the pages dirtied since, merged onto this. Absent after a boot.
+         */
+        memBase: join(dir, "mem.base"),
+        sock: join(dir, "fc.sock"),
+        /** Firecracker's vsock endpoint: the host connects here to reach kvbox-agent inside the box (core/agent.ts). */
+        vsock: join(dir, "vsock.sock"),
+        log: join(dir, "fc.log")
+      };
+    },
+    snapshot: (owner, name) => {
+      const dir = join(home, "snapshots", owner, name);
+      return {
+        dir,
+        meta: join(dir, "meta.json"),
+        vmstate: join(dir, "vmstate"),
+        mem: join(dir, "mem"),
+        /** Copy of the box's overlay at the moment of the snapshot; the base image is referenced by version in meta.json. */
+        overlay: join(dir, "overlay.ext4")
+      };
+    }
   };
 }
 
@@ -97,6 +100,36 @@ function isSizeName(value) {
   return value in SIZES;
 }
 
+// src/core/refs.ts
+import { userInfo } from "os";
+function shown(ref) {
+  return ref.display ?? ref.name;
+}
+var LOCAL_OWNER_RE = /^[A-Za-z0-9_][A-Za-z0-9._-]{0,63}$/;
+var OWNER_RE = /^[A-Za-z0-9_][A-Za-z0-9._-]{0,63}(@[A-Za-z0-9.-]{1,128})?$/;
+function localOwner() {
+  try {
+    const name = userInfo().username;
+    if (LOCAL_OWNER_RE.test(name)) return name;
+  } catch {
+  }
+  const env = process.env["USER"];
+  return env !== void 0 && LOCAL_OWNER_RE.test(env) ? env : "kvbox";
+}
+function parseRef(text, caller) {
+  const slash = text.indexOf("/");
+  if (slash === -1) return { owner: caller, name: text, display: text };
+  const owner = text.slice(0, slash);
+  const name = text.slice(slash + 1);
+  if (!OWNER_RE.test(owner) || name.length === 0 || name.includes("/")) {
+    throw new KvboxError(`invalid box reference "${text}": use <name> or <owner>/<name>`);
+  }
+  return { owner, name, display: owner === caller ? name : text };
+}
+function refKey(ref) {
+  return `${ref.owner}/${ref.name}`;
+}
+
 // src/core/config.ts
 var ConfigSchema = z.object({
   kernel: z.string(),
@@ -107,14 +140,17 @@ var ConfigSchema = z.object({
   bridge: z.string().default("kvbox0"),
   subnet: z.string().default("172.30.0.0/24"),
   gateway: z.string().default("172.30.0.1"),
-  defaultSize: z.enum(SIZE_NAMES).default(DEFAULT_SIZE)
+  defaultSize: z.enum(SIZE_NAMES).default(DEFAULT_SIZE),
+  /** Who boxes made over the local socket belong to: the Unix user running the server unless set here. No `@`, no `/`. */
+  owner: z.string().regex(LOCAL_OWNER_RE, "owner: letters, digits, '.', '_', '-'; no '@' or '/'").default(localOwner)
 });
 function defaultConfig(p = paths()) {
   return ConfigSchema.parse({
     kernel: p.kernel,
     rootfs: p.rootfs,
     firecracker: p.firecracker,
-    snapshotEditor: p.snapshotEditor
+    snapshotEditor: p.snapshotEditor,
+    owner: localOwner()
   });
 }
 async function loadConfig(p = paths()) {
@@ -225,7 +261,7 @@ function macFor(ip) {
 }
 
 // src/listen.ts
-import { rm as rm3, writeFile as writeFile4 } from "fs/promises";
+import { rm as rm3, writeFile as writeFile5 } from "fs/promises";
 import { createAdaptorServer } from "@hono/node-server";
 
 // src/core/state.ts
@@ -233,6 +269,8 @@ import { mkdir, readFile as readFile2, readdir, writeFile as writeFile2 } from "
 import { z as z2 } from "zod";
 var MachineMetaSchema = z2.object({
   name: z2.string(),
+  /** Part of the box's identity: machines/<owner>/<name>. See refs.ts. */
+  owner: z2.string(),
   ip: z2.string(),
   mac: z2.string(),
   pid: z2.number().int().nullable(),
@@ -252,6 +290,8 @@ var MachineMetaSchema = z2.object({
 });
 var SnapshotMetaSchema = z2.object({
   name: z2.string(),
+  owner: z2.string(),
+  /** The box it was taken from, as owner/name. */
   source: z2.string(),
   base: z2.string(),
   vcpu: z2.number().int(),
@@ -277,25 +317,36 @@ async function listDirs(dir) {
     throw err;
   }
 }
-async function readMachineMeta(name, p = paths()) {
-  return readJson(p.machine(name).meta, MachineMetaSchema);
+async function readMachineMeta(ref, p = paths()) {
+  return readJson(p.machine(ref.owner, ref.name).meta, MachineMetaSchema);
 }
 async function writeMachineMeta(meta, p = paths()) {
-  await mkdir(p.machine(meta.name).dir, { recursive: true });
-  await writeFile2(p.machine(meta.name).meta, JSON.stringify(meta, null, 2) + "\n");
+  const m = p.machine(meta.owner, meta.name);
+  await mkdir(m.dir, { recursive: true });
+  await writeFile2(m.meta, JSON.stringify(meta, null, 2) + "\n");
 }
-async function listMachineNames(p = paths()) {
-  return listDirs(p.machines);
+async function listMachineRefs(p = paths()) {
+  return listRefs(p.machines);
 }
-async function readSnapshotMeta(name, p = paths()) {
-  return readJson(p.snapshot(name).meta, SnapshotMetaSchema);
+async function readSnapshotMeta(ref, p = paths()) {
+  return readJson(p.snapshot(ref.owner, ref.name).meta, SnapshotMetaSchema);
 }
 async function writeSnapshotMeta(meta, p = paths()) {
-  await mkdir(p.snapshot(meta.name).dir, { recursive: true });
-  await writeFile2(p.snapshot(meta.name).meta, JSON.stringify(meta, null, 2) + "\n");
+  const s = p.snapshot(meta.owner, meta.name);
+  await mkdir(s.dir, { recursive: true });
+  await writeFile2(s.meta, JSON.stringify(meta, null, 2) + "\n");
+}
+async function listSnapshotRefs(p = paths()) {
+  return listRefs(p.snapshots);
 }
-async function listSnapshotNames(p = paths()) {
-  return listDirs(p.snapshots);
+async function listRefs(root) {
+  const out = [];
+  for (const owner of await listDirs(root)) {
+    for (const name of await listDirs(`${root}/${owner}`)) {
+      out.push({ owner, name });
+    }
+  }
+  return out;
 }
 function pidAlive(pid) {
   if (pid === null || pid <= 0) return false;
@@ -307,6 +358,62 @@ function pidAlive(pid) {
   }
 }
 
+// src/core/migrate.ts
+import { existsSync as existsSync2 } from "fs";
+import { mkdir as mkdir2, readdir as readdir2, readFile as readFile3, rename, writeFile as writeFile3 } from "fs/promises";
+import { join as join2 } from "path";
+async function migrateOwnerLayout(owner, p = paths()) {
+  const done = { boxes: [], snapshots: [], conflicts: [] };
+  for (const name of await oldDepthEntries(p.machines)) {
+    const from = join2(p.machines, name);
+    const to = p.machine(owner, name).dir;
+    if (existsSync2(to)) {
+      done.conflicts.push(`machines/${name}`);
+      continue;
+    }
+    await patchJson(join2(from, "meta.json"), (meta) => ({
+      ...meta,
+      owner,
+      // a restored box names its snapshot: that moved under the same owner
+      source: typeof meta["source"] === "string" && meta["source"].startsWith("snapshot:") && !meta["source"].includes("/") ? `snapshot:${owner}/${meta["source"].slice("snapshot:".length)}` : meta["source"]
+    }));
+    await mkdir2(p.ownerMachines(owner), { recursive: true, mode: 448 });
+    await rename(from, to);
+    done.boxes.push(name);
+  }
+  for (const name of await oldDepthEntries(p.snapshots)) {
+    const from = join2(p.snapshots, name);
+    const to = p.snapshot(owner, name).dir;
+    if (existsSync2(to)) {
+      done.conflicts.push(`snapshots/${name}`);
+      continue;
+    }
+    await patchJson(join2(from, "meta.json"), (meta) => ({
+      ...meta,
+      owner,
+      source: typeof meta["source"] === "string" && !meta["source"].includes("/") ? `${owner}/${meta["source"]}` : meta["source"]
+    }));
+    await mkdir2(p.ownerSnapshots(owner), { recursive: true, mode: 448 });
+    await rename(from, to);
+    done.snapshots.push(name);
+  }
+  return done;
+}
+async function oldDepthEntries(root) {
+  let entries;
+  try {
+    entries = await readdir2(root, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === "ENOENT") return [];
+    throw err;
+  }
+  return entries.filter((e) => e.isDirectory() && existsSync2(join2(root, e.name, "meta.json"))).map((e) => e.name).sort();
+}
+async function patchJson(file, patch) {
+  const raw = JSON.parse(await readFile3(file, "utf8"));
+  await writeFile3(file, JSON.stringify(patch(raw), null, 2) + "\n");
+}
+
 // src/app.ts
 import { Hono as Hono4 } from "hono";
 
@@ -323,12 +430,21 @@ function versionOf(srcFileUrl, injected) {
 }
 
 // src/version.ts
-var VERSION = versionOf(import.meta.url, true ? "0.0.14" : void 0);
+var VERSION = versionOf(import.meta.url, true ? "0.0.16" : void 0);
+
+// src/caller.ts
+function resolveCaller() {
+  return async (c, next) => {
+    const cfg = await loadConfig();
+    c.set("owner", cfg.owner);
+    await next();
+  };
+}
 
 // src/core/machines.ts
 import { spawn } from "child_process";
-import { closeSync, existsSync as existsSync2, openSync, statSync } from "fs";
-import { link, mkdir as mkdir2, readFile as readFile3, realpath, rm, truncate, writeFile as writeFile3 } from "fs/promises";
+import { closeSync, existsSync as existsSync3, openSync, statSync } from "fs";
+import { link, mkdir as mkdir3, readFile as readFile4, realpath, rm, truncate, writeFile as writeFile4 } from "fs/promises";
 import { basename } from "path";
 import { setTimeout as sleep } from "timers/promises";
 
@@ -382,6 +498,66 @@ function setIdentity(udsPath, id, timeoutMs) {
   return agentCall(udsPath, { op: "identity", ...id }, timeoutMs);
 }
 
+// src/core/capacity.ts
+import { cpus, totalmem } from "os";
+var MEM_HEADROOM_MIB = 2048;
+var VCPU_OVERSUBSCRIPTION = 2;
+function hostResources() {
+  return { memMib: Math.floor(totalmem() / 1024 ** 2), cores: cpus().length };
+}
+async function runningReservations(p = paths()) {
+  const out = [];
+  for (const ref of await listMachineRefs(p)) {
+    try {
+      const meta = await readMachineMeta(ref, p);
+      if (pidAlive(meta.pid)) out.push({ name: meta.name, vcpu: meta.vcpu, memMib: meta.memMib });
+    } catch {
+    }
+  }
+  return out;
+}
+async function capacity(p = paths()) {
+  const host = hostResources();
+  const running = await runningReservations(p);
+  return {
+    hostMemMib: host.memMib,
+    hostCores: host.cores,
+    reservedMemMib: running.reduce((n, r) => n + r.memMib, 0),
+    reservedVcpu: running.reduce((n, r) => n + r.vcpu, 0),
+    running: running.length
+  };
+}
+function gb(mib) {
+  const g = mib / 1024;
+  return `${Number.isInteger(g) ? g : g.toFixed(1)} GB`;
+}
+function describeRunning(running) {
+  if (running.length === 0) return "no box is running";
+  const list = running.map((r) => `${r.name} ${r.vcpu} vCPU/${gb(r.memMib)}`).join(", ");
+  const vcpu = running.reduce((n, r) => n + r.vcpu, 0);
+  const mem = running.reduce((n, r) => n + r.memMib, 0);
+  return `${running.length} running ${running.length === 1 ? "box reserves" : "boxes reserve"} ${vcpu} vCPU and ${gb(mem)} (${list})`;
+}
+function roomFor(host, running, want) {
+  const reservedMem = running.reduce((n, r) => n + r.memMib, 0);
+  const reservedVcpu = running.reduce((n, r) => n + r.vcpu, 0);
+  const memLimit = host.memMib - MEM_HEADROOM_MIB;
+  const vcpuLimit = host.cores * VCPU_OVERSUBSCRIPTION;
+  const hint = "stop or remove a box (kvbox stop, kvbox rm), pick a smaller --size, or pass --force to start it anyway";
+  if (reservedMem + want.memMib > memLimit) {
+    return `not enough memory for a ${gb(want.memMib)} box: ${describeRunning(running)}; this host has ${gb(host.memMib)} and keeps ${gb(MEM_HEADROOM_MIB)} for itself, so boxes may reserve ${gb(memLimit)} in total. ` + hint;
+  }
+  if (reservedVcpu + want.vcpu > vcpuLimit) {
+    return `too many vCPUs for a ${want.vcpu} vCPU box: ${describeRunning(running)}; this host has ${host.cores} cores and allows ${vcpuLimit} vCPUs in total (${VCPU_OVERSUBSCRIPTION}x). ` + hint;
+  }
+  return void 0;
+}
+async function assertRoomFor(vcpu, memMib, force, p = paths()) {
+  if (force) return;
+  const reason = roomFor(hostResources(), await runningReservations(p), { vcpu, memMib });
+  if (reason !== void 0) throw new KvboxError(reason);
+}
+
 // src/core/firecracker.ts
 import { Agent, request } from "undici";
 var FirecrackerClient = class {
@@ -516,13 +692,14 @@ function diskStats(disk) {
   }
 }
 function ownDisk(meta, p) {
-  const m = p.machine(meta.name);
+  const m = p.machine(meta.owner, meta.name);
   return meta.base === void 0 ? m.disk : m.overlay;
 }
 function toMachine(meta, p = paths()) {
   const alive = pidAlive(meta.pid);
   return {
     name: meta.name,
+    owner: meta.owner,
     ip: meta.ip,
     mac: meta.mac,
     pid: alive ? meta.pid : null,
@@ -537,17 +714,17 @@ function toMachine(meta, p = paths()) {
 }
 async function readAllMeta(p) {
   const metas = [];
-  for (const name of await listMachineNames(p)) {
+  for (const ref of await listMachineRefs(p)) {
     try {
-      metas.push(await readMachineMeta(name, p));
+      metas.push(await readMachineMeta(ref, p));
     } catch (err) {
-      console.error(`warning: skipping machines/${name}: ${err.message}`);
+      console.error(`warning: skipping machines/${refKey(ref)}: ${err.message}`);
     }
   }
   return metas;
 }
-async function listMachines(p = paths()) {
-  return (await readAllMeta(p)).map((m) => toMachine(m, p));
+async function listMachines(owner, p = paths()) {
+  return (await readAllMeta(p)).filter((m) => owner === null || m.owner === owner).map((m) => toMachine(m, p));
 }
 function pickName(requested, taken) {
   if (requested !== void 0) {
@@ -582,7 +759,7 @@ async function currentBase(cfg, p) {
 function baseFileFor(meta, p) {
   if (meta.base === void 0) return void 0;
   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();
@@ -596,7 +773,7 @@ async function assertOverlayCapable(baseFile, version) {
   if (!ok) throw new KvboxError(`base image ${version} is too old for this server (no /sbin/overlay-init); rerun install-server.sh to get a newer one`);
 }
 async function createOverlay(file, gib) {
-  await writeFile3(file, "", { mode: 384 });
+  await writeFile4(file, "", { mode: 384 });
   await truncate(file, gib * 1024 ** 3);
   await run(["mkfs.ext4", "-q", "-F", "-m", "0", "-L", "kvbox-box", "-E", "lazy_itable_init=1,lazy_journal_init=1", file]);
 }
@@ -610,19 +787,19 @@ async function waitFor(pred, timeoutMs, stepMs = 50) {
 }
 async function tailOf(file, lines = 5) {
   try {
-    return (await readFile3(file, "utf8")).trim().split("\n").slice(-lines).join("\n");
+    return (await readFile4(file, "utf8")).trim().split("\n").slice(-lines).join("\n");
   } catch {
     return "";
   }
 }
-async function spawnFirecracker(name, cfg, p) {
-  const m = p.machine(name);
+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 });
   const logFd = openSync(m.log, "a");
   let child;
   try {
-    child = spawn(cfg.firecracker, ["--api-sock", m.sock, "--id", name, "--level", "Error"], {
+    child = spawn(cfg.firecracker, ["--api-sock", m.sock, "--id", ref.name, "--level", "Error"], {
       cwd: m.dir,
       detached: true,
       stdio: ["ignore", logFd, logFd]
@@ -633,7 +810,7 @@ async function spawnFirecracker(name, 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)}`);
@@ -647,9 +824,9 @@ function killQuietly(pid) {
   }
 }
 async function launch(spec, tap, cfg, pubkeyB64, p) {
-  const m = p.machine(spec.name);
+  const m = p.machine(spec.owner, spec.name);
   const baseFile = baseFileFor(spec, p);
-  const pid = await spawnFirecracker(spec.name, cfg, p);
+  const pid = await spawnFirecracker(spec, cfg, p);
   try {
     const fc = new FirecrackerClient(m.sock);
     try {
@@ -673,10 +850,10 @@ async function launch(spec, tap, cfg, pubkeyB64, p) {
     throw err;
   }
 }
-async function loadSnapshot(spec, snapshotName, tap, cfg, p) {
-  const m = p.machine(spec.name);
-  const s = p.snapshot(snapshotName);
-  const pid = await spawnFirecracker(spec.name, cfg, p);
+async function loadSnapshot(spec, snapshot, tap, cfg, p) {
+  const m = p.machine(spec.owner, spec.name);
+  const s = p.snapshot(snapshot.owner, snapshot.name);
+  const pid = await spawnFirecracker(spec, cfg, p);
   try {
     const fc = new FirecrackerClient(m.sock);
     try {
@@ -690,7 +867,7 @@ async function loadSnapshot(spec, snapshotName, tap, cfg, p) {
           resume: false
         });
       } catch (err) {
-        if (/Unknown Vsock Device/.test(err.message)) throw new KvboxError(tooOldToRestore(snapshotName));
+        if (/Unknown Vsock Device/.test(err.message)) throw new KvboxError(tooOldToRestore(shown(snapshot)));
         throw err;
       }
       if (await namesOverlayAbsolutely(s.vmstate)) await fc.patchDrivePath("overlay", m.overlay);
@@ -710,43 +887,44 @@ async function currentBaseVersion(p = paths()) {
   return (await currentBase(await loadConfig(p), p)).version;
 }
 async function namesOverlayAbsolutely(vmstate) {
-  return (await readFile3(vmstate)).includes(`/${OVERLAY_REL}`);
+  return (await readFile4(vmstate)).includes(`/${OVERLAY_REL}`);
 }
 async function readPubkeyB64(p) {
   try {
-    return Buffer.from((await readFile3(`${p.sshKey}.pub`, "utf8")).trim()).toString("base64");
+    return Buffer.from((await readFile4(`${p.sshKey}.pub`, "utf8")).trim()).toString("base64");
   } catch {
     throw new KvboxError(`SSH key missing at ${p.sshKey}.pub; run install-server.sh`);
   }
 }
 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, p = paths()) {
+async function createMachine(req, owner, p = paths()) {
   const cfg = await loadConfig(p);
-  if (req.from !== void 0) return restoreMachine(req.from, req, cfg, p);
+  if (req.from !== void 0) return restoreMachine(req.from, owner, req, cfg, p);
   const sizeName = req.size ?? cfg.defaultSize;
   if (!isSizeName(sizeName)) throw new KvboxError(`unknown size "${sizeName}"; use one of ${Object.keys(SIZES).join(", ")}`);
   const size = SIZES[sizeName];
   assertAssets(cfg);
+  await assertRoomFor(size.vcpu, size.memMib, req.force ?? false, p);
   const pubkeyB64 = await readPubkeyB64(p);
   const existing = await readAllMeta(p);
-  const name = pickName(req.name, new Set(existing.map((m2) => m2.name)));
+  const name = pickName(req.name, new Set(existing.filter((m2) => m2.owner === owner).map((m2) => m2.name)));
   const ip = nextFreeIp(cfg.subnet, [...existing.map((m2) => m2.ip), cfg.gateway]);
   const mac = macFor(ip);
-  const m = p.machine(name);
+  const m = p.machine(owner, name);
   const base = await currentBase(cfg, p);
   await assertOverlayCapable(base.file, base.version);
   await ensureHostNetwork(cfg);
-  await mkdir2(m.dir, { recursive: true, mode: 448 });
+  await mkdir3(m.dir, { recursive: true, mode: 448 });
   let tapCreated = false;
   try {
     await createOverlay(m.overlay, size.diskGib);
     const tap = await createTap(name, cfg);
     tapCreated = true;
-    const spec = { name, ip, mac, vcpu: size.vcpu, memMib: size.memMib, base: base.version };
+    const spec = { name, owner, ip, mac, vcpu: size.vcpu, memMib: size.memMib, base: base.version };
     const pid = await launch(spec, tap, cfg, pubkeyB64, p);
     const meta = { ...spec, pid, createdAt: (/* @__PURE__ */ new Date()).toISOString(), source: "base" };
     await writeMachineMeta(meta, p);
@@ -757,34 +935,36 @@ async function createMachine(req, p = paths()) {
     throw err;
   }
 }
-async function readSnap(name, p) {
+async function readSnap(ref, p) {
   try {
-    return await readSnapshotMeta(name, p);
+    return await readSnapshotMeta(ref, p);
   } catch (err) {
-    if (err.code === "ENOENT") throw new NotFoundError(`snapshot ${name}`);
+    if (err.code === "ENOENT") throw new NotFoundError(`snapshot ${shown(ref)}`);
     throw err;
   }
 }
 function prefixLenOf(subnet) {
   return Number(subnet.split("/")[1]);
 }
-async function restoreMachine(from, req, cfg, p) {
+async function restoreMachine(fromText, owner, req, cfg, p) {
+  const from = parseRef(fromText, owner);
   const snap = await readSnap(from, p);
   if (req.size !== void 0) {
-    throw new KvboxError(`--size cannot be combined with --from: a restored box has the snapshot's size (${from}: ${snap.vcpu} vCPU, ${snap.memMib} MiB)`);
+    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))) {
-    throw new KvboxError(`snapshot ${from} stacks on base image ${snap.base}, which is gone from ${p.assets}`);
+  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 existing = await readAllMeta(p);
-  const name = pickName(req.name, new Set(existing.map((m2) => m2.name)));
+  const name = pickName(req.name, new Set(existing.filter((m2) => m2.owner === owner).map((m2) => m2.name)));
   const ip = nextFreeIp(cfg.subnet, [...existing.map((m2) => m2.ip), cfg.gateway]);
   const mac = macFor(ip);
-  const m = p.machine(name);
-  const s = p.snapshot(from);
+  const m = p.machine(owner, name);
+  const s = p.snapshot(from.owner, from.name);
   await ensureHostNetwork(cfg);
-  await mkdir2(m.dir, { recursive: true, mode: 448 });
+  await mkdir3(m.dir, { recursive: true, mode: 448 });
   let tapCreated = false;
   let pid;
   try {
@@ -792,7 +972,7 @@ async function restoreMachine(from, req, cfg, p) {
     await link(s.mem, m.memBase);
     const tap = await createTap(name, cfg, { detached: true });
     tapCreated = true;
-    const spec = { name, ip, mac, vcpu: snap.vcpu, memMib: snap.memMib, base: snap.base };
+    const spec = { name, owner, ip, mac, vcpu: snap.vcpu, memMib: snap.memMib, base: snap.base };
     pid = await loadSnapshot(spec, from, tap, cfg, p);
     const fc = new FirecrackerClient(m.sock);
     try {
@@ -800,9 +980,9 @@ async function restoreMachine(from, req, cfg, p) {
     } finally {
       await fc.close();
     }
-    await introduce(spec, m.vsock, cfg, from);
+    await introduce(spec, m.vsock, cfg, shown(from));
     await attachTap(name, cfg);
-    const meta = { ...spec, pid, createdAt: (/* @__PURE__ */ new Date()).toISOString(), source: `snapshot:${from}`, memSnapshots: 1 };
+    const meta = { ...spec, pid, createdAt: (/* @__PURE__ */ new Date()).toISOString(), source: `snapshot:${refKey(from)}`, memSnapshots: 1 };
     await writeMachineMeta(meta, p);
     return toMachine(meta, p);
   } catch (err) {
@@ -837,7 +1017,7 @@ async function introduce(spec, vsock, cfg, from) {
 async function shutdown(meta, cfg, p, graceMs) {
   const pid = meta.pid;
   if (pidAlive(pid)) {
-    const fc = new FirecrackerClient(p.machine(meta.name).sock);
+    const fc = new FirecrackerClient(p.machine(meta.owner, meta.name).sock);
     try {
       await fc.sendCtrlAltDel();
     } catch {
@@ -854,34 +1034,35 @@ async function shutdown(meta, cfg, p, graceMs) {
     }
   }
   await deleteTap(meta.name, cfg);
-  await rm(p.machine(meta.name).sock, { force: true });
-  await rm(p.machine(meta.name).vsock, { force: true });
+  const m = p.machine(meta.owner, meta.name);
+  await rm(m.sock, { force: true });
+  await rm(m.vsock, { force: true });
 }
-async function stopMachine(name, p = paths()) {
-  const meta = await readMeta(name, p);
+async function stopMachine(ref, p = paths()) {
+  const meta = await readMeta(ref, p);
   const cfg = await loadConfig(p);
-  if (!pidAlive(meta.pid)) throw new KvboxError(`box ${name} is already stopped`);
+  if (!pidAlive(meta.pid)) throw new KvboxError(`box ${shown(ref)} is already stopped`);
   await shutdown(meta, cfg, p, 1e4);
-  await rm(p.machine(name).memBase, { force: true });
+  await rm(p.machine(ref.owner, ref.name).memBase, { force: true });
   const stopped = { ...meta, pid: null, memSnapshots: void 0 };
   await writeMachineMeta(stopped, p);
   return toMachine(stopped, p);
 }
-async function startMachine(name, p = paths()) {
-  const meta = await readMeta(name, p);
+async function startMachine(ref, p = paths()) {
+  const meta = await readMeta(ref, p);
   const cfg = await loadConfig(p);
-  if (pidAlive(meta.pid)) throw new KvboxError(`box ${name} is already running`);
+  if (pidAlive(meta.pid)) throw new KvboxError(`box ${shown(ref)} is already running`);
   assertAssets(cfg);
   const pubkeyB64 = await readPubkeyB64(p);
   await ensureHostNetwork(cfg);
-  const tap = await createTap(name, cfg);
+  const tap = await createTap(ref.name, cfg);
   try {
     const pid = await launch(meta, tap, cfg, pubkeyB64, p);
     const started = { ...meta, pid };
     await writeMachineMeta(started, p);
     return toMachine(started, p);
   } catch (err) {
-    await deleteTap(name, cfg).catch(() => void 0);
+    await deleteTap(ref.name, cfg).catch(() => void 0);
     throw err;
   }
 }
@@ -889,18 +1070,18 @@ async function applyAtNextBoot(meta, changes, cfg, p, whileStopped) {
   const wasRunning = pidAlive(meta.pid);
   if (wasRunning) {
     await shutdown(meta, cfg, p, 1e4);
-    await rm(p.machine(meta.name).memBase, { force: true });
+    await rm(p.machine(meta.owner, meta.name).memBase, { force: true });
   }
   const updated = { ...meta, ...changes, pid: null, memSnapshots: void 0 };
   await writeMachineMeta(updated, p);
   if (whileStopped) await whileStopped();
-  return wasRunning ? startMachine(meta.name, p) : toMachine(updated, p);
+  return wasRunning ? startMachine(meta, p) : toMachine(updated, p);
 }
-async function updateMachine(name, p = paths()) {
-  const meta = await readMeta(name, p);
+async function updateMachine(ref, p = paths()) {
+  const meta = await readMeta(ref, p);
   const cfg = await loadConfig(p);
   if (meta.base === void 0) {
-    throw new KvboxError(`box ${name} was made before overlays and runs on its own disk copy; it cannot be moved to another base image`);
+    throw new KvboxError(`box ${shown(ref)} was made before overlays and runs on its own disk copy; it cannot be moved to another base image`);
   }
   assertAssets(cfg);
   const base = await currentBase(cfg, p);
@@ -908,8 +1089,8 @@ async function updateMachine(name, p = paths()) {
   await assertOverlayCapable(base.file, base.version);
   return applyAtNextBoot(meta, { base: base.version }, cfg, p);
 }
-async function rescaleMachine(name, req, p = paths()) {
-  const meta = await readMeta(name, p);
+async function rescaleMachine(ref, req, p = paths()) {
+  const meta = await readMeta(ref, p);
   const cfg = await loadConfig(p);
   const disk = ownDisk(meta, p);
   const currentDiskGib = Math.round(statSync(disk).size / 1024 ** 3);
@@ -920,7 +1101,7 @@ async function rescaleMachine(name, req, p = paths()) {
     diskGib: req.diskGib ?? preset?.diskGib ?? currentDiskGib
   };
   if (target.diskGib < currentDiskGib) {
-    throw new KvboxError(`box ${name} has a ${currentDiskGib} GB disk and a disk cannot shrink; ${target.diskGib} GB is smaller`);
+    throw new KvboxError(`box ${shown(ref)} has a ${currentDiskGib} GB disk and a disk cannot shrink; ${target.diskGib} GB is smaller`);
   }
   const changes = {};
   if (target.vcpu !== meta.vcpu) changes.vcpu = target.vcpu;
@@ -934,30 +1115,23 @@ async function growDisk(file, gib) {
   await run(["e2fsck", "-f", "-p", file], { okExitCodes: [1] });
   await run(["resize2fs", file]);
 }
-async function readMeta(name, p) {
+async function readMeta(ref, p) {
   try {
-    return await readMachineMeta(name, p);
+    return await readMachineMeta(ref, p);
   } catch (err) {
-    if (err.code === "ENOENT") throw new NotFoundError(`box ${name}`);
+    if (err.code === "ENOENT") throw new NotFoundError(`box ${shown(ref)}`);
     throw err;
   }
 }
-async function destroyMachine(name, p = paths()) {
-  const meta = await readMeta(name, p);
+async function destroyMachine(ref, p = paths()) {
+  const meta = await readMeta(ref, p);
   const cfg = await loadConfig(p);
   await shutdown(meta, cfg, p, 2e3);
-  await rm(p.machine(name).dir, { recursive: true, force: true });
+  await rm(p.machine(ref.owner, ref.name).dir, { recursive: true, force: true });
 }
 
 // src/routes/capacity.ts
 import { Hono } from "hono";
-
-// src/core/capacity.ts
-async function capacity() {
-  throw new NotImplementedError("capacity.capacity");
-}
-
-// src/routes/capacity.ts
 function capacityRoutes() {
   const r = new Hono();
   r.get("/", async (c) => c.json(await capacity()));
@@ -972,6 +1146,8 @@ import { z as z3 } from "zod";
 var SizeSchema = z3.enum(SIZE_NAMES);
 var MachineSchema = z3.object({
   name: z3.string(),
+  /** Who the box belongs to; names are unique per owner. A bare name is local to the host, `user@control-plane` later. */
+  owner: z3.string(),
   ip: z3.string(),
   mac: z3.string(),
   pid: z3.number().int().nullable(),
@@ -990,6 +1166,8 @@ var MachineSchema = z3.object({
 });
 var CreateMachineRequest = z3.object({
   name: z3.string().optional(),
+  /** Ignored over the local socket (the caller is the host owner); the control plane sets it over HTTPS. */
+  owner: z3.string().optional(),
   size: SizeSchema.optional(),
   from: z3.string().optional(),
   force: z3.boolean().optional()
@@ -1002,8 +1180,9 @@ var RescaleMachineRequest = z3.object({
 });
 var SnapshotSchema = z3.object({
   name: z3.string(),
+  owner: z3.string(),
   source: z3.string(),
-  // the box it was taken from
+  // the box it was taken from, as owner/name
   base: z3.string(),
   // base image version the overlay stacks on; a restore needs the same one
   vcpu: z3.number().int(),
@@ -1028,7 +1207,9 @@ var HealthSchema = z3.object({
   version: z3.string(),
   pid: z3.number().int(),
   /** Base image version new boxes get (null when the host has no usable base image yet); absent from older servers. */
-  base: z3.string().nullable().optional()
+  base: z3.string().nullable().optional(),
+  /** Owner that boxes made over the local socket get (the Unix user running the server); absent from older servers. */
+  owner: z3.string().optional()
 });
 var ApiErrorSchema = z3.object({
   error: z3.string()
@@ -1037,20 +1218,20 @@ var ApiErrorSchema = z3.object({
 // src/routes/machines.ts
 function machineRoutes() {
   const r = new Hono2();
-  r.get("/", async (c) => c.json(await listMachines()));
+  r.get("/", async (c) => c.json(await listMachines(c.get("owner"))));
   r.post("/", async (c) => {
     const body = CreateMachineRequest.parse(await c.req.json().catch(() => ({})));
-    return c.json(await createMachine(body), 201);
+    return c.json(await createMachine(body, c.get("owner")), 201);
   });
-  r.post("/:name/stop", async (c) => c.json(await stopMachine(c.req.param("name"))));
-  r.post("/:name/start", async (c) => c.json(await startMachine(c.req.param("name"))));
-  r.post("/:name/update", async (c) => c.json(await updateMachine(c.req.param("name"))));
+  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/update", async (c) => c.json(await updateMachine(parseRef(c.req.param("name"), c.get("owner")))));
   r.post("/:name/rescale", async (c) => {
     const body = RescaleMachineRequest.parse(await c.req.json().catch(() => ({})));
-    return c.json(await rescaleMachine(c.req.param("name"), body));
+    return c.json(await rescaleMachine(parseRef(c.req.param("name"), c.get("owner")), body));
   });
   r.delete("/:name", async (c) => {
-    await destroyMachine(c.req.param("name"));
+    await destroyMachine(parseRef(c.req.param("name"), c.get("owner")));
     return c.body(null, 204);
   });
   return r;
@@ -1060,12 +1241,13 @@ function machineRoutes() {
 import { Hono as Hono3 } from "hono";
 
 // src/core/snapshots.ts
-import { existsSync as existsSync3 } from "fs";
-import { link as link2, mkdir as mkdir3, readdir as readdir2, rename, rm as rm2, stat } from "fs/promises";
+import { existsSync as existsSync4 } from "fs";
+import { link as link2, mkdir as mkdir4, readdir as readdir3, rename as rename2, rm as rm2, stat } from "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,
@@ -1074,54 +1256,55 @@ function toSnapshot(meta) {
     createdAt: meta.createdAt
   };
 }
-async function listSnapshots(p = paths()) {
+async function listSnapshots(owner, p = paths()) {
   const out = [];
-  for (const name of await listSnapshotNames(p)) {
+  for (const ref of await listSnapshotRefs(p)) {
+    if (owner !== null && ref.owner !== owner) continue;
     try {
-      out.push(toSnapshot(await readSnapshotMeta(name, p)));
+      out.push(toSnapshot(await readSnapshotMeta(ref, p)));
     } catch (err) {
-      console.error(`warning: skipping snapshots/${name}: ${err.message}`);
+      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)) {
+  for (const entry of await readdir3(dir)) {
     total += (await stat(`${dir}/${entry}`)).blocks * 512;
   }
   return total;
 }
-async function readBox(name, p) {
+async function readBox(ref, p) {
   try {
-    return await readMachineMeta(name, p);
+    return await readMachineMeta(ref, p);
   } catch (err) {
-    if (err.code === "ENOENT") throw new NotFoundError(`box ${name}`);
+    if (err.code === "ENOENT") throw new NotFoundError(`box ${shown(ref)}`);
     throw err;
   }
 }
-async function saveSnapshot(req, p = paths()) {
+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 box = await readBox(req.box, p);
+  const box = await readBox(parseRef(req.box, owner), p);
   if (box.base === void 0) {
     throw new KvboxError(`box ${req.box} was made before overlays and runs on its own disk copy; snapshots need a box made by this version of kvbox (kvbox new)`);
   }
   if (!pidAlive(box.pid)) {
     throw new KvboxError(`box ${req.box} is not running; a snapshot freezes a running box (kvbox start ${req.box} first)`);
   }
-  const s = p.snapshot(req.name);
-  if (existsSync3(s.dir)) throw new KvboxError(`snapshot ${req.name} already exists`);
+  const s = p.snapshot(owner, req.name);
+  if (existsSync4(s.dir)) throw new KvboxError(`snapshot ${req.name} already exists`);
   const cfg = await loadConfig(p);
-  const m = p.machine(box.name);
-  await mkdir3(s.dir, { recursive: true, mode: 448 });
+  const m = p.machine(box.owner, box.name);
+  await mkdir4(s.dir, { recursive: true, mode: 448 });
   const fc = new FirecrackerClient(m.sock);
   let lineageTouched = false;
   try {
     const tracked = (await fc.machineConfigInfo()).track_dirty_pages;
     const since = box.memSnapshots ?? 0;
-    const mode = tracked && (since === 0 || existsSync3(m.memBase)) ? "Diff" : "Full";
+    const mode = tracked && (since === 0 || existsSync4(m.memBase)) ? "Diff" : "Full";
     let failure;
     await fc.pause();
     try {
@@ -1148,7 +1331,8 @@ async function saveSnapshot(req, p = paths()) {
     }
     const meta = {
       name: req.name,
-      source: box.name,
+      owner,
+      source: refKey(box),
       base: box.base,
       vcpu: box.vcpu,
       memMib: box.memMib,
@@ -1166,27 +1350,28 @@ async function saveSnapshot(req, p = paths()) {
   }
 }
 async function mergeOntoPrevious(previous, diffFile, editor) {
-  if (!existsSync3(editor)) throw new KvboxError(`snapshot-editor missing at ${editor}; rerun install-server.sh`);
+  if (!existsSync4(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 rename(merged, diffFile);
+  await rename2(merged, diffFile);
 }
-async function deleteSnapshot(name, p = paths()) {
-  if (!existsSync3(p.snapshot(name).dir)) throw new NotFoundError(`snapshot ${name}`);
-  await rm2(p.snapshot(name).dir, { recursive: true, force: true });
+async function deleteSnapshot(ref, p = paths()) {
+  const dir = p.snapshot(ref.owner, ref.name).dir;
+  if (!existsSync4(dir)) throw new NotFoundError(`snapshot ${shown(ref)}`);
+  await rm2(dir, { recursive: true, force: true });
 }
 
 // src/routes/snapshots.ts
 function snapshotRoutes() {
   const r = new Hono3();
-  r.get("/", async (c) => c.json(await listSnapshots()));
+  r.get("/", async (c) => c.json(await listSnapshots(c.get("owner"))));
   r.post("/", async (c) => {
     const body = CreateSnapshotRequest.parse(await c.req.json());
-    return c.json(await saveSnapshot(body), 201);
+    return c.json(await saveSnapshot(body, c.get("owner")), 201);
   });
   r.delete("/:name", async (c) => {
-    await deleteSnapshot(c.req.param("name"));
+    await deleteSnapshot(parseRef(c.req.param("name"), c.get("owner")));
     return c.body(null, 204);
   });
   return r;
@@ -1195,9 +1380,16 @@ function snapshotRoutes() {
 // src/app.ts
 function createApp() {
   const app = new Hono4();
+  app.use(resolveCaller());
   app.get(
     "/health",
-    async (c) => c.json({ ok: true, version: VERSION, pid: process.pid, base: await currentBaseVersion().catch(() => null) })
+    async (c) => c.json({
+      ok: true,
+      version: VERSION,
+      pid: process.pid,
+      base: await currentBaseVersion().catch(() => null),
+      owner: (await loadConfig()).owner
+    })
   );
   app.route("/machines", machineRoutes());
   app.route("/snapshots", snapshotRoutes());
@@ -1217,7 +1409,12 @@ function createApp() {
 // src/listen.ts
 async function listen(opts = {}) {
   const p = await ensureLayout(paths());
-  await loadConfig(p);
+  const cfg = await loadConfig(p);
+  const moved = await migrateOwnerLayout(cfg.owner, p);
+  if (moved.boxes.length + moved.snapshots.length > 0) {
+    console.error(`boxes and snapshots now belong to an owner: moved ${moved.boxes.length} box(es) and ${moved.snapshots.length} snapshot(s) under ${cfg.owner}/`);
+  }
+  for (const c of moved.conflicts) console.error(`warning: ${c} left in place: ${cfg.owner} already has one with that name`);
   const socketPath = opts.socketPath ?? p.serverSock;
   if (Buffer.byteLength(socketPath) > 100) {
     throw new KvboxError(`socket path too long for a Unix socket (${socketPath}); set KVBOX_HOME to a shorter path`);
@@ -1228,7 +1425,7 @@ async function listen(opts = {}) {
     server.once("error", reject);
     server.listen(socketPath, () => resolve());
   });
-  await writeFile4(p.serverPid, `${process.pid}
+  await writeFile5(p.serverPid, `${process.pid}
 `);
   const shutdown2 = async () => {
     server.close();