@ghalex/kvbox-server 0.0.15 → 0.0.17

package/dist/kvbox-server.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { spawnSync } from "child_process";
+import { spawnSync } from "node:child_process";
 import { Command } from "commander";
 
 // ../shared/src/errors.ts
@@ -21,8 +21,8 @@ var NotFoundError = class extends KvboxError {
 };
 
 // ../shared/src/paths.ts
-import { homedir } from "os";
-import { join } from "path";
+import { homedir } from "node:os";
+import { join } from "node:path";
 function kvboxHome() {
   return process.env["KVBOX_HOME"] ?? join(homedir(), ".kvbox");
 }
@@ -30,6 +30,8 @@ function paths(home = kvboxHome()) {
   return {
     home,
     config: join(home, "config.json"),
+    /** The host's ledgers (SQLite via node:sqlite): usage events today. Boxes and snapshots stay files; see server core/db.ts. */
+    db: join(home, "kvbox.db"),
     serverSock: join(home, "server.sock"),
     serverPid: join(home, "server.pid"),
     serverLog: join(home, "server.log"),
@@ -47,36 +49,45 @@ 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")
+      };
+    }
   };
 }
 
 // src/core/config.ts
-import { readFile, writeFile } from "fs/promises";
+import { readFile, writeFile } from "node:fs/promises";
 import { z } from "zod";
 
 // ../shared/src/sizes.ts
@@ -91,7 +102,43 @@ function isSizeName(value) {
   return value in SIZES;
 }
 
