@kvbox/server 0.0.0-stage → 0.5.5

package/dist/kvbox-server.js

@@ -0,0 +1,2504 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { spawnSync } from "node:child_process";
+import { Command } from "commander";
+
+// ../shared/src/errors.ts
+var KvboxError = class extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.exitCode = exitCode;
+    this.name = "KvboxError";
+  }
+  exitCode;
+};
+var NotFoundError = class extends KvboxError {
+  constructor(what) {
+    super(`${what}: not found`, 1);
+    this.name = "NotFoundError";
+  }
+};
+
+// ../shared/src/paths.ts
+import { homedir } from "node:os";
+import { join } from "node:path";
+function kvboxHome() {
+  return process.env["KVBOX_HOME"] ?? join(homedir(), ".kvbox");
+}
+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"),
+    /** The CLI's login to the control plane (`kvbox login`): url, bearer token, user. Mode 600. */
+    cli: join(home, "cli.json"),
+    ssh: join(home, "ssh"),
+    sshKey: join(home, "ssh", "id_ed25519"),
+    /** The device key signed by the control plane's CA (#51); ssh loads it by itself next to `-i id_ed25519`. */
+    sshCert: join(home, "ssh", "id_ed25519-cert.pub"),
+    /** Host keys of the cloud boxes this laptop connected to, one entry per box (`connect`, #21). */
+    sshKnownHosts: join(home, "ssh", "known_hosts"),
+    /** The host's self-signed TLS identity for the control plane (`kvbox-server join`): pinned there by fingerprint. */
+    tls: join(home, "tls"),
+    tlsKey: join(home, "tls", "key.pem"),
+    tlsCert: join(home, "tls", "cert.pem"),
+    /** The host's WireGuard tunnel to its relay (`kvbox server relay`, #50): the conf net-setup.sh installs for wg-quick. Mode 600. */
+    relay: join(home, "relay"),
+    relayConf: join(home, "relay", "kvbox.conf"),
+    bin: join(home, "bin"),
+    firecracker: join(home, "bin", "firecracker"),
+    /** Firecracker's snapshot-editor, from the same release: merges a diff snapshot onto a full memory image. */
+    snapshotEditor: join(home, "bin", "snapshot-editor"),
+    assets: join(home, "assets"),
+    kernel: join(home, "assets", "vmlinux"),
+    /** Symlink to the current base image, assets/rootfs-<version>.ext4; boxes keep using the version they were made from. */
+    rootfs: join(home, "assets", "rootfs.ext4"),
+    baseImage: (version) => join(home, "assets", `rootfs-${version}.ext4`),
+    machines: join(home, "machines"),
+    snapshots: join(home, "snapshots"),
+    /** 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"),
+        /**
+         * 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"),
+        /** `kvbox hibernate`: the box's memory image and VM state while it is hibernated; gone again after `wake` or `stop`. */
+        hibernateDir: join(dir, "hibernate"),
+        hibernateVmstate: join(dir, "hibernate", "vmstate"),
+        hibernateMem: join(dir, "hibernate", "mem"),
+        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 { chmod, readFile, rename, writeFile } from "node:fs/promises";
+import { z } from "zod";
+
+// ../shared/src/sizes.ts
+var SIZES = {
+  s: { vcpu: 2, memMib: 4096, diskGib: 8 },
+  m: { vcpu: 4, memMib: 8192, diskGib: 16 },
+  l: { vcpu: 8, memMib: 16384, diskGib: 32 }
+};
+var SIZE_NAMES = Object.keys(SIZES);
+var DEFAULT_SIZE = "s";
+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 REALM_RE = /^[A-Za-z0-9.-]{1,128}$/;
+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 inScope(owner, scope) {
+  if (scope === null) return true;
+  if (typeof scope === "string") return owner === scope;
+  return realmOf(owner) === scope.realm;
+}
+function realmOf(owner) {
+  const at = owner.indexOf("@");
+  return at === -1 ? null : owner.slice(at + 1);
+}
+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>`);
+  }
+  const realm = realmOf(caller);
+  if (realm !== null && realmOf(owner) !== realm) {
+    throw new KvboxError(`invalid box reference "${text}": ${owner} is not in your realm`);
+  }
+  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 ControlPlaneSchema = z.object({
+  url: z.string().url(),
+  /** The realm name: boxes the control plane creates are owned by `<user>@<name>`, a directory name on disk. */
+  name: z.string().regex(REALM_RE),
+  /** Minted at join; every HTTPS call from the control plane carries it as a bearer. */
+  secret: z.string().min(1),
+  /** The address the control plane reaches this host at. */
+  advertise: z.string().min(1),
+  port: z.number().int().positive().default(7777)
+});
+var RelaySchema = z.object({
+  name: z.string().min(1),
+  publicIp: z.string().min(1),
+  tunnelIp: z.string().min(1),
+  /** `<relay-ip>:<port>` the tunnel dials. */
+  endpoint: z.string().min(1)
+});
+var ConfigSchema = z.object({
+  kernel: z.string(),
+  rootfs: z.string(),
+  firecracker: z.string(),
+  snapshotEditor: z.string().optional(),
+  // default: bin/snapshot-editor next to firecracker
+  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),
+  /** 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(),
+  /** Absent until the host joins a control plane; then the server also listens on HTTPS. */
+  controlPlane: ControlPlaneSchema.optional(),
+  /** Absent unless the host sits behind a relay. */
+  relay: RelaySchema.optional()
+});
+async function saveConfig(cfg, p = paths()) {
+  const parsed = ConfigSchema.parse(cfg);
+  const tmp = `${p.config}.tmp`;
+  await writeFile(tmp, JSON.stringify(parsed, null, 2) + "\n", { mode: 384 });
+  await chmod(tmp, 384);
+  await rename(tmp, p.config);
+}
+function defaultConfig(p = paths()) {
+  return ConfigSchema.parse({
+    kernel: p.kernel,
+    rootfs: p.rootfs,
+    firecracker: p.firecracker,
+    snapshotEditor: p.snapshotEditor,
+    owner: localOwner()
+  });
+}
+async function loadConfig(p = paths()) {
+  try {
+    const raw = await readFile(p.config, "utf8");
+    return ConfigSchema.parse(JSON.parse(raw));
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      const cfg = defaultConfig(p);
+      await writeFile(p.config, JSON.stringify(cfg, null, 2) + "\n");
+      return cfg;
+    }
+    throw err;
+  }
+}
+
+// src/core/controlPlane.ts
+import { X509Certificate } from "node:crypto";
+import { chmod as chmod2, mkdir, readFile as readFile2 } from "node:fs/promises";
+import { hostname as osHostname } from "node:os";
+import { request } from "undici";
+
+// ../shared/src/api.ts
+import { z as z2 } from "zod";
+var SizeSchema = z2.enum(SIZE_NAMES);
+var BoxStatusSchema = z2.enum(["running", "standby", "hibernated", "stopped", "unknown"]);
+var MachineSchema = z2.object({
+  /** Host-unique short id (the tap is `kv-<id>`). Missing only on a box made before ids that has not restarted since. */
+  id: z2.string(),
+  name: z2.string(),
+  /** Who the box belongs to; names are unique per owner. A bare name is local to the host, `user@control-plane` later. */
+  owner: z2.string(),
+  ip: z2.string(),
+  mac: z2.string(),
+  pid: z2.number().int().nullable(),
+  vcpu: z2.number().int(),
+  memMib: z2.number().int(),
+  diskBytes: z2.number().int(),
+  // the box's own writable disk, as the guest sees it
+  diskUsedBytes: z2.number().int(),
+  // what that sparse file really occupies on the host
+  base: z2.string(),
+  // base image version the box's overlay stacks on
+  createdAt: z2.string(),
+  source: z2.string(),
+  // "base" or "snapshot:<name>"
+  status: BoxStatusSchema,
+  /**
+   * Public TCP port on the host that reaches the box's SSH while it runs (#49). Only boxes made
+   * through a control plane have one; the control plane adds the host's address for `connect` (#21).
+   */
+  sshPort: z2.number().int().optional(),
+  /**
+   * Where `ssh` reaches the box from outside: the host's public address and that port (#21). Only
+   * the control plane fills it in (a host does not know its own public address); absent for a box
+   * whose host reported no port or did not answer.
+   */
+  ssh: z2.object({ host: z2.string(), port: z2.number().int(), user: z2.string() }).optional(),
+  /** Whether the owner slug is a user or an org. Only the control plane knows; it fills it in on `GET /machines`. */
+  ownerKind: z2.enum(["user", "org"]).optional()
+});
+var CreateMachineRequest = z2.object({
+  name: z2.string().optional(),
+  /** Ignored over the local socket (the caller is the host owner); the control plane sets it over HTTPS. */
+  owner: z2.string().optional(),
+  size: SizeSchema.optional(),
+  from: z2.string().optional(),
+  force: z2.boolean().optional(),
+  /**
+   * Extra authorized_keys lines for the box, on top of the host's own key: the control plane sends
+   * its SSH CA as one `cert-authority …` line (#51). Written into the box's authorized_keys at every
+   * boot (#49); a host older than that ignores them.
+   */
+  sshKeys: z2.array(z2.string()).optional()
+});
+var SetSshKeysRequest = z2.object({
+  sshKeys: z2.array(z2.string())
+});
+var RescaleMachineRequest = z2.object({
+  size: SizeSchema.optional(),
+  vcpu: z2.number().int().min(1).max(64).optional(),
+  memMib: z2.number().int().min(256).optional(),
+  diskGib: z2.number().int().min(1).optional()
+});
+var SnapshotSchema = z2.object({
+  name: z2.string(),
+  owner: z2.string(),
+  source: z2.string(),
+  // the box it was taken from, as owner/name
+  base: z2.string(),
+  // base image version the overlay stacks on; a restore needs the same one
+  vcpu: z2.number().int(),
+  memMib: z2.number().int(),
+  sizeBytes: z2.number().int(),
+  // what vmstate + mem + overlay really occupy on the host
+  createdAt: z2.string()
+});
+var CreateSnapshotRequest = z2.object({
+  box: z2.string(),
+  name: z2.string()
+});
+var CapacitySchema = z2.object({
+  hostMemMib: z2.number().int(),
+  hostCores: z2.number().int(),
+  reservedMemMib: z2.number().int(),
+  reservedVcpu: z2.number().int(),
+  running: z2.number().int()
+});
+var HealthSchema = z2.object({
+  ok: z2.literal(true),
+  version: z2.string(),
+  pid: z2.number().int(),
+  /** Base image version new boxes get (null when the host has no usable base image yet). */
+  base: z2.string().nullable(),
+  /** Owner that boxes made over the local socket get (the Unix user running the server). */
+  owner: z2.string(),
+  /** The control plane this host joined (null when none). */
+  controlPlane: z2.object({
+    /** Realm name, e.g. kvbox.sh. */
+    name: z2.string(),
+    url: z2.string(),
+    /** Where this host answers the control plane. */
+    hostUrl: z2.string()
+  }).nullable(),
+  /** The relay this host reaches the internet through (#50); null when it has its own public address. Older servers omit it. */
+  relay: z2.object({
+    name: z2.string(),
+    /** The public IP the relay owns for this host. */
+    publicIp: z2.string(),
+    /** The relay's WireGuard endpoint the tunnel dials. */
+    endpoint: z2.string()
+  }).nullable().optional()
+});
+var MachineUsageSchema = z2.object({
+  name: z2.string(),
+  owner: z2.string(),
+  status: BoxStatusSchema,
+  window: z2.object({ from: z2.string(), to: z2.string() }),
+  seconds: z2.object({
+    running: z2.number().int(),
+    standby: z2.number().int(),
+    hibernated: z2.number().int(),
+    stopped: z2.number().int()
+  }),
+  vcpuHours: z2.number(),
+  ramGibHours: z2.number(),
+  diskGibHours: z2.number(),
+  cost: z2.object({ amount: z2.number(), currency: z2.string() }).optional(),
+  /** Stops the server did not witness (Firecracker died, host rebooted) and dated to when it noticed. */
+  estimatedStops: z2.number().int(),
+  historyFrom: z2.string().nullable()
+});
+var ApiErrorSchema = z2.object({
+  error: z2.string()
+});
+var CloudUserSchema = z2.object({
+  /** The handle: what hosts file boxes under (`<username>@<control plane>`). Lowercase, no `@` or `/`. */
+  username: z2.string(),
+  /** Display name, free text ("Alexandru Ghiura"). */
+  name: z2.string(),
+  /** Login identity, unique. */
+  email: z2.string(),
+  role: z2.enum(["admin", "user"]),
+  createdAt: z2.string()
+});
+var ORG_ROLES = ["owner", "admin", "member"];
+var OrgRoleSchema = z2.enum(ORG_ROLES);
+var CloudOrgSchema = z2.object({
+  slug: z2.string(),
+  /** Display name; the slug never changes, this may. */
+  name: z2.string(),
+  createdAt: z2.string()
+});
+var OrgMembershipSchema = CloudOrgSchema.extend({ role: OrgRoleSchema });
+var OrgMemberSchema = z2.object({
+  username: z2.string(),
+  name: z2.string(),
+  role: OrgRoleSchema,
+  addedAt: z2.string()
+});
+var OrgDetailSchema = CloudOrgSchema.extend({ members: z2.array(OrgMemberSchema) });
+var CreateOrgRequestSchema = z2.object({
+  slug: z2.string().min(1),
+  name: z2.string().min(1)
+});
+var RenameOrgRequestSchema = z2.object({ name: z2.string().min(1) });
+var AddMemberRequestSchema = z2.object({
+  username: z2.string().min(1),
+  role: OrgRoleSchema.default("member")
+});
+var SetRoleRequestSchema = z2.object({ role: OrgRoleSchema });
+var MeResponseSchema = CloudUserSchema.extend({ orgs: z2.array(OrgMembershipSchema) });
+var LoginRequestSchema = z2.object({
+  email: z2.string().min(1),
+  password: z2.string().min(1),
+  publicKey: z2.string().optional()
+});
+var SignupRequestSchema = z2.object({
+  username: z2.string().min(1),
+  name: z2.string().min(1),
+  email: z2.string().min(1),
+  password: z2.string().min(1)
+});
+var LoginResponseSchema = z2.object({
+  token: z2.string(),
+  user: CloudUserSchema,
+  sshCert: z2.string().optional(),
+  sshCertExpires: z2.string().optional(),
+  /** Whose boxes the certificate opens: `<slug>@<realm>` for the user and each org they are in (orgs phase 4). */
+  sshCertPrincipals: z2.array(z2.string()).optional()
+});
+var SshCertRequestSchema = z2.object({
+  publicKey: z2.string().min(1)
+});
+var SshCertResponseSchema = z2.object({
+  cert: z2.string(),
+  expires: z2.string(),
+  principals: z2.array(z2.string())
+});
+var SshCaResponseSchema = z2.object({
+  publicKey: z2.string(),
+  /** CAs replaced by `ca rotate` (#55), newest first; a box still holding one of these has not had `kvbox server trust-ca` run on its host. */
+  retired: z2.array(z2.object({ publicKey: z2.string(), retiredAt: z2.string() })).optional()
+});
+var HostSshCaResponseSchema = z2.object({
+  publicKey: z2.string()
+});
+var CloudCaSchema = z2.object({
+  controlPlane: z2.string(),
+  publicKey: z2.string(),
+  fingerprint: z2.string()
+});
+var TrustCaRequestSchema = z2.object({
+  publicKey: z2.string().min(1)
+});
+var SshKeysAppliedSchema = z2.enum(["now", "start", "wake", "resume", "later"]);
+var TrustCaReportSchema = z2.object({
+  publicKey: z2.string(),
+  fingerprint: z2.string(),
+  /** The guest trusts the CA now. */
+  updated: z2.array(z2.string()),
+  /** meta.json has the line; the guest gets it at `when`. */
+  pending: z2.array(z2.object({ box: z2.string(), when: SshKeysAppliedSchema, why: z2.string().optional() })),
+  failed: z2.array(z2.object({ box: z2.string(), error: z2.string() })),
+  /** Local boxes, untouched: they trust the host's key only. */
+  local: z2.number().int()
+});
+var HostJoinRequestSchema = z2.object({
+  token: z2.string().min(1),
+  name: z2.string().min(1),
+  url: z2.string().url(),
+  fingerprint: z2.string().regex(/^([0-9A-F]{2}:){31}[0-9A-F]{2}$/),
+  publicAddress: z2.string().min(1)
+});
+var HostJoinResponseSchema = z2.object({
+  hostSecret: z2.string(),
+  controlPlane: z2.object({ name: z2.string() })
+});
+var CloudHostSchema = z2.object({
+  name: z2.string(),
+  url: z2.string(),
+  publicAddress: z2.string(),
+  joinedAt: z2.string(),
+  lastSeenAt: z2.string().nullable(),
+  capacity: CapacitySchema.nullable()
+});
+
+// ../shared/src/ssh.ts
+import { createHash } from "node:crypto";
+var SSH_PUBLIC_KEY_RE = /^(ssh-ed25519|ssh-rsa|ecdsa-sha2-nistp(?:256|384|521)|sk-ssh-ed25519@openssh\.com|sk-ecdsa-sha2-nistp256@openssh\.com) ([A-Za-z0-9+/]+=*)(?: [^\r\n]*)?$/;
+function parseSshPublicKey(text) {
+  const key = text.trim().replace(/^cert-authority\s+/, "");
+  if (!SSH_PUBLIC_KEY_RE.test(key)) {
+    throw new KvboxError("that is not an SSH public key; expected one line like: ssh-ed25519 AAAA\u2026 kvbox-ca@kvbox.sh");
+  }
+  return key;
+}
+function sshKeyFingerprint(publicKey) {
+  const m = SSH_PUBLIC_KEY_RE.exec(publicKey.trim());
+  if (!m) throw new KvboxError("cannot fingerprint: not an SSH public key");
+  return `SHA256:${createHash("sha256").update(Buffer.from(m[2], "base64")).digest("base64").replace(/=+$/, "")}`;
+}
+function caLineFor(principal, caPublicKey) {
+  return `cert-authority,principals="${principal}" ${caPublicKey}`;
+}
+var isCaLine = (line) => /^cert-authority(,|\s)/.test(line.trim());
+
+// src/core/exec.ts
+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;
+  if (!cmd) throw new KvboxError("run: empty argv");
+  if (process.env["KVBOX_DEBUG"]) console.error(`[exec] ${[cmd, ...args].join(" ")}`);
+  try {
+    const { stdout, stderr } = await execFileAsync(cmd, args, {
+      cwd: opts.cwd,
+      env: opts.env ?? process.env,
+      timeout: opts.timeoutMs ?? 3e4,
+      maxBuffer: 8 * 1024 * 1024
+    });
+    return { stdout, stderr };
+  } catch (err) {
+    const e = err;
+    if (typeof e.code === "number" && opts.okExitCodes?.includes(e.code)) return { stdout: e.stdout ?? "", stderr: e.stderr ?? "" };
+    const detail = (e.stderr ?? e.message ?? "").trim();
+    throw new KvboxError(`${[cmd, ...args].join(" ")} failed${detail ? `: ${detail}` : ""}`);
+  }
+}
+
+// src/core/controlPlane.ts
+var DEFAULT_HTTPS_PORT = 7777;
+async function ensureTlsCert(p = paths()) {
+  const have = await readFile2(p.tlsCert, "utf8").catch(() => null);
+  const haveKey = await readFile2(p.tlsKey).then(() => true, () => false);
+  if (have === null || !haveKey) {
+    await mkdir(p.tls, { recursive: true, mode: 448 });
+    try {
+      await run([
+        "openssl",
+        "req",
+        "-x509",
+        "-newkey",
+        "ec",
+        "-pkeyopt",
+        "ec_paramgen_curve:prime256v1",
+        "-nodes",
+        "-keyout",
+        p.tlsKey,
+        "-out",
+        p.tlsCert,
+        "-subj",
+        "/CN=kvbox-host",
+        "-days",
+        "3650"
+      ]);
+    } catch (err) {
+      throw new KvboxError(`could not make the host's certificate (is openssl installed?): ${err.message}`);
+    }
+    await chmod2(p.tlsKey, 384);
+  }
+  const pem = await readFile2(p.tlsCert, "utf8");
+  return { fingerprint: new X509Certificate(pem).fingerprint256 };
+}
+function isPrivateAddress(ip) {
+  const m = /^(\d+)\.(\d+)\.(\d+)\.(\d+)$/.exec(ip);
+  if (!m) return false;
+  const [a, b] = [Number(m[1]), Number(m[2])];
+  return a === 10 || a === 127 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 168 || a === 169 && b === 254 || a === 100 && b >= 64 && b <= 127;
+}
+async function defaultAdvertise() {
+  const { stdout } = await run(["ip", "-4", "route", "get", "1.1.1.1"]).catch((err) => {
+    throw new KvboxError(`cannot tell this host's address (${err.message}); pass --advertise <host-or-ip>`);
+  });
+  const m = /\bsrc\s+(\S+)/.exec(stdout);
+  if (!m) throw new KvboxError("cannot tell this host's address from its routes; pass --advertise <host-or-ip>");
+  return m[1];
+}
+async function joinControlPlane(opts, p = paths(), guessAddress = defaultAdvertise) {
+  const url = opts.url.replace(/\/+$/, "");
+  const port = opts.port ?? DEFAULT_HTTPS_PORT;
+  const cfg = await loadConfig(p);
+  if (cfg.controlPlane) throw new KvboxError(`this host has already joined ${cfg.controlPlane.name} (${cfg.controlPlane.url}); run kvbox server leave first`);
+  let advertise = opts.advertise;
+  if (advertise === void 0 && cfg.relay) {
+    advertise = cfg.relay.publicIp;
+  } else if (advertise === void 0) {
+    advertise = await guessAddress();
+    if (isPrivateAddress(advertise)) {
+      throw new KvboxError(
+        `${advertise} is a private address: a control plane on the internet cannot reach this host there.
+  Pass --advertise <public host or ip>, or --advertise ${advertise} if the control plane is on the same network.`
+      );
+    }
+  }
+  const name = opts.name ?? osHostname();
+  const { fingerprint } = await ensureTlsCert(p);
+  const hostUrl = `https://${advertise}:${port}`;
+  const body = { token: opts.token, name, url: hostUrl, fingerprint, publicAddress: advertise };
+  const res = await request(`${url}/hosts/join`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+    headersTimeout: 1e4,
+    bodyTimeout: 1e4
+  }).catch((err) => {
+    throw new KvboxError(`cannot reach ${url} (${err.message})`);
+  });
+  const text = await res.body.text();
+  if (res.statusCode < 200 || res.statusCode >= 300) {
+    throw new KvboxError(errorIn(text) ?? `control plane answered ${res.statusCode}`);
+  }
+  const parsed = HostJoinResponseSchema.safeParse(jsonOrNull(text));
+  if (!parsed.success) throw new KvboxError(`${url} did not answer like a kvbox control plane`);
+  if (!REALM_RE.test(parsed.data.controlPlane.name)) {
+    throw new KvboxError(`${url} calls itself "${parsed.data.controlPlane.name}", which cannot name a realm (letters, digits, '.', '-')`);
+  }
+  await saveConfig({ ...cfg, controlPlane: { url, name: parsed.data.controlPlane.name, secret: parsed.data.hostSecret, advertise, port } }, p);
+  return { hostName: name, controlPlane: parsed.data.controlPlane.name, hostUrl };
+}
+async function fetchCloudCa(p = paths()) {
+  const cfg = await loadConfig(p);
+  const cp = cfg.controlPlane;
+  if (!cp) throw new KvboxError("this host has not joined a control plane, so there is no CA to fetch; paste the key instead: kvbox server trust-ca <public-key>");
+  const res = await request(`${cp.url}/hosts/self/ssh-ca`, {
+    headers: { authorization: `Bearer ${cp.secret}` },
+    headersTimeout: 1e4,
+    bodyTimeout: 1e4
+  }).catch((err) => {
+    throw new KvboxError(`cannot reach ${cp.url} (${err.message})`);
+  });
+  const text = await res.body.text();
+  if (res.statusCode === 404) throw new KvboxError(`${cp.name} does not answer /hosts/self/ssh-ca: it is older than this host; paste the key instead`);
+  if (res.statusCode < 200 || res.statusCode >= 300) throw new KvboxError(errorIn(text) ?? `${cp.name} answered ${res.statusCode}`);
+  const parsed = HostSshCaResponseSchema.safeParse(jsonOrNull(text));
+  if (!parsed.success) throw new KvboxError(`${cp.name} did not answer with a CA key`);
+  const publicKey = parseSshPublicKey(parsed.data.publicKey);
+  return { controlPlane: cp.name, publicKey, fingerprint: sshKeyFingerprint(publicKey) };
+}
+async function leaveControlPlane(p = paths()) {
+  const cfg = await loadConfig(p);
+  const cp = cfg.controlPlane;
+  if (!cp) throw new KvboxError("this host has not joined a control plane");
+  const told = await request(`${cp.url}/hosts/self`, {
+    method: "DELETE",
+    headers: { authorization: `Bearer ${cp.secret}` },
+    headersTimeout: 3e3,
+    bodyTimeout: 3e3
+  }).then(async (res) => {
+    await res.body.dump();
+    return res.statusCode >= 200 && res.statusCode < 300;
+  }).catch(() => false);
+  const { controlPlane: _gone, ...rest } = cfg;
+  await saveConfig(rest, p);
+  return { controlPlane: cp.name, told };
+}
+function jsonOrNull(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+function errorIn(text) {
+  const v = jsonOrNull(text);
+  if (v && typeof v === "object" && typeof v.error === "string") return v.error;
+  return void 0;
+}
+
+// src/core/kvm.ts
+import { access, constants, readFile as readFile3, stat } from "node:fs/promises";
+var KVM_DEVICE = "/dev/kvm";
+async function groupName(gid, groupFile = "/etc/group") {
+  const text = await readFile3(groupFile, "utf8").catch(() => "");
+  for (const line of text.split("\n")) {
+    const [name, , id] = line.split(":");
+    if (id !== void 0 && Number.parseInt(id, 10) === gid && name) return name;
+  }
+  return "kvm";
+}
+async function requireKvm(device = KVM_DEVICE, groupFile = "/etc/group") {
+  try {
+    await access(device, constants.R_OK | constants.W_OK);
+    return;
+  } catch (err) {
+    const code = err.code;
+    if (code === "ENOENT") {
+      throw new KvboxError(`${device} is missing: this machine has no KVM, so boxes cannot run here (enable virtualization in the BIOS, then install-server.sh checks the rest)`);
+    }
+    if (code !== "EACCES" && code !== "EPERM") throw new KvboxError(`cannot open ${device}: ${err.message}`);
+  }
+  const owner = await stat(device).then((s) => groupName(s.gid, groupFile), () => "kvm");
+  throw new KvboxError(
+    `cannot start: this process is not allowed to open ${device}, so no box could run. It was started from a shell without the ${owner} group (a login from before you were added to it). Log out and back in, or start it from a shell that has the group: sg ${owner} -c "kvbox server start"`
+  );
+}
+
+// src/core/network.ts
+import { randomInt } from "node:crypto";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+var TAP_PREFIX = "kv-";
+var PRIVILEGED_SCRIPT = "/usr/local/lib/kvbox/net-setup.sh";
+function tapName(box) {
+  return `${TAP_PREFIX}${box}`.slice(0, 15);
+}
+function netSetupScript() {
+  const override = process.env["KVBOX_NET_SETUP"];
+  if (override) return override;
+  if (existsSync(PRIVILEGED_SCRIPT)) return PRIVILEGED_SCRIPT;
+  for (const rel of ["../scripts/net-setup.sh", "../../scripts/net-setup.sh"]) {
+    const candidate = fileURLToPath(new URL(rel, import.meta.url));
+    if (existsSync(candidate)) return candidate;
+  }
+  throw new KvboxError("net-setup.sh not found next to kvbox-server");
+}
+function bridgeExists(bridge) {
+  return existsSync(`/sys/class/net/${bridge}`);
+}
+function netRun(cfg, args) {
+  return run([netSetupScript(), ...args], {
+    env: { ...process.env, KVBOX_BRIDGE: cfg.bridge, KVBOX_SUBNET: cfg.subnet, KVBOX_GATEWAY: cfg.gateway }
+  }).catch((err) => {
+    throw new KvboxError(
+      `${err.message}
+  (root is needed for host networking; install-server.sh sets up a sudoers rule for ${PRIVILEGED_SCRIPT})`
+    );
+  });
+}
+async function netSetup(cfg, args) {
+  await netRun(cfg, args);
+}
+async function ensureHostNetwork(cfg) {
+  if (bridgeExists(cfg.bridge)) return "present";
+  await netRun(cfg, ["up"]);
+  return "created";
+}
+async function createTap(box, cfg, opts = {}) {
+  const tap = tapName(box);
+  await netRun(cfg, ["tap", "add", tap, ...opts.detached ? ["detached"] : []]);
+  return tap;
+}
+async function attachTap(box, cfg) {
+  await netRun(cfg, ["tap", "attach", tapName(box)]);
+}
+async function deleteTap(box, cfg) {
+  await netRun(cfg, ["tap", "del", tapName(box)]);
+}
+var SSH_PORT_MIN = 2e4;
+var SSH_PORT_MAX = 6e4;
+function pickSshPort(taken) {
+  const span = SSH_PORT_MAX - SSH_PORT_MIN + 1;
+  for (let i = 0; i < 32; i++) {
+    const port = SSH_PORT_MIN + randomInt(span);
+    if (!taken.has(port)) return port;
+  }
+  const start = randomInt(span);
+  for (let i = 0; i < span; i++) {
+    const port = SSH_PORT_MIN + (start + i) % span;
+    if (!taken.has(port)) return port;
+  }
+  throw new KvboxError(`no free port left between ${SSH_PORT_MIN} and ${SSH_PORT_MAX} on this host`);
+}
+function parseListeningPorts(ssOutput) {
+  const ports = /* @__PURE__ */ new Set();
+  for (const line of ssOutput.split("\n")) {
+    const cols = line.trim().split(/\s+/);
+    const local = cols[3];
+    if (!local) continue;
+    const port = Number(local.slice(local.lastIndexOf(":") + 1));
+    if (Number.isInteger(port) && port > 0) ports.add(port);
+  }
+  return ports;
+}
+async function listeningPorts() {
+  try {
+    return parseListeningPorts((await run(["ss", "-ltnH"])).stdout);
+  } catch {
+    return /* @__PURE__ */ new Set();
+  }
+}
+var proxyArgs = (p) => [p.box, p.boxIp, String(p.hostPort), String(p.guestPort), p.proto ?? "tcp"];
+async function openProxy(proxy, cfg) {
+  await netRun(cfg, ["proxy", "add", ...proxyArgs(proxy)]);
+}
+async function closeProxy(proxy, cfg) {
+  await netRun(cfg, ["proxy", "rm", ...proxyArgs(proxy)]);
+}
+var ipToInt = (ip) => ip.split(".").reduce((acc, o) => (acc << 8) + Number(o), 0) >>> 0;
+var intToIp = (n) => [24, 16, 8, 0].map((s) => n >>> s & 255).join(".");
+function nextFreeIp(subnet, inUse) {
+  const [base, lenStr] = subnet.split("/");
+  const len = Number(lenStr);
+  if (!base || !Number.isInteger(len) || len < 8 || len > 30) throw new KvboxError(`bad subnet: ${subnet}`);
+  const mask = len === 0 ? 0 : ~0 << 32 - len >>> 0;
+  const network = (ipToInt(base) & mask) >>> 0;
+  const broadcast = (network | ~mask >>> 0) >>> 0;
+  const used = new Set(inUse.map(ipToInt));
+  for (let n = network + 2; n < broadcast; n++) {
+    if (!used.has(n)) return intToIp(n);
+  }
+  throw new KvboxError(`no free IP left in ${subnet}`);
+}
+function macFor(ip) {
+  const hex = ip.split(".").map((o) => Number(o).toString(16).padStart(2, "0").toUpperCase());
+  return ["06", "00", ...hex].join(":");
+}
+
+// src/core/relay.ts
+import { chmod as chmod3, mkdir as mkdir2, rm, writeFile as writeFile2 } from "node:fs/promises";
+
+// ../shared/src/relay.ts
+import { z as z3 } from "zod";
+var RELAY_TUNNEL_GATEWAY = "10.77.0.1";
+var IPV4_RE = /^(\d{1,3})(\.\d{1,3}){3}$/;
+var WG_KEY_RE = /^[A-Za-z0-9+/]{43}=$/;
+var RelayJoinSchema = z3.object({
+  v: z3.literal(1),
+  /** How the relay lists this host. */
+  name: z3.string().regex(/^[a-z0-9][a-z0-9-]{0,30}$/),
+  /** `<relay-primary-ip>:<port>`, the WireGuard endpoint the host dials. */
+  relay: z3.string().regex(/^(\d{1,3})(\.\d{1,3}){3}:\d{1,5}$/),
+  /** The relay's WireGuard public key. */
+  relayKey: z3.string().regex(WG_KEY_RE),
+  /** This host's address inside the tunnel. */
+  tunnelIp: z3.string().regex(IPV4_RE),
+  /** This host's WireGuard private key, generated on the relay, kept nowhere else. */
+  privateKey: z3.string().regex(WG_KEY_RE),
+  /** The extra public IPv4 the relay owns for this host; what the host advertises to the control plane. */
+  publicIp: z3.string().regex(IPV4_RE)
+});
+function decodeRelayJoin(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(Buffer.from(text.trim(), "base64url").toString("utf8"));
+  } catch {
+    return null;
+  }
+  const res = RelayJoinSchema.safeParse(parsed);
+  return res.success ? res.data : null;
+}
+
+// src/core/relay.ts
+function relayConf(join2) {
+  return [
+    "# kvbox relay tunnel: made by `kvbox server relay`, installed by net-setup.sh. Do not edit.",
+    "[Interface]",
+    `PrivateKey = ${join2.privateKey}`,
+    `Address = ${join2.tunnelIp}/32`,
+    "",
+    "[Peer]",
+    `PublicKey = ${join2.relayKey}`,
+    `Endpoint = ${join2.relay}`,
+    // Only the relay's own tunnel address goes through the tunnel: the host keeps its normal internet
+    // route, and the relay SNATs forwarded connections so their replies come back this way.
+    `AllowedIPs = ${RELAY_TUNNEL_GATEWAY}/32`,
+    // The router forgets an idle outbound mapping; a packet every 25 s keeps the relay able to reach us.
+    "PersistentKeepalive = 25",
+    ""
+  ].join("\n");
+}
+async function useRelay(joinString, p = paths()) {
+  const join2 = decodeRelayJoin(joinString);
+  if (!join2) throw new KvboxError("that is not a relay join string; copy the whole line `kvbox-relay add` printed on the relay");
+  const cfg = await loadConfig(p);
+  if (cfg.relay && cfg.relay.name !== join2.name) {
+    throw new KvboxError(`this host already goes through relay ${cfg.relay.name} (${cfg.relay.publicIp}); run kvbox server relay off first`);
+  }
+  if (cfg.relay && cfg.relay.publicIp !== join2.publicIp && cfg.controlPlane?.advertise === cfg.relay.publicIp) {
+    throw new KvboxError(
+      `${cfg.controlPlane.name} reaches this host at ${cfg.relay.publicIp}, not ${join2.publicIp}; run kvbox server leave first, then join again`
+    );
+  }
+  await mkdir2(p.relay, { recursive: true, mode: 448 });
+  await writeFile2(p.relayConf, relayConf(join2), { mode: 384 });
+  await chmod3(p.relayConf, 384);
+  await netSetup(cfg, ["relay", "up", p.relayConf, String(cfg.controlPlane?.port ?? DEFAULT_HTTPS_PORT)]);
+  const relay = { name: join2.name, publicIp: join2.publicIp, tunnelIp: join2.tunnelIp, endpoint: join2.relay };
+  await saveConfig({ ...cfg, relay }, p);
+  return relay;
+}
+async function dropRelay(p = paths()) {
+  const cfg = await loadConfig(p);
+  const relay = cfg.relay;
+  if (!relay) throw new KvboxError("this host does not go through a relay");
+  if (cfg.controlPlane?.advertise === relay.publicIp) {
+    throw new KvboxError(`${cfg.controlPlane.name} reaches this host through the relay (${relay.publicIp}); run kvbox server leave first`);
+  }
+  await netSetup(cfg, ["relay", "down"]);
+  await rm(p.relayConf, { force: true });
+  const { relay: _gone, ...rest } = cfg;
+  await saveConfig(rest, p);
+  return relay;
+}
+
+// src/listen.ts
+import { readFile as readFile6, rm as rm4, writeFile as writeFile5 } from "node:fs/promises";
+import { createServer as createHttpsServer } from "node:https";
+import { createAdaptorServer } from "@hono/node-server";
+
+// src/core/state.ts
+import { randomBytes } from "node:crypto";
+import { mkdir as mkdir3, readFile as readFile4, readdir, writeFile as writeFile3 } from "node:fs/promises";
+import { z as z4 } from "zod";
+var MachineMetaSchema = z4.object({
+  /** Host-unique, minted at `kvbox new` (fresh or restored) and kept for the box's life; the tap is `kv-<id>`. */
+  id: z4.string(),
+  name: z4.string(),
+  /** Part of the box's identity: machines/<owner>/<name>. See refs.ts. */
+  owner: z4.string(),
+  ip: z4.string(),
+  mac: z4.string(),
+  pid: z4.number().int().nullable(),
+  // null: stopped on purpose, disk kept
+  vcpu: z4.number().int(),
+  memMib: z4.number().int(),
+  createdAt: z4.string(),
+  source: z4.string(),
+  /** Base image version (assets/rootfs-<version>.ext4) the box's overlay stacks on. */
+  base: z4.string(),
+  /**
+   * Snapshots taken since this VM started (boot or restore). Firecracker resets its dirty-page bitmap at
+   * each one, so when this is > 0 the next diff is only standalone merged onto `mem.base`; if that file
+   * is missing the lineage is broken and the next snapshot has to be a full dump. Absent: 0.
+   */
+  memSnapshots: z4.number().int().optional(),
+  /** `kvbox pause`: Firecracker is alive but the VM is frozen (standby). Absent: not paused. */
+  paused: z4.boolean().optional(),
+  /**
+   * authorized_keys lines the box gets on top of the host's own key, as the control plane sent them
+   * at `new` (#49). kvbox-init rewrites authorized_keys from the kernel cmdline at every boot, so
+   * `start` has to send the same lines again. Absent: host key only.
+   */
+  sshKeys: z4.array(z4.string()).optional(),
+  /**
+   * The guest's authorized_keys may not match `sshKeys`: they changed while the box was not running,
+   * or its agent could not take them (#55, #63). Cleared by a push through kvbox-agent or a boot.
+   */
+  sshKeysStale: z4.boolean().optional(),
+  /** Public port on the host DNATed to the box's SSH while it runs (#49); fixed for the box's life. Absent: none. */
+  sshPort: z4.number().int().optional()
+});
+function newBoxId(taken) {
+  for (; ; ) {
+    const id = randomBytes(3).toString("hex");
+    if (!taken.has(id)) return id;
+  }
+}
+var SnapshotMetaSchema = z4.object({
+  name: z4.string(),
+  owner: z4.string(),
+  /** The box it was taken from, as owner/name. */
+  source: z4.string(),
+  base: z4.string(),
+  vcpu: z4.number().int(),
+  memMib: z4.number().int(),
+  sizeBytes: z4.number().int(),
+  createdAt: z4.string()
+});
+async function ensureLayout(p = paths()) {
+  for (const dir of [p.home, p.ssh, p.bin, p.assets, p.machines, p.snapshots]) {
+    await mkdir3(dir, { recursive: true, mode: 448 });
+  }
+  return p;
+}
+async function readJson(file, schema) {
+  return schema.parse(JSON.parse(await readFile4(file, "utf8")));
+}
+async function listDirs(dir) {
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+  } catch (err) {
+    if (err.code === "ENOENT") return [];
+    throw err;
+  }
+}
+async function readMachineMeta(ref, p = paths()) {
+  return readJson(p.machine(ref.owner, ref.name).meta, MachineMetaSchema);
+}
+async function writeMachineMeta(meta, p = paths()) {
+  const m = p.machine(meta.owner, meta.name);
+  await mkdir3(m.dir, { recursive: true });
+  await writeFile3(m.meta, JSON.stringify(meta, null, 2) + "\n");
+}
+async function listMachineRefs(p = paths()) {
+  return listRefs(p.machines);
+}
+async function readSnapshotMeta(ref, p = paths()) {
+  return readJson(p.snapshot(ref.owner, ref.name).meta, SnapshotMetaSchema);
+}
+async function writeSnapshotMeta(meta, p = paths()) {
+  const s = p.snapshot(meta.owner, meta.name);
+  await mkdir3(s.dir, { recursive: true });
+  await writeFile3(s.meta, JSON.stringify(meta, null, 2) + "\n");
+}
+async function listSnapshotRefs(p = paths()) {
+  return listRefs(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;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+
+// src/app.ts
+import { Hono as Hono5 } 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.5.5" : void 0);
+
+// src/caller.ts
+import { createHash as createHash2, timingSafeEqual } from "node:crypto";
+var OWNER_HEADER = "x-kvbox-owner";
+function resolveCaller(opts = {}) {
+  const cp = opts.controlPlane;
+  if (!cp) {
+    return async (c, next) => {
+      const cfg = await loadConfig();
+      c.set("owner", cfg.owner);
+      c.set("listScope", cfg.owner);
+      await next();
+    };
+  }
+  const expected = digest(cp.secret);
+  return async (c, next) => {
+    const m = /^Bearer\s+(\S+)$/i.exec(c.req.header("authorization") ?? "");
+    if (!m || !timingSafeEqual(digest(m[1]), expected)) return c.json({ error: "not authorized" }, 401);
+    const user = c.req.header(OWNER_HEADER);
+    if (user === void 0) {
+      const path = c.req.path.replace(/\/$/, "");
+      const realmListing = c.req.method === "GET" && (path === "/machines" || path === "/snapshots");
+      if (!realmListing && /^\/(machines|snapshots)(\/|$)/.test(c.req.path)) {
+        return c.json({ error: "X-Kvbox-Owner header required" }, 400);
+      }
+      c.set("owner", "");
+      c.set("listScope", { realm: cp.name });
+    } else {
+      if (!LOCAL_OWNER_RE.test(user)) return c.json({ error: "X-Kvbox-Owner: letters, digits, '.', '_', '-'" }, 400);
+      const owner = `${user}@${cp.name}`;
+      c.set("owner", owner);
+      c.set("listScope", owner);
+    }
+    await next();
+  };
+}
+function digest(secret) {
+  return createHash2("sha256").update(secret).digest();
+}
+
+// src/core/machines.ts
+import { spawn } from "node:child_process";
+import { closeSync as closeSync2, existsSync as existsSync2, openSync as openSync2, statSync } from "node:fs";
+import { link, mkdir as mkdir4, readFile as readFile5, realpath, rm as rm2, 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 "node:net";
+var AGENT_PORT = 52;
+async function agentCall(udsPath, req, timeoutMs = 5e3) {
+  const reply = await new Promise((resolve, reject) => {
+    const sock = connect(udsPath);
+    let buf = "";
+    let handshaken = false;
+    const fail = (err) => {
+      sock.destroy();
+      reject(err);
+    };
+    sock.setTimeout(timeoutMs, () => fail(new KvboxError(`kvbox-agent did not answer within ${timeoutMs} ms`)));
+    sock.once("error", (err) => fail(new KvboxError(`kvbox-agent unreachable: ${err.message}`)));
+    sock.once("connect", () => sock.write(`CONNECT ${AGENT_PORT}
+`));
+    sock.on("data", (chunk) => {
+      buf += chunk.toString("utf8");
+      let nl;
+      while ((nl = buf.indexOf("\n")) !== -1) {
+        const line = buf.slice(0, nl);
+        buf = buf.slice(nl + 1);
+        if (!handshaken) {
+          if (!line.startsWith("OK ")) return fail(new KvboxError(`vsock connect refused: ${line}`));
+          handshaken = true;
+          sock.write(JSON.stringify(req) + "\n");
+        } else {
+          sock.end();
+          return resolve(line);
+        }
+      }
+    });
+    sock.once("close", () => {
+      if (!handshaken) fail(new KvboxError("vsock connection closed before the guest accepted"));
+      else fail(new KvboxError("kvbox-agent closed the connection without a reply"));
+    });
+  });
+  let parsed;
+  try {
+    parsed = JSON.parse(reply);
+  } catch {
+    throw new KvboxError(`kvbox-agent sent something that is not JSON: ${reply}`);
+  }
+  if (!parsed.ok) throw new KvboxError(`kvbox-agent: ${parsed.error}`);
+  return parsed;
+}
+function setIdentity(udsPath, id, timeoutMs) {
+  return agentCall(udsPath, { op: "identity", ...id }, timeoutMs);
+}
+function setAuthorizedKeys(udsPath, lines, timeoutMs) {
+  return agentCall(udsPath, { op: "authorizedKeys", lines: [...lines] }, timeoutMs);
+}
+var isUnknownOp = (err) => /unknown op/.test(err.message ?? "");
+
+// src/core/capacity.ts
+import { cpus, totalmem } from "node:os";
+
+// ../shared/src/capacity.ts
+var MEM_HEADROOM_MIB = 2048;
+var VCPU_OVERSUBSCRIPTION = 2;
+
+// src/core/capacity.ts
+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/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;
+    }
+  }
+}
+var LIVE_STATES = ["running", "standby"];
+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" && e.by !== "resume") 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 || !LIVE_STATES.includes(last.state)) 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/firecracker.ts
+import { Agent, request as request2 } from "undici";
+var FirecrackerClient = class {
+  constructor(socketPath) {
+    this.socketPath = socketPath;
+    this.agent = new Agent({ connect: { socketPath } });
+  }
+  socketPath;
+  agent;
+  async call(method, path, body) {
+    const res = await request2(`http://localhost${path}`, {
+      dispatcher: this.agent,
+      method,
+      headers: body === void 0 ? {} : { "content-type": "application/json" },
+      body: body === void 0 ? null : JSON.stringify(body)
+    });
+    const text = await res.body.text();
+    if (res.statusCode >= 300) {
+      throw new KvboxError(`firecracker ${method} ${path} -> ${res.statusCode}: ${text}`);
+    }
+    return text ? JSON.parse(text) : void 0;
+  }
+  bootSource(kernelImagePath, bootArgs2) {
+    return this.call("PUT", "/boot-source", { kernel_image_path: kernelImagePath, boot_args: bootArgs2 });
+  }
+  /** /dev/vda: the shared base image, read-only. Firecracker adds `root=/dev/vda ro` to the boot args to match. */
+  rootDrive(pathOnHost) {
+    return this.drive("rootfs", pathOnHost, { root: true, readOnly: true });
+  }
+  /** The box's own writable disk, /dev/vdb: the guest stacks it on the base as an overlay. */
+  overlayDrive(pathOnHost) {
+    return this.drive("overlay", pathOnHost, { root: false, readOnly: false });
+  }
+  drive(id, pathOnHost, opts) {
+    return this.call("PUT", `/drives/${id}`, {
+      drive_id: id,
+      path_on_host: pathOnHost,
+      is_root_device: opts.root,
+      is_read_only: opts.readOnly,
+      // "Unsafe" (the default) acks guest flushes without doing anything, so the last journal
+      // commit of a clean shutdown can be lost when the guest resets and Firecracker exits.
+      // Writeback makes a guest flush a real fsync; a box's writes must survive `kvbox stop`.
+      cache_type: "Writeback"
+    });
+  }
+  /**
+   * The host's control channel into the box: Firecracker listens on `udsPath`, a connection there
+   * followed by `CONNECT <port>\n` reaches whatever listens on that vsock port in the guest (kvbox-agent).
+   */
+  vsock(guestCid, udsPath) {
+    return this.call("PUT", "/vsock", { guest_cid: guestCid, uds_path: udsPath });
+  }
+  machineConfig(vcpuCount, memSizeMib) {
+    return this.call("PUT", "/machine-config", { vcpu_count: vcpuCount, mem_size_mib: memSizeMib, track_dirty_pages: true });
+  }
+  networkInterface(ifaceId, hostDevName, guestMac) {
+    return this.call("PUT", `/network-interfaces/${ifaceId}`, {
+      iface_id: ifaceId,
+      host_dev_name: hostDevName,
+      guest_mac: guestMac
+    });
+  }
+  start() {
+    return this.call("PUT", "/actions", { action_type: "InstanceStart" });
+  }
+  /** Ask the guest to shut down cleanly (systemd handles Ctrl+Alt+Del as poweroff on Firecracker). */
+  sendCtrlAltDel() {
+    return this.call("PUT", "/actions", { action_type: "SendCtrlAltDel" });
+  }
+  pause() {
+    return this.call("PATCH", "/vm", { state: "Paused" });
+  }
+  resume() {
+    return this.call("PATCH", "/vm", { state: "Resumed" });
+  }
+  /**
+   * Full: all of guest memory, dense (seconds for a 4 GB box). Diff: only pages dirtied since the last
+   * snapshot (or since boot), written sparse; needs dirty page tracking and resets its bitmap.
+   */
+  snapshotCreate(snapshotPath, memFilePath, type = "Full") {
+    return this.call("PUT", "/snapshot/create", {
+      snapshot_type: type,
+      snapshot_path: snapshotPath,
+      mem_file_path: memFilePath
+    });
+  }
+  /**
+   * Restore a snapshot into this (fresh) process. The memory file is mapped privately: the guest's
+   * writes never reach the snapshot. The vmstate carries the source box's tap and vsock paths; the
+   * overrides point them at this box's. Drive paths are not overridable here: the vmstate names the overlay relative to the box dir (spawnFirecracker).
+   */
+  snapshotLoad(opts) {
+    return this.call("PUT", "/snapshot/load", {
+      snapshot_path: opts.snapshotPath,
+      mem_backend: { backend_type: "File", backend_path: opts.memFilePath },
+      network_overrides: [{ iface_id: opts.tap.ifaceId, host_dev_name: opts.tap.hostDevName }],
+      vsock_override: { uds_path: opts.vsockPath },
+      track_dirty_pages: opts.trackDirtyPages,
+      resume_vm: opts.resume
+    });
+  }
+  info() {
+    return this.call("GET", "/");
+  }
+  async close() {
+    await this.agent.close();
+  }
+};
+
+// src/core/machines.ts
+var NAME_RE = /^[a-z0-9][a-z0-9-]{0,11}$/;
+var AUTO_PREFIX = "box";
+var GUEST_CID = 3;
+var OVERLAY_REL = "overlay.ext4";
+var idsInUse = (metas) => new Set(metas.map((m) => m.id));
+var sshPortsInUse = (metas) => metas.flatMap((m) => m.sshPort === void 0 ? [] : [m.sshPort]);
+var isCloudBox = (owner) => realmOf(owner) !== null;
+function sshProxy(meta) {
+  if (meta.sshPort === void 0 || meta.id === void 0) return void 0;
+  return { box: meta.id, boxIp: meta.ip, hostPort: meta.sshPort, guestPort: 22 };
+}
+async function openSshPort(meta, cfg) {
+  const proxy = sshProxy(meta);
+  if (proxy) await openProxy(proxy, cfg);
+}
+async function closeSshPort(meta, cfg) {
+  const proxy = sshProxy(meta);
+  if (!proxy) return;
+  await closeProxy(proxy, cfg).catch((err) => console.error(`warning: could not close port ${proxy.hostPort}: ${err.message}`));
+}
+async function newSshPort(existing) {
+  return pickSshPort(/* @__PURE__ */ new Set([...sshPortsInUse(existing), ...await listeningPorts()]));
+}
+function diskStats(disk) {
+  try {
+    const st = statSync(disk);
+    return { diskBytes: st.size, diskUsedBytes: st.blocks * 512 };
+  } catch {
+    return { diskBytes: 0, diskUsedBytes: 0 };
+  }
+}
+function diskGibOf(meta, p) {
+  try {
+    return Math.round(statSync(p.machine(meta.owner, meta.name).overlay).size / 1024 ** 3);
+  } catch {
+    return 0;
+  }
+}
+function recordState(meta, state, by, p, at = (/* @__PURE__ */ new Date()).toISOString()) {
+  try {
+    insertUsageEvent({ boxId: meta.id, 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 isHibernated(meta, p) {
+  return !pidAlive(meta.pid) && existsSync2(p.machine(meta.owner, meta.name).hibernateVmstate);
+}
+function statusOf(meta, p = paths()) {
+  if (pidAlive(meta.pid)) return meta.paused ? "standby" : "running";
+  return isHibernated(meta, p) ? "hibernated" : "stopped";
+}
+function stateMessage(ref, status) {
+  return `box ${shown(ref)} is ${status === "standby" ? "in standby" : status}`;
+}
+function toMachine(meta, p = paths()) {
+  const alive = pidAlive(meta.pid);
+  if (!alive && meta.pid !== null) {
+    try {
+      closeOpenRun(meta.id, (/* @__PURE__ */ new Date()).toISOString(), p);
+    } catch (err) {
+      console.error(`warning: usage ledger: ${err.message}`);
+    }
+  }
+  return {
+    id: meta.id,
+    name: meta.name,
+    owner: meta.owner,
+    ip: meta.ip,
+    mac: meta.mac,
+    pid: alive ? meta.pid : null,
+    vcpu: meta.vcpu,
+    memMib: meta.memMib,
+    ...diskStats(p.machine(meta.owner, meta.name).overlay),
+    base: meta.base,
+    createdAt: meta.createdAt,
+    source: meta.source,
+    status: statusOf(meta, p),
+    ...meta.sshPort === void 0 ? {} : { sshPort: meta.sshPort }
+  };
+}
+async function readAllMeta(p) {
+  const metas = [];
+  for (const ref of await listMachineRefs(p)) {
+    try {
+      metas.push(await readMachineMeta(ref, p));
+    } catch (err) {
+      console.error(`warning: skipping machines/${refKey(ref)}: ${err.message}`);
+    }
+  }
+  return metas;
+}
+async function listMachines(scope, p = paths()) {
+  return (await readAllMeta(p)).filter((m) => inScope(m.owner, scope)).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) {
+    if (!NAME_RE.test(requested)) {
+      throw new KvboxError(`invalid box name "${requested}": 1-12 chars, lowercase letters, digits and '-', starting with a letter or digit`);
+    }
+    if (taken.has(requested)) throw new KvboxError(`box ${requested} already exists`);
+    return requested;
+  }
+  for (let i = 1; ; i++) {
+    const candidate = `${AUTO_PREFIX}${i}`;
+    if (!taken.has(candidate)) return candidate;
+  }
+}
+var MAX_SSH_KEY_LINES = 8;
+var MAX_SSH_KEYS_B64 = 1500;
+function authorizedKeysLines(hostKey, extra) {
+  const lines = [hostKey.trim(), ...extra.map((l) => l.trim())];
+  if (lines.some((l) => l === "" || /[\r\n]/.test(l))) throw new KvboxError("sshKeys: every entry must be one non-empty authorized_keys line");
+  if (lines.length > MAX_SSH_KEY_LINES) {
+    throw new KvboxError(`a box takes at most ${MAX_SSH_KEY_LINES - 1} SSH keys on top of the host's own; ${extra.length} were given`);
+  }
+  return lines;
+}
+function authorizedKeysB64(hostKey, extra) {
+  const lines = authorizedKeysLines(hostKey, extra);
+  const b64 = Buffer.from(lines.join("\n") + "\n").toString("base64");
+  if (b64.length > MAX_SSH_KEYS_B64) {
+    throw new KvboxError(`the SSH keys for this box do not fit the kernel command line (${b64.length} bytes encoded, ${MAX_SSH_KEYS_B64} at most); use fewer or shorter keys`);
+  }
+  return b64;
+}
+function bootArgs(name, ip, cfg, pubkeyB64) {
+  const args = `console=ttyS0 reboot=k panic=1 init=/sbin/overlay-init kvbox.overlay=/dev/vdb ip=${ip}::${cfg.gateway}:255.255.255.0:${name}:eth0:off kvbox.name=${name} kvbox.sshkey=${pubkeyB64}`;
+  return process.arch === "arm64" ? `keep_bootcon ${args}` : args;
+}
+function baseVersionOf(file) {
+  const m = /^rootfs-(.+)\.ext4$/.exec(basename(file));
+  if (!m) throw new KvboxError(`base image ${file} is not versioned (expected assets/rootfs-<version>.ext4); run install-server.sh`);
+  return m[1];
+}
+async function currentBase(cfg, p) {
+  const file = await realpath(cfg.rootfs);
+  const version = baseVersionOf(file);
+  const expected = p.baseImage(version);
+  if (file !== expected) throw new KvboxError(`base image ${cfg.rootfs} points outside ${p.assets} (${file})`);
+  return { version, file };
+}
+function baseFileFor(meta, p) {
+  const file = p.baseImage(meta.base);
+  if (!existsSync2(file)) throw new KvboxError(`box ${meta.name} runs on base image ${meta.base}, which is gone from ${p.assets}`);
+  return file;
+}
+var overlayCapable = /* @__PURE__ */ new Map();
+async function assertOverlayCapable(baseFile, version) {
+  let ok = overlayCapable.get(baseFile);
+  if (ok === void 0) {
+    const { stdout } = await run(["debugfs", "-R", "stat /sbin/overlay-init", baseFile]);
+    ok = /Type:\s+regular/.test(stdout);
+    overlayCapable.set(baseFile, ok);
+  }
+  if (!ok) throw new KvboxError(`base image ${version} is not a kvbox base image (no /sbin/overlay-init); rerun install-server.sh`);
+}
+async function createOverlay(file, gib) {
+  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]);
+}
+async function waitFor(pred, timeoutMs, stepMs = 50) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (pred()) return true;
+    await sleep(stepMs);
+  }
+  return pred();
+}
+async function tailOf(file, lines = 5) {
+  try {
+    return (await readFile5(file, "utf8")).trim().split("\n").slice(-lines).join("\n");
+  } catch {
+    return "";
+  }
+}
+async function spawnFirecracker(ref, cfg, p) {
+  const m = p.machine(ref.owner, ref.name);
+  await rm2(m.sock, { force: true });
+  await rm2(m.vsock, { force: true });
+  const logFd = openSync2(m.log, "a");
+  let child;
+  try {
+    child = spawn(cfg.firecracker, ["--api-sock", m.sock, "--id", ref.name, "--level", "Error"], {
+      cwd: m.dir,
+      detached: true,
+      stdio: ["ignore", logFd, logFd]
+    });
+  } finally {
+    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)) {
+    killQuietly(pid);
+    throw new KvboxError(`firecracker did not open its API socket; last log lines:
+${await tailOf(m.log)}`);
+  }
+  return pid;
+}
+function killQuietly(pid) {
+  try {
+    process.kill(pid, "SIGKILL");
+  } catch {
+  }
+}
+async function launch(spec, tap, cfg, pubkeyB64, p) {
+  const m = p.machine(spec.owner, spec.name);
+  const baseFile = baseFileFor(spec, p);
+  const pid = await spawnFirecracker(spec, cfg, p);
+  try {
+    const fc = new FirecrackerClient(m.sock);
+    try {
+      await fc.bootSource(cfg.kernel, bootArgs(spec.name, spec.ip, cfg, pubkeyB64));
+      await fc.rootDrive(baseFile);
+      await fc.overlayDrive(OVERLAY_REL);
+      await fc.machineConfig(spec.vcpu, spec.memMib);
+      await fc.networkInterface("eth0", tap, spec.mac);
+      await fc.vsock(GUEST_CID, m.vsock);
+      await fc.start();
+    } finally {
+      await fc.close();
+    }
+    return pid;
+  } catch (err) {
+    killQuietly(pid);
+    throw err;
+  }
+}
+async function loadSnapshot(spec, image, tap, cfg, p) {
+  const m = p.machine(spec.owner, spec.name);
+  const pid = await spawnFirecracker(spec, cfg, p);
+  try {
+    const fc = new FirecrackerClient(m.sock);
+    try {
+      await fc.snapshotLoad({
+        snapshotPath: image.vmstate,
+        memFilePath: image.mem,
+        tap: { ifaceId: "eth0", hostDevName: tap },
+        vsockPath: m.vsock,
+        trackDirtyPages: true,
+        resume: false
+      });
+    } finally {
+      await fc.close();
+    }
+    return pid;
+  } catch (err) {
+    killQuietly(pid);
+    throw err;
+  }
+}
+async function currentBaseVersion(p = paths()) {
+  return (await currentBase(await loadConfig(p), p)).version;
+}
+async function readHostPubkey(p) {
+  try {
+    return (await readFile5(`${p.sshKey}.pub`, "utf8")).trim();
+  } 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`);
+  }
+}
+async function createMachine(req, owner, p = paths()) {
+  const cfg = await loadConfig(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 cloud = isCloudBox(owner);
+  const sshKeys = cloud && req.sshKeys !== void 0 && req.sshKeys.length > 0 ? req.sshKeys : void 0;
+  const keysB64 = authorizedKeysB64(await readHostPubkey(p), sshKeys ?? []);
+  const existing = await readAllMeta(p);
+  const name = pickName(req.name, new Set(existing.filter((m2) => m2.owner === owner).map((m2) => m2.name)));
+  const id = newBoxId(idsInUse(existing));
+  const ip = nextFreeIp(cfg.subnet, [...existing.map((m2) => m2.ip), cfg.gateway]);
+  const mac = macFor(ip);
+  const sshPort = cloud ? await newSshPort(existing) : void 0;
+  const m = p.machine(owner, name);
+  const base = await currentBase(cfg, p);
+  await assertOverlayCapable(base.file, base.version);
+  await ensureHostNetwork(cfg);
+  await mkdir4(m.dir, { recursive: true, mode: 448 });
+  let tapCreated = false;
+  let pid;
+  try {
+    await createOverlay(m.overlay, size.diskGib);
+    const tap = await createTap(id, cfg);
+    tapCreated = true;
+    const spec = { id, name, owner, ip, mac, vcpu: size.vcpu, memMib: size.memMib, base: base.version, sshKeys, sshPort };
+    pid = await launch(spec, tap, cfg, keysB64, p);
+    await openSshPort(spec, cfg);
+    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 (pid !== void 0) killQuietly(pid);
+    await closeSshPort({ id, ip, sshPort }, cfg);
+    if (tapCreated) await deleteTap(id, cfg).catch(() => void 0);
+    await rm2(m.dir, { recursive: true, force: true });
+    throw err;
+  }
+}
+async function readSnap(ref, p) {
+  try {
+    return await readSnapshotMeta(ref, p);
+  } catch (err) {
+    if (err.code === "ENOENT") throw new NotFoundError(`snapshot ${shown(ref)}`);
+    throw err;
+  }
+}
+function prefixLenOf(subnet) {
+  return Number(subnet.split("/")[1]);
+}
+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 (${shown(from)}: ${snap.vcpu} vCPU, ${snap.memMib} MiB)`);
+  }
+  assertAssets(cfg);
+  if (!existsSync2(p.baseImage(snap.base))) {
+    throw new KvboxError(`snapshot ${shown(from)} stacks on base image ${snap.base}, which is gone from ${p.assets}`);
+  }
+  await assertRoomFor(snap.vcpu, snap.memMib, req.force ?? false, p);
+  const cloud = isCloudBox(owner);
+  const sshKeys = cloud && req.sshKeys !== void 0 && req.sshKeys.length > 0 ? req.sshKeys : void 0;
+  authorizedKeysB64(await readHostPubkey(p), sshKeys ?? []);
+  const existing = await readAllMeta(p);
+  const name = pickName(req.name, new Set(existing.filter((m2) => m2.owner === owner).map((m2) => m2.name)));
+  const id = newBoxId(idsInUse(existing));
+  const ip = nextFreeIp(cfg.subnet, [...existing.map((m2) => m2.ip), cfg.gateway]);
+  const mac = macFor(ip);
+  const sshPort = cloud ? await newSshPort(existing) : void 0;
+  const m = p.machine(owner, name);
+  const s = p.snapshot(from.owner, from.name);
+  await ensureHostNetwork(cfg);
+  await mkdir4(m.dir, { recursive: true, mode: 448 });
+  let tapCreated = false;
+  let pid;
+  try {
+    await run(["cp", "--sparse=always", "--reflink=auto", s.overlay, m.overlay]);
+    await link(s.mem, m.memBase);
+    const tap = await createTap(id, cfg, { detached: true });
+    tapCreated = true;
+    const spec = { id, name, owner, ip, mac, vcpu: snap.vcpu, memMib: snap.memMib, base: snap.base, sshKeys, sshPort };
+    pid = await loadSnapshot(spec, { vmstate: s.vmstate, mem: s.mem, label: shown(from) }, tap, cfg, p);
+    await resumeVm(m.sock);
+    await introduce(spec, m.vsock, cfg, {
+      silent: `nothing answered on the restored box's control channel for 3 s; the restored box was discarded, try again`,
+      noAnswer: "the restored box was discarded. kvbox-agent inside it took the request but gave no answer; try again, and if it keeps happening look at the box's journal (kvbox exec <box> -- sudo journalctl -u kvbox-agent) on a box started from the same snapshot."
+    });
+    const stale = await pushAuthorizedKeys({ owner, name, sshKeys }, m.vsock, p);
+    await attachTap(id, cfg);
+    await openSshPort(spec, cfg);
+    const meta = { ...spec, pid, createdAt: (/* @__PURE__ */ new Date()).toISOString(), source: `snapshot:${refKey(from)}`, memSnapshots: 1, sshKeysStale: stale ? true : void 0 };
+    await writeMachineMeta(meta, p);
+    recordState(meta, "running", "new", p, meta.createdAt);
+    return toMachine(meta, p);
+  } catch (err) {
+    if (pid !== void 0) killQuietly(pid);
+    await closeSshPort({ id, ip, sshPort }, cfg);
+    if (tapCreated) await deleteTap(id, cfg).catch(() => void 0);
+    await rm2(m.dir, { recursive: true, force: true });
+    throw err;
+  }
+}
+var AGENT_REPLY_MS = 2e4;
+async function introduce(spec, vsock, cfg, failure) {
+  const id = { name: spec.name, ip: spec.ip, prefixLen: prefixLenOf(cfg.subnet), gateway: cfg.gateway, mac: spec.mac, time: Math.floor(Date.now() / 1e3) };
+  const deadline = Date.now() + 3e3;
+  for (; ; ) {
+    try {
+      await setIdentity(vsock, id, AGENT_REPLY_MS);
+      return;
+    } catch (err) {
+      const msg = err.message;
+      const transient = /unreachable|refused|before the guest accepted/.test(msg);
+      if (transient && Date.now() < deadline) {
+        await sleep(100);
+        continue;
+      }
+      if (transient) throw new KvboxError(`${msg}
+  ${failure.silent}`);
+      throw new KvboxError(`${msg}
+  ${failure.noAnswer}`);
+    }
+  }
+}
+async function pushAuthorizedKeys(box, vsock, p) {
+  try {
+    await setAuthorizedKeys(vsock, authorizedKeysLines(await readHostPubkey(p), box.sshKeys ?? []), AGENT_REPLY_MS);
+    return void 0;
+  } catch (err) {
+    const why = isUnknownOp(err) ? `its image predates base v0.6.0, whose kvbox-agent can replace authorized_keys (kvbox vm update ${shown(box)} moves it onto the current base)` : err.message;
+    console.error(`warning: box ${shown(box)} keeps the authorized_keys it was frozen with: ${why}`);
+    return why;
+  }
+}
+async function resumeVm(sock) {
+  const fc = new FirecrackerClient(sock);
+  try {
+    await fc.resume();
+  } finally {
+    await fc.close();
+  }
+}
+async function shutdown(meta, cfg, p, graceMs) {
+  const pid = meta.pid;
+  if (pidAlive(pid)) {
+    const fc = new FirecrackerClient(p.machine(meta.owner, meta.name).sock);
+    try {
+      if (meta.paused) await fc.resume();
+      await fc.sendCtrlAltDel();
+    } catch {
+      process.kill(pid, "SIGTERM");
+    } finally {
+      await fc.close();
+    }
+    await waitDead(pid, graceMs);
+  }
+  await cleanupProcess(meta, cfg, p);
+}
+async function waitDead(pid, graceMs) {
+  if (!await waitFor(() => !pidAlive(pid), graceMs, 100)) {
+    killQuietly(pid);
+    await waitFor(() => !pidAlive(pid), 1e3, 50);
+  }
+}
+async function cleanupProcess(meta, cfg, p) {
+  await closeSshPort(meta, cfg);
+  await deleteTap(meta.id, cfg);
+  const m = p.machine(meta.owner, meta.name);
+  await rm2(m.sock, { force: true });
+  await rm2(m.vsock, { force: true });
+}
+async function stopMachine(ref, p = paths()) {
+  const meta = await readMeta(ref, p);
+  const cfg = await loadConfig(p);
+  const m = p.machine(ref.owner, ref.name);
+  if (!pidAlive(meta.pid) && !isHibernated(meta, p)) throw new KvboxError(`box ${shown(ref)} is already stopped`);
+  await shutdown(meta, cfg, p, 1e4);
+  await rm2(m.hibernateDir, { recursive: true, force: true });
+  await rm2(m.memBase, { force: true });
+  const stopped = { ...meta, pid: null, memSnapshots: void 0, paused: void 0 };
+  await writeMachineMeta(stopped, p);
+  recordState(stopped, "stopped", "stop", p);
+  return toMachine(stopped, 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 ${shown(ref)} is already ${meta.paused ? "up, in standby (kvbox resume " + shown(ref) + ")" : "running"}`);
+  if (isHibernated(meta, p)) {
+    throw new KvboxError(`${stateMessage(ref, "hibernated")}: kvbox wake ${shown(ref)} continues where it left off; to boot fresh instead, kvbox stop ${shown(ref)} first (discards its memory)`);
+  }
+  assertAssets(cfg);
+  const keysB64 = authorizedKeysB64(await readHostPubkey(p), meta.sshKeys ?? []);
+  await ensureHostNetwork(cfg);
+  const tap = await createTap(meta.id, cfg);
+  let pid;
+  try {
+    pid = await launch(meta, tap, cfg, keysB64, p);
+    await openSshPort(meta, cfg);
+    const started = { ...meta, pid, sshKeysStale: void 0 };
+    await writeMachineMeta(started, p);
+    recordState(started, "running", "start", p);
+    return toMachine(started, p);
+  } catch (err) {
+    if (pid !== void 0) killQuietly(pid);
+    await closeSshPort(meta, cfg);
+    await deleteTap(meta.id, cfg).catch(() => void 0);
+    throw err;
+  }
+}
+async function setSshKeys(ref, sshKeys, p = paths()) {
+  const meta = await readMeta(ref, p);
+  if (!isCloudBox(meta.owner)) throw new KvboxError(`box ${shown(ref)} is local: it trusts this host's key, there are no authorized_keys lines to replace`);
+  if (sshKeys.length === 0) throw new KvboxError("sshKeys: at least one authorized_keys line (the box would keep only the host's own key)");
+  authorizedKeysB64(await readHostPubkey(p), sshKeys);
+  const { meta: updated, applied } = await applySshKeys(meta, sshKeys, p);
+  return { machine: toMachine(updated, p), applied };
+}
+async function applySshKeys(meta, sshKeys, p) {
+  const status = statusOf(meta, p);
+  let updated = { ...meta, sshKeys: [...sshKeys], sshKeysStale: status === "stopped" ? void 0 : true };
+  let applied = status === "stopped" ? "start" : status === "standby" ? "resume" : status === "hibernated" ? "wake" : "later";
+  let why;
+  if (status === "running") {
+    why = await pushAuthorizedKeys(updated, p.machine(meta.owner, meta.name).vsock, p);
+    if (why === void 0) {
+      updated = { ...updated, sshKeysStale: void 0 };
+      applied = "now";
+    }
+  }
+  await writeMachineMeta(updated, p);
+  return why === void 0 ? { meta: updated, applied } : { meta: updated, applied, why };
+}
+async function trustCa(publicKeyText, p = paths()) {
+  const publicKey = parseSshPublicKey(publicKeyText);
+  const report = { publicKey, fingerprint: sshKeyFingerprint(publicKey), updated: [], pending: [], failed: [], local: 0 };
+  const hostKey = await readHostPubkey(p);
+  for (const meta of await readAllMeta(p)) {
+    if (!isCloudBox(meta.owner)) {
+      report.local++;
+      continue;
+    }
+    const box = refKey(meta);
+    try {
+      const sshKeys = [...(meta.sshKeys ?? []).filter((l) => !isCaLine(l)), caLineFor(meta.owner, publicKey)];
+      authorizedKeysLines(hostKey, sshKeys);
+      const { applied, why } = await applySshKeys(meta, sshKeys, p);
+      if (applied === "now") report.updated.push(box);
+      else report.pending.push(why === void 0 ? { box, when: applied } : { box, when: applied, why });
+    } catch (err) {
+      report.failed.push({ box, error: err.message });
+    }
+  }
+  return report;
+}
+async function pauseMachine(ref, p = paths()) {
+  const meta = await readMeta(ref, p);
+  const status = statusOf(meta, p);
+  if (status === "standby") throw new KvboxError(`${stateMessage(ref, status)} already`);
+  if (status === "hibernated") throw new KvboxError(`${stateMessage(ref, status)}; kvbox wake ${shown(ref)} brings it back`);
+  if (status === "stopped") throw new KvboxError(`${stateMessage(ref, status)}; only a running box can be paused`);
+  const fc = new FirecrackerClient(p.machine(ref.owner, ref.name).sock);
+  try {
+    await fc.pause();
+  } finally {
+    await fc.close();
+  }
+  const paused = { ...meta, paused: true };
+  await writeMachineMeta(paused, p);
+  recordState(paused, "standby", "pause", p);
+  return toMachine(paused, p);
+}
+async function resumeMachine(ref, p = paths()) {
+  const meta = await readMeta(ref, p);
+  const status = statusOf(meta, p);
+  if (status === "running") throw new KvboxError(`${stateMessage(ref, status)} already`);
+  if (status === "hibernated") throw new KvboxError(`${stateMessage(ref, status)}, not in standby; kvbox wake ${shown(ref)} brings it back`);
+  if (status === "stopped") throw new KvboxError(`${stateMessage(ref, status)}, not in standby; kvbox start ${shown(ref)} boots it`);
+  const m = p.machine(ref.owner, ref.name);
+  await resumeVm(m.sock);
+  const stale = meta.sshKeysStale ? await pushAuthorizedKeys(meta, m.vsock, p) : void 0;
+  const running = { ...meta, paused: void 0, sshKeysStale: stale ? true : void 0 };
+  await writeMachineMeta(running, p);
+  recordState(running, "running", "resume", p);
+  return toMachine(running, p);
+}
+async function hibernateMachine(ref, p = paths()) {
+  const meta = await readMeta(ref, p);
+  const cfg = await loadConfig(p);
+  const status = statusOf(meta, p);
+  if (status === "hibernated") throw new KvboxError(`${stateMessage(ref, status)} already`);
+  if (status === "stopped") throw new KvboxError(`${stateMessage(ref, status)}; only a running box can be hibernated (there is no memory to keep)`);
+  const m = p.machine(ref.owner, ref.name);
+  await rm2(m.hibernateDir, { recursive: true, force: true });
+  await mkdir4(m.hibernateDir, { recursive: true, mode: 448 });
+  const fc = new FirecrackerClient(m.sock);
+  try {
+    try {
+      await fc.pause();
+      await fc.snapshotCreate(m.hibernateVmstate, m.hibernateMem, "Full");
+    } catch (err) {
+      await rm2(m.hibernateDir, { recursive: true, force: true });
+      if (!meta.paused) await fc.resume().catch(() => void 0);
+      throw err;
+    }
+  } finally {
+    await fc.close();
+  }
+  killQuietly(meta.pid);
+  await waitFor(() => !pidAlive(meta.pid), 5e3, 50);
+  await cleanupProcess(meta, cfg, p);
+  await run(["fallocate", "--dig-holes", m.hibernateMem]);
+  await rm2(m.memBase, { force: true });
+  const hibernated = { ...meta, pid: null, memSnapshots: void 0, paused: void 0 };
+  await writeMachineMeta(hibernated, p);
+  recordState(hibernated, "hibernated", "hibernate", p);
+  return toMachine(hibernated, p);
+}
+async function wakeMachine(ref, p = paths()) {
+  const meta = await readMeta(ref, p);
+  const cfg = await loadConfig(p);
+  const status = statusOf(meta, p);
+  if (status === "running" || status === "standby") throw new KvboxError(`${stateMessage(ref, status)}, not hibernated`);
+  if (status === "stopped") throw new KvboxError(`${stateMessage(ref, status)}, not hibernated; kvbox start ${shown(ref)} boots it`);
+  assertAssets(cfg);
+  if (!existsSync2(p.baseImage(meta.base))) {
+    throw new KvboxError(`box ${shown(ref)} stacks on base image ${meta.base}, which is gone from ${p.assets}`);
+  }
+  const m = p.machine(ref.owner, ref.name);
+  await ensureHostNetwork(cfg);
+  const tap = await createTap(meta.id, cfg, { detached: true });
+  let pid;
+  let stale;
+  try {
+    const spec = { id: meta.id, name: meta.name, owner: meta.owner, ip: meta.ip, mac: meta.mac, vcpu: meta.vcpu, memMib: meta.memMib, base: meta.base };
+    pid = await loadSnapshot(spec, { vmstate: m.hibernateVmstate, mem: m.hibernateMem, label: `box ${shown(ref)}'s memory image` }, tap, cfg, p);
+    await resumeVm(m.sock);
+    await introduce(spec, m.vsock, cfg, {
+      silent: `nothing answered on the box's control channel for 3 s; it stays hibernated, try kvbox wake ${shown(ref)} again`,
+      noAnswer: `the box stays hibernated. kvbox-agent inside it took the request but gave no answer; try kvbox wake ${shown(ref)} again`
+    });
+    stale = await pushAuthorizedKeys(meta, m.vsock, p);
+    await attachTap(meta.id, cfg);
+    await openSshPort(meta, cfg);
+  } catch (err) {
+    if (pid !== void 0) killQuietly(pid);
+    await closeSshPort(meta, cfg);
+    await deleteTap(meta.id, cfg).catch(() => void 0);
+    throw err;
+  }
+  await rm2(m.memBase, { force: true });
+  await link(m.hibernateMem, m.memBase);
+  await rm2(m.hibernateDir, { recursive: true, force: true });
+  const running = { ...meta, pid, memSnapshots: 1, paused: void 0, sshKeysStale: stale ? true : void 0 };
+  await writeMachineMeta(running, p);
+  recordState(running, "running", "wake", p);
+  return toMachine(running, p);
+}
+async function applyAtNextBoot(meta, changes, by, cfg, p, whileStopped) {
+  const wasRunning = pidAlive(meta.pid);
+  if (wasRunning) {
+    await shutdown(meta, cfg, p, 1e4);
+    await rm2(p.machine(meta.owner, meta.name).memBase, { force: true });
+  }
+  const updated = { ...meta, ...changes, pid: null, memSnapshots: void 0, paused: void 0 };
+  await writeMachineMeta(updated, p);
+  if (whileStopped) await whileStopped();
+  recordState(updated, "stopped", by, p);
+  return wasRunning ? startMachine(meta, p) : toMachine(updated, p);
+}
+function assertNotHibernated(meta, p) {
+  if (isHibernated(meta, p)) {
+    throw new KvboxError(`${stateMessage(meta, "hibernated")}; its memory image was made with its current shape and base: kvbox wake ${shown(meta)} first`);
+  }
+}
+async function updateMachine(ref, p = paths()) {
+  const meta = await readMeta(ref, p);
+  const cfg = await loadConfig(p);
+  assertNotHibernated(meta, p);
+  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 }, "update", cfg, p);
+}
+async function rescaleMachine(ref, req, p = paths()) {
+  const meta = await readMeta(ref, p);
+  const cfg = await loadConfig(p);
+  assertNotHibernated(meta, p);
+  const disk = p.machine(ref.owner, ref.name).overlay;
+  const currentDiskGib = Math.round(statSync(disk).size / 1024 ** 3);
+  const preset = req.size !== void 0 && isSizeName(req.size) ? SIZES[req.size] : void 0;
+  const target = {
+    vcpu: req.vcpu ?? preset?.vcpu ?? meta.vcpu,
+    memMib: req.memMib ?? preset?.memMib ?? meta.memMib,
+    diskGib: req.diskGib ?? preset?.diskGib ?? currentDiskGib
+  };
+  if (target.diskGib < currentDiskGib) {
+    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, "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(ref, p) {
+  try {
+    return await readMachineMeta(ref, p);
+  } catch (err) {
+    if (err.code === "ENOENT") throw new NotFoundError(`box ${shown(ref)}`);
+    throw err;
+  }
+}
+async function destroyMachine(ref, p = paths()) {
+  const meta = await readMeta(ref, p);
+  const cfg = await loadConfig(p);
+  await shutdown(meta, cfg, p, 2e3);
+  recordState(meta, "stopped", "rm", p);
+  await rm2(p.machine(ref.owner, ref.name).dir, { recursive: true, force: true });
+}
+
+// src/routes/capacity.ts
+import { Hono } from "hono";
+function capacityRoutes() {
+  const r = new Hono();
+  r.get("/", async (c) => c.json(await capacity()));
+  return r;
+}
+
+// src/routes/machines.ts
+import { Hono as Hono2 } from "hono";
+
+// 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, standby: 0, hibernated: 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;
+    if (e.state === "running" || e.state === "standby") ramGibHours += h * e.memMib / 1024;
+    diskGibHours += h * e.diskGib;
+  });
+  const totals = {
+    seconds: {
+      running: Math.round(ms.running / 1e3),
+      standby: Math.round(ms.standby / 1e3),
+      hibernated: Math.round(ms.hibernated / 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;
+}
+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 events = usageEventsFor(box.id, 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 }) };
+}
+
+// src/routes/machines.ts
+function machineRoutes() {
+  const r = new Hono2();
+  r.get("/", async (c) => c.json(await listMachines(c.get("listScope"))));
+  r.post("/", async (c) => {
+    const body = CreateMachineRequest.parse(await c.req.json().catch(() => ({})));
+    return c.json(await createMachine(body, c.get("owner")), 201);
+  });
+  r.post("/:name/stop", async (c) => c.json(await stopMachine(parseRef(c.req.param("name"), c.get("owner")))));
+  r.post("/:name/start", async (c) => c.json(await startMachine(parseRef(c.req.param("name"), c.get("owner")))));
+  r.post("/:name/pause", async (c) => c.json(await pauseMachine(parseRef(c.req.param("name"), c.get("owner")))));
+  r.post("/:name/resume", async (c) => c.json(await resumeMachine(parseRef(c.req.param("name"), c.get("owner")))));
+  r.post("/:name/hibernate", async (c) => c.json(await hibernateMachine(parseRef(c.req.param("name"), c.get("owner")))));
+  r.post("/:name/wake", async (c) => c.json(await wakeMachine(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(parseRef(c.req.param("name"), c.get("owner")), body));
+  });
+  r.post("/:name/ssh-keys", async (c) => {
+    const body = SetSshKeysRequest.safeParse(await c.req.json().catch(() => ({})));
+    if (!body.success) throw new KvboxError("sshKeys: expected a list of authorized_keys lines");
+    const { machine, applied } = await setSshKeys(parseRef(c.req.param("name"), c.get("owner")), body.data.sshKeys);
+    return c.json({ ...machine, sshKeysApplied: applied });
+  });
+  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(parseRef(c.req.param("name"), c.get("owner")));
+    return c.body(null, 204);
+  });
+  return r;
+}
+
+// src/routes/snapshots.ts
+import { Hono as Hono3 } from "hono";
+
+// src/core/snapshots.ts
+import { existsSync as existsSync3 } from "node:fs";
+import { link as link2, mkdir as mkdir5, readdir as readdir2, rename as rename2, rm as rm3, stat as stat2 } from "node:fs/promises";
+var NAME_RE2 = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+function toSnapshot(meta) {
+  return {
+    name: meta.name,
+    owner: meta.owner,
+    source: meta.source,
+    base: meta.base,
+    vcpu: meta.vcpu,
+    memMib: meta.memMib,
+    sizeBytes: meta.sizeBytes,
+    createdAt: meta.createdAt
+  };
+}
+async function listSnapshots(scope, p = paths()) {
+  const out = [];
+  for (const ref of await listSnapshotRefs(p)) {
+    if (!inScope(ref.owner, scope)) continue;
+    try {
+      out.push(toSnapshot(await readSnapshotMeta(ref, p)));
+    } catch (err) {
+      console.error(`warning: skipping snapshots/${refKey(ref)}: ${err.message}`);
+    }
+  }
+  return out;
+}
+async function usedBytes(dir) {
+  let total = 0;
+  for (const entry of await readdir2(dir)) {
+    total += (await stat2(`${dir}/${entry}`)).blocks * 512;
+  }
+  return total;
+}
+async function readBox(ref, p) {
+  try {
+    return await readMachineMeta(ref, p);
+  } catch (err) {
+    if (err.code === "ENOENT") throw new NotFoundError(`box ${shown(ref)}`);
+    throw err;
+  }
+}
+async function saveSnapshot(req, owner, p = paths()) {
+  if (!NAME_RE2.test(req.name)) {
+    throw new KvboxError(`invalid snapshot name "${req.name}": 1-64 chars, lowercase letters, digits, '.', '_' and '-', starting with a letter or digit`);
+  }
+  const box = await readBox(parseRef(req.box, owner), p);
+  if (!pidAlive(box.pid)) {
+    if (existsSync3(p.machine(box.owner, box.name).hibernateVmstate)) {
+      throw new KvboxError(`box ${req.box} is hibernated; a snapshot freezes a running box (kvbox wake ${req.box} first)`);
+    }
+    throw new KvboxError(`box ${req.box} is not running; a snapshot freezes a running box (kvbox start ${req.box} first)`);
+  }
+  const s = p.snapshot(owner, req.name);
+  if (existsSync3(s.dir)) throw new KvboxError(`snapshot ${req.name} already exists`);
+  const cfg = await loadConfig(p);
+  const m = p.machine(box.owner, box.name);
+  await mkdir5(s.dir, { recursive: true, mode: 448 });
+  const fc = new FirecrackerClient(m.sock);
+  let lineageTouched = false;
+  try {
+    const since = box.memSnapshots ?? 0;
+    const mode = since === 0 || existsSync3(m.memBase) ? "Diff" : "Full";
+    let failure;
+    await fc.pause();
+    try {
+      await fc.snapshotCreate(s.vmstate, s.mem, mode);
+      lineageTouched = true;
+      await run(["cp", "--sparse=always", "--reflink=auto", m.overlay, s.overlay]);
+    } catch (err) {
+      failure = err;
+    } finally {
+      if (!box.paused) await fc.resume();
+    }
+    if (lineageTouched) {
+      await writeMachineMeta({ ...box, memSnapshots: since + 1 }, p);
+    }
+    if (failure !== void 0) throw failure;
+    if (mode === "Full") {
+      await run(["fallocate", "--dig-holes", s.mem]);
+    } else if (since > 0) {
+      await mergeOntoPrevious(m.memBase, s.mem, cfg.snapshotEditor ?? p.snapshotEditor);
+    }
+    await rm3(m.memBase, { force: true });
+    await link2(s.mem, m.memBase);
+    const meta = {
+      name: req.name,
+      owner,
+      source: refKey(box),
+      base: box.base,
+      vcpu: box.vcpu,
+      memMib: box.memMib,
+      sizeBytes: await usedBytes(s.dir),
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await writeSnapshotMeta(meta, p);
+    return toSnapshot(meta);
+  } catch (err) {
+    if (lineageTouched) await rm3(m.memBase, { force: true }).catch(() => void 0);
+    await rm3(s.dir, { recursive: true, force: true });
+    throw err;
+  } finally {
+    await fc.close();
+  }
+}
+async function mergeOntoPrevious(previous, diffFile, editor) {
+  if (!existsSync3(editor)) throw new KvboxError(`snapshot-editor missing at ${editor}; rerun install-server.sh`);
+  const merged = `${diffFile}.merged`;
+  await run(["cp", "--sparse=always", "--reflink=auto", previous, merged]);
+  await run([editor, "edit-memory", "rebase", "--memory-path", merged, "--diff-path", diffFile]);
+  await rename2(merged, diffFile);
+}
+async function deleteSnapshot(ref, p = paths()) {
+  const dir = p.snapshot(ref.owner, ref.name).dir;
+  if (!existsSync3(dir)) throw new NotFoundError(`snapshot ${shown(ref)}`);
+  await rm3(dir, { recursive: true, force: true });
+}
+
+// src/routes/snapshots.ts
+function snapshotRoutes() {
+  const r = new Hono3();
+  r.get("/", async (c) => c.json(await listSnapshots(c.get("listScope"))));
+  r.post("/", async (c) => {
+    const body = CreateSnapshotRequest.parse(await c.req.json());
+    return c.json(await saveSnapshot(body, c.get("owner")), 201);
+  });
+  r.delete("/:name", async (c) => {
+    await deleteSnapshot(parseRef(c.req.param("name"), c.get("owner")));
+    return c.body(null, 204);
+  });
+  return r;
+}
+
+// src/routes/ssh.ts
+import { Hono as Hono4 } from "hono";
+function sshRoutes(opts = {}) {
+  const r = new Hono4();
+  if (opts.controlPlane) {
+    r.all("/*", (c) => c.json({ error: "trusting a CA is done on the host itself (kvbox server trust-ca there); the control plane cannot ask a host to" }, 403));
+    return r;
+  }
+  r.get("/cloud-ca", async (c) => c.json(await fetchCloudCa()));
+  r.post("/trust-ca", async (c) => {
+    const body = TrustCaRequestSchema.safeParse(await c.req.json().catch(() => ({})));
+    if (!body.success) throw new KvboxError("trust-ca: expected the CA public key as publicKey");
+    return c.json(await trustCa(body.data.publicKey));
+  });
+  return r;
+}
+
+// src/app.ts
+function createApp(opts = {}) {
+  const app = new Hono5();
+  app.use(resolveCaller(opts));
+  app.get("/health", async (c) => {
+    const cfg = await loadConfig();
+    const cp = cfg.controlPlane;
+    return c.json({
+      ok: true,
+      version: VERSION,
+      pid: process.pid,
+      base: await currentBaseVersion().catch(() => null),
+      owner: cfg.owner,
+      controlPlane: cp ? { name: cp.name, url: cp.url, hostUrl: `https://${cp.advertise}:${cp.port}` } : null,
+      relay: cfg.relay ? { name: cfg.relay.name, publicIp: cfg.relay.publicIp, endpoint: cfg.relay.endpoint } : null
+    });
+  });
+  app.route("/machines", machineRoutes());
+  app.route("/snapshots", snapshotRoutes());
+  app.route("/capacity", capacityRoutes());
+  app.route("/ssh", sshRoutes(opts));
+  app.notFound((c) => c.json({ error: `no route: ${c.req.method} ${c.req.path}` }, 404));
+  app.onError((err, c) => {
+    if (err instanceof NotFoundError) return c.json({ error: err.message }, 404);
+    if (err instanceof KvboxError) {
+      return c.json({ error: err.message }, err.exitCode === 2 ? 501 : 400);
+    }
+    console.error(err);
+    return c.json({ error: err.message }, 500);
+  });
+  return app;
+}
+
+// src/listen.ts
+async function listen(opts = {}) {
+  const p = await ensureLayout(paths());
+  const cfg = await loadConfig(p);
+  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`);
+  }
+  await rm4(socketPath, { force: true });
+  const server = createAdaptorServer({ fetch: createApp().fetch });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(socketPath, () => resolve());
+  });
+  await writeFile5(p.serverPid, `${process.pid}
+`);
+  let https;
+  let httpsServer;
+  const cp = cfg.controlPlane;
+  if (cp) {
+    const [key, cert] = await Promise.all([readFile6(p.tlsKey), readFile6(p.tlsCert)]).catch((err) => {
+      throw new KvboxError(`joined ${cp.name} but the host's certificate is missing (${err.message}); run kvbox-server leave, then join again`);
+    });
+    httpsServer = createAdaptorServer({
+      fetch: createApp({ controlPlane: { name: cp.name, secret: cp.secret } }).fetch,
+      createServer: createHttpsServer,
+      serverOptions: { key, cert }
+    });
+    const port = opts.httpsPort ?? cp.port;
+    await new Promise((resolve, reject) => {
+      httpsServer.once("error", reject);
+      httpsServer.listen(port, "0.0.0.0", () => resolve());
+    }).catch(async (err) => {
+      server.close();
+      await rm4(socketPath, { force: true });
+      await rm4(p.serverPid, { force: true });
+      throw new KvboxError(`cannot listen on port ${port} for ${cp.name} (${err.message})`);
+    });
+    const bound = httpsServer.address().port;
+    https = { port: bound, url: `https://${cp.advertise}:${bound}` };
+  }
+  const close = async () => {
+    await Promise.all([
+      new Promise((resolve) => server.close(() => resolve())),
+      httpsServer ? new Promise((resolve) => httpsServer.close(() => resolve())) : void 0
+    ]);
+    await rm4(socketPath, { force: true });
+    await rm4(p.serverPid, { force: true });
+  };
+  const shutdown2 = async () => {
+    server.close();
+    httpsServer?.close();
+    await rm4(socketPath, { force: true });
+    await rm4(p.serverPid, { force: true });
+    process.exit(0);
+  };
+  process.once("SIGINT", () => void shutdown2());
+  process.once("SIGTERM", () => void shutdown2());
+  return https ? { socketPath, server, https, close } : { socketPath, server, close };
+}
+
+// src/index.ts
+var program = new Command("kvbox-server").description("kvbox host daemon: owns Firecracker and ~/.kvbox, serves the kvbox API").version(VERSION, "-v, --version").showHelpAfterError();
+program.command("start", { isDefault: true }).description("serve the API on the local Unix socket (foreground)").option("--socket <path>", "socket to listen on (default: $KVBOX_HOME/server.sock)").action(async (opts) => {
+  await requireKvm();
+  const { socketPath, https } = await listen(opts.socket ? { socketPath: opts.socket } : {});
+  console.log(`kvbox-server ${VERSION} listening on ${socketPath} (pid ${process.pid})`);
+  if (https) {
+    const cfg = await loadConfig(paths());
+    console.log(`control plane ${cfg.controlPlane?.name}: answering on ${https.url}`);
+  }
+  try {
+    const cfg = await loadConfig(paths());
+    const state = await ensureHostNetwork(cfg);
+    console.log(`host network: bridge ${cfg.bridge} ${state}`);
+  } catch (err) {
+    console.error(`warning: host network not ready (${err.message}); run: kvbox-server net up`);
+  }
+});
+program.command("join <control-plane-url>").description("register this host with a control plane (needs a one-time token minted there); it answers the control plane from its next start").requiredOption("--token <token>", "one-time join token from the control plane").option("--advertise <host-or-ip>", "address the control plane reaches this host at (default: this host's default-route address)").option("--name <name>", "how the control plane lists this host (default: hostname)").action(async (url, opts) => {
+  const joined = await joinControlPlane({ url, ...opts }, paths());
+  console.log(`joined ${joined.controlPlane} as host ${joined.hostName}`);
+  console.log(`it answers the control plane on ${joined.hostUrl} once its server restarts`);
+  console.log(`make sure port ${new URL(joined.hostUrl).port} is reachable from the control plane`);
+});
+program.command("leave").description("forget the control plane this host joined; the HTTPS port closes at the next start").action(async () => {
+  const left = await leaveControlPlane(paths());
+  console.log(`left ${left.controlPlane}; the HTTPS port closes once its server restarts`);
+  if (!left.told) console.log(`(the control plane could not be told; remove this host there)`);
+});
+program.command("relay <join-string>").description("reach the internet through a relay (paste what `kvbox-relay add` printed there); `off` takes the tunnel down").action(async (joinString) => {
+  if (joinString === "off") {
+    const relay2 = await dropRelay(paths());
+    console.log(`tunnel to relay ${relay2.name} is down; this host no longer answers at ${relay2.publicIp}`);
+    return;
+  }
+  const relay = await useRelay(joinString, paths());
+  console.log(`tunnel to relay ${relay.name} (${relay.endpoint}) is up`);
+  console.log(`this host is reachable at ${relay.publicIp}; kvbox server join advertises it by default`);
+});
+program.command("net <action>").description("host network: up | down | status (bridge, forwarding, NAT; uses sudo)").action(async (action) => {
+  if (!["up", "down", "status"].includes(action)) throw new KvboxError("net: expected up, down or status");
+  const cfg = await loadConfig(paths());
+  const res = spawnSync(netSetupScript(), [action], {
+    stdio: "inherit",
+    env: { ...process.env, KVBOX_BRIDGE: cfg.bridge, KVBOX_SUBNET: cfg.subnet, KVBOX_GATEWAY: cfg.gateway }
+  });
+  process.exit(res.status ?? 1);
+});
+try {
+  await program.parseAsync(process.argv);
+} catch (err) {
+  if (err instanceof KvboxError) {
+    console.error(`error: ${err.message}`);
+    process.exit(err.exitCode);
+  }
+  throw err;
+}
+//# sourceMappingURL=kvbox-server.js.map