+// src/core/refs.ts
+import { userInfo } from "node: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 PricingSchema = z.object({
+  currency: z.string().min(1),
+  vcpuHour: z.number().nonnegative(),
+  ramGibHour: z.number().nonnegative(),
+  diskGibHour: z.number().nonnegative()
+});
 var ConfigSchema = z.object({
   kernel: z.string(),
   rootfs: z.string(),
@@ -101,14 +148,18 @@ 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),
+  pricing: PricingSchema.optional()
 });
 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()) {
@@ -126,12 +177,12 @@ async function loadConfig(p = paths()) {
 }
 
 // src/core/network.ts
-import { existsSync } from "fs";
-import { fileURLToPath } from "url";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 
 // src/core/exec.ts
-import { execFile } from "child_process";
-import { promisify } from "util";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
 var execFileAsync = promisify(execFile);
 async function run(argv, opts = {}) {
   const [cmd, ...args] = opts.sudo ? ["sudo", "-n", ...argv] : argv;
@@ -219,14 +270,16 @@ function macFor(ip) {
 }
 
 // src/listen.ts
-import { rm as rm3, writeFile as writeFile4 } from "fs/promises";
+import { rm as rm3, writeFile as writeFile5 } from "node:fs/promises";
 import { createAdaptorServer } from "@hono/node-server";
 
 // src/core/state.ts
-import { mkdir, readFile as readFile2, readdir, writeFile as writeFile2 } from "fs/promises";
+import { mkdir, readFile as readFile2, readdir, writeFile as writeFile2 } from "node:fs/promises";
 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(),
@@ -246,6 +299,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(),
@@ -271,25 +326,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;
@@ -301,33 +367,151 @@ function pidAlive(pid) {
   }
 }
 
-// src/app.ts
-import { Hono as Hono4 } from "hono";
-
-// ../shared/src/version.ts
-import { createRequire } from "module";
-function versionOf(srcFileUrl, injected) {
-  if (typeof injected === "string") return injected;
+// src/core/migrate.ts
+import { existsSync as existsSync2 } from "node:fs";
+import { mkdir as mkdir2, readdir as readdir2, readFile as readFile3, rename, writeFile as writeFile3 } from "node:fs/promises";
+import { join as join2 } from "node: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 {
-    const require2 = createRequire(srcFileUrl);
-    return require2("../package.json").version;
-  } catch {
-    return "0.0.0-dev";
+    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/version.ts
-var VERSION = versionOf(import.meta.url, true ? "0.0.15" : void 0);
+// src/core/db.ts
+import { chmodSync, closeSync, mkdirSync, openSync } from "node:fs";
+import { dirname } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+var MIGRATIONS = [
+  `create table usage_events (
+     id integer primary key,
+     box_id text not null,
+     owner text not null,
+     name text not null,
+     at text not null,
+     state text not null,
+     vcpu integer not null,
+     mem_mib integer not null,
+     disk_gib integer not null,
+     by text not null
+   );
+   create index usage_events_box_at on usage_events (box_id, at);`
+];
+var handles = /* @__PURE__ */ new Map();
+function openDb(p = paths()) {
+  const have = handles.get(p.db);
+  if (have !== void 0) return have;
+  mkdirSync(dirname(p.db), { recursive: true, mode: 448 });
+  closeSync(openSync(p.db, "a", 384));
+  chmodSync(p.db, 384);
+  const db = new DatabaseSync(p.db);
+  db.exec("pragma journal_mode = wal");
+  db.exec("pragma busy_timeout = 5000");
+  migrate(db);
+  handles.set(p.db, db);
+  return db;
+}
+function migrate(db) {
+  db.exec("create table if not exists schema_version (version integer not null)");
+  const row = db.prepare("select version from schema_version").get();
+  let version = row?.version ?? 0;
+  if (row === void 0) db.prepare("insert into schema_version (version) values (0)").run();
+  while (version < MIGRATIONS.length) {
+    db.exec("begin");
+    try {
+      db.exec(MIGRATIONS[version]);
+      version += 1;
+      db.prepare("update schema_version set version = ?").run(version);
+      db.exec("commit");
+    } catch (err) {
+      db.exec("rollback");
+      throw err;
+    }
+  }
+}
+function fromRaw(r) {
+  return { boxId: r.box_id, owner: r.owner, name: r.name, at: r.at, state: r.state, vcpu: r.vcpu, memMib: r.mem_mib, diskGib: r.disk_gib, by: r.by };
+}
+function lastEvent(boxId, db) {
+  const raw = db.prepare("select * from usage_events where box_id = ? order by at desc, id desc limit 1").get(boxId);
+  return raw === void 0 ? void 0 : fromRaw(raw);
+}
+function insertRaw(e, db) {
+  db.prepare(
+    "insert into usage_events (box_id, owner, name, at, state, vcpu, mem_mib, disk_gib, by) values (?, ?, ?, ?, ?, ?, ?, ?, ?)"
+  ).run(e.boxId, e.owner, e.name, e.at, e.state, e.vcpu, e.memMib, e.diskGib, e.by);
+}
+function insertUsageEvent(e, p = paths()) {
+  const db = openDb(p);
+  if (e.state === "running") closeOpenRun(e.boxId, e.at, p);
+  insertRaw(e, db);
+}
+function closeOpenRun(boxId, at, p = paths()) {
+  const db = openDb(p);
+  const last = lastEvent(boxId, db);
+  if (last === void 0 || last.state !== "running") return false;
+  insertRaw({ ...last, at, state: "stopped", by: "server" }, db);
+  return true;
+}
+function usageEventsFor(boxId, since, p = paths()) {
+  const rows = openDb(p).prepare("select * from usage_events where box_id = ? and at >= ? order by at, id").all(boxId, since);
+  return rows.map(fromRaw);
+}
 
 // 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 { basename } from "path";
-import { setTimeout as sleep } from "timers/promises";
+import { spawn } from "node:child_process";
+import { closeSync as closeSync2, existsSync as existsSync3, openSync as openSync2, statSync } from "node:fs";
+import { link, mkdir as mkdir3, readFile as readFile4, realpath, rm, truncate, writeFile as writeFile4 } from "node:fs/promises";
+import { basename } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
 
 // src/core/agent.ts
-import { connect } from "net";
+import { connect } from "node:net";
 var AGENT_PORT = 52;
 async function agentCall(udsPath, req, timeoutMs = 5e3) {
   const reply = await new Promise((resolve, reject) => {
@@ -377,7 +561,7 @@ function setIdentity(udsPath, id, timeoutMs) {
 }
 
 // src/core/capacity.ts
-import { cpus, totalmem } from "os";
+import { cpus, totalmem } from "node:os";
 var MEM_HEADROOM_MIB = 2048;
 var VCPU_OVERSUBSCRIPTION = 2;
 function hostResources() {
@@ -385,9 +569,9 @@ function hostResources() {
 }
 async function runningReservations(p = paths()) {
   const out = [];
-  for (const name of await listMachineNames(p)) {
+  for (const ref of await listMachineRefs(p)) {
     try {
-      const meta = await readMachineMeta(name, p);
+      const meta = await readMachineMeta(ref, p);
       if (pidAlive(meta.pid)) out.push({ name: meta.name, vcpu: meta.vcpu, memMib: meta.memMib });
     } catch {
     }
@@ -570,13 +754,35 @@ 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 diskGibOf(meta, p) {
+  try {
+    return Math.round(statSync(ownDisk(meta, p)).size / 1024 ** 3);
+  } catch {
+    return 0;
+  }
+}
+function recordState(meta, state, by, p, at = (/* @__PURE__ */ new Date()).toISOString()) {
+  try {
+    insertUsageEvent({ boxId: refKey(meta), owner: meta.owner, name: meta.name, at, state, by, vcpu: meta.vcpu, memMib: meta.memMib, diskGib: diskGibOf(meta, p) }, p);
+  } catch (err) {
+    console.error(`warning: usage ledger: ${err.message}`);
+  }
+}
 function toMachine(meta, p = paths()) {
   const alive = pidAlive(meta.pid);
+  if (!alive && meta.pid !== null) {
+    try {
+      closeOpenRun(refKey(meta), (/* @__PURE__ */ new Date()).toISOString(), p);
+    } catch (err) {
+      console.error(`warning: usage ledger: ${err.message}`);
+    }
+  }
   return {
     name: meta.name,
+    owner: meta.owner,
     ip: meta.ip,
     mac: meta.mac,
     pid: alive ? meta.pid : null,
@@ -591,17 +797,20 @@ 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));
+}
+async function getMachine(ref, p = paths()) {
+  return toMachine(await readMeta(ref, p), p);
 }
 function pickName(requested, taken) {
   if (requested !== void 0) {
@@ -636,7 +845,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();
@@ -650,7 +859,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]);
 }
@@ -664,30 +873,30 @@ 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");
+  const logFd = openSync2(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]
     });
   } finally {
-    closeSync(logFd);
+    closeSync2(logFd);
   }
   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)}`);
@@ -701,9 +910,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 {
@@ -727,10 +936,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 {
@@ -744,7 +953,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);
@@ -764,23 +973,23 @@ 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];
@@ -788,23 +997,24 @@ async function createMachine(req, p = paths()) {
   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);
+    recordState(meta, "running", "new", p, meta.createdAt);
     return toMachine(meta, p);
   } catch (err) {
     if (tapCreated) await deleteTap(name, cfg).catch(() => void 0);
@@ -812,35 +1022,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 {
@@ -848,7 +1059,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 {
@@ -856,10 +1067,11 @@ 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);
+    recordState(meta, "running", "new", p, meta.createdAt);
     return toMachine(meta, p);
   } catch (err) {
     if (pid !== void 0) killQuietly(pid);
@@ -893,7 +1105,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 {
@@ -910,62 +1122,66 @@ 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);
+  recordState(stopped, "stopped", "stop", 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);
+    recordState(started, "running", "start", p);
     return toMachine(started, p);
   } catch (err) {
-    await deleteTap(name, cfg).catch(() => void 0);
+    await deleteTap(ref.name, cfg).catch(() => void 0);
     throw err;
   }
 }
-async function applyAtNextBoot(meta, changes, cfg, p, whileStopped) {
+async function applyAtNextBoot(meta, changes, by, 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);
+  recordState(updated, "stopped", by, 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);
   if (base.version === meta.base) return toMachine(meta, p);
   await assertOverlayCapable(base.file, base.version);
-  return applyAtNextBoot(meta, { base: base.version }, cfg, p);
+  return applyAtNextBoot(meta, { base: base.version }, "update", 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);
@@ -976,33 +1192,130 @@ 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;
   if (target.memMib !== meta.memMib) changes.memMib = target.memMib;
   const growTo = target.diskGib > currentDiskGib ? target.diskGib : void 0;
   if (Object.keys(changes).length === 0 && growTo === void 0) return toMachine(meta, p);
-  return applyAtNextBoot(meta, changes, cfg, p, growTo === void 0 ? void 0 : () => growDisk(disk, growTo));
+  return applyAtNextBoot(meta, changes, "rescale", cfg, p, growTo === void 0 ? void 0 : () => growDisk(disk, growTo));
 }
 async function growDisk(file, gib) {
   await truncate(file, gib * 1024 ** 3);
   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 });
+  recordState(meta, "stopped", "rm", p);
+  await rm(p.machine(ref.owner, ref.name).dir, { recursive: true, force: true });
+}
+
+// src/core/usage.ts
+var HOUR_MS = 36e5;
+var round = (n, places) => Math.round(n * 10 ** places) / 10 ** places;
+function computeUsage(events, w) {
+  const sorted = [...events].sort((a, b) => a.at < b.at ? -1 : a.at > b.at ? 1 : 0);
+  const from = Date.parse(w.from);
+  const to = Date.parse(w.to);
+  const ms = { running: 0, stopped: 0 };
+  let vcpuHours = 0;
+  let ramGibHours = 0;
+  let diskGibHours = 0;
+  sorted.forEach((e, i) => {
+    const start = Math.max(Date.parse(e.at), from);
+    const next = sorted[i + 1];
+    const end = Math.min(next === void 0 ? to : Date.parse(next.at), to);
+    if (end <= start) return;
+    const h = (end - start) / HOUR_MS;
+    ms[e.state] += end - start;
+    if (e.state === "running") {
+      vcpuHours += h * e.vcpu;
+      ramGibHours += h * e.memMib / 1024;
+    }
+    diskGibHours += h * e.diskGib;
+  });
+  const totals = {
+    seconds: { running: Math.round(ms.running / 1e3), stopped: Math.round(ms.stopped / 1e3) },
+    vcpuHours: round(vcpuHours, 3),
+    ramGibHours: round(ramGibHours, 3),
+    diskGibHours: round(diskGibHours, 3),
+    estimatedStops: sorted.filter((e) => e.state === "stopped" && e.by === "server" && e.at >= w.from).length,
+    historyFrom: sorted[0]?.at ?? null
+  };
+  if (w.pricing !== void 0) {
+    const amount = vcpuHours * w.pricing.vcpuHour + ramGibHours * w.pricing.ramGibHour + diskGibHours * w.pricing.diskGibHour;
+    totals.cost = { amount: round(amount, 4), currency: w.pricing.currency };
+  }
+  return totals;
+}
+var GIB = 1024 ** 3;
+async function machineUsage(ref, since, p = paths()) {
+  const box = await getMachine(ref, p);
+  const cfg = await loadConfig(p);
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const boxId = refKey(ref);
+  let events = usageEventsFor(boxId, box.createdAt, p);
+  if (events.length === 0) {
+    insertUsageEvent(
+      { boxId, owner: box.owner, name: box.name, at: now, state: box.status, by: "upgrade", vcpu: box.vcpu, memMib: box.memMib, diskGib: Math.round(box.diskBytes / GIB) },
+      p
+    );
+    events = usageEventsFor(boxId, box.createdAt, p);
+  }
+  const window = { from: since ?? box.createdAt, to: now };
+  return { name: box.name, owner: box.owner, status: box.status, window, ...computeUsage(events, { ...window, pricing: cfg.pricing }) };
+}
+async function seedUsageLedger(p = paths()) {
+  let seeded = 0;
+  for (const box of await listMachines(null, p)) {
+    const boxId = `${box.owner}/${box.name}`;
+    if (usageEventsFor(boxId, box.createdAt, p).length > 0) continue;
+    insertUsageEvent(
+      { boxId, owner: box.owner, name: box.name, at: (/* @__PURE__ */ new Date()).toISOString(), state: box.status, by: "upgrade", vcpu: box.vcpu, memMib: box.memMib, diskGib: Math.round(box.diskBytes / GIB) },
+      p
+    );
+    seeded += 1;
+  }
+  return seeded;
+}
+
+// src/app.ts
+import { Hono as Hono4 } from "hono";
+
+// ../shared/src/version.ts
+import { createRequire } from "node:module";
+function versionOf(srcFileUrl, injected) {
+  if (typeof injected === "string") return injected;
+  try {
+    const require2 = createRequire(srcFileUrl);
+    return require2("../package.json").version;
+  } catch {
+    return "0.0.0-dev";
+  }
+}
+
+// src/version.ts
+var VERSION = versionOf(import.meta.url, true ? "0.0.17" : void 0);
+
+// src/caller.ts
+function resolveCaller() {
+  return async (c, next) => {
+    const cfg = await loadConfig();
+    c.set("owner", cfg.owner);
+    await next();
+  };
 }
 
 // src/routes/capacity.ts
@@ -1021,6 +1334,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(),
@@ -1039,6 +1354,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()
@@ -1051,8 +1368,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(),
@@ -1077,7 +1395,23 @@ 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 MachineUsageSchema = z3.object({
+  name: z3.string(),
+  owner: z3.string(),
+  status: z3.enum(["running", "stopped"]),
+  window: z3.object({ from: z3.string(), to: z3.string() }),
+  seconds: z3.object({ running: z3.number().int(), stopped: z3.number().int() }),
+  vcpuHours: z3.number(),
+  ramGibHours: z3.number(),
+  diskGibHours: z3.number(),
+  cost: z3.object({ amount: z3.number(), currency: z3.string() }).optional(),
+  /** Stops the server did not witness (Firecracker died, host rebooted) and dated to when it noticed. */
+  estimatedStops: z3.number().int(),
+  historyFrom: z3.string().nullable()
 });
 var ApiErrorSchema = z3.object({
   error: z3.string()
@@ -1086,20 +1420,30 @@ 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.get("/:name/usage", async (c) => {
+    const since = c.req.query("since");
+    let from;
+    if (since !== void 0) {
+      const t = Date.parse(since);
+      if (Number.isNaN(t)) throw new KvboxError(`since: "${since}" is not a date; write it like 2026-10-19 or 2026-10-19T08:00:00Z`);
+      from = new Date(t).toISOString();
+    }
+    return c.json(await machineUsage(parseRef(c.req.param("name"), c.get("owner")), from));
   });
   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;
@@ -1109,12 +1453,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 "node:fs";
+import { link as link2, mkdir as mkdir4, readdir as readdir3, rename as rename2, rm as rm2, stat } 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,
@@ -1123,54 +1468,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 {
@@ -1197,7 +1543,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,
@@ -1215,27 +1562,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;
@@ -1244,9 +1592,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());
@@ -1266,7 +1621,14 @@ 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 seeded = await seedUsageLedger(p);
+  if (seeded > 0) console.error(`usage: started keeping time for ${seeded} box(es) made before this version; kvbox vm usage counts from now for them`);
   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`);
@@ -1277,7 +1639,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();