@omg-dev/sandbox 0.4.25

package/README.md

@@ -0,0 +1,84 @@
+# `@omg-dev/sandbox`
+
+Server-only control-plane client and TypeScript template baker for Vibes
+sandboxes. This is deliberately separate from `@omg-dev/sdk/sandbox`, which is
+the restricted router available to code running *inside* a user sandbox.
+
+## Public usage (API key)
+
+Get an API key (`omg_sk_…`) from the omg.dev dashboard and point the client at
+the public API — see [docs.omg.dev/sandbox](https://docs.omg.dev/sandbox):
+
+```ts
+import { SandboxClient } from "@omg-dev/sandbox";
+
+const client = new SandboxClient({
+  baseUrl: "https://infra.omg.dev",
+  token: process.env.OMG_API_KEY!, // omg_sk_...
+});
+
+const sandbox = await client.create({ templateId: "react-ts", ports: [5173] });
+await sandbox.exec("echo", ["hello from a microVM"]);
+await sandbox.snapshot();
+await sandbox.stop();
+```
+
+## Template baking (service / self-host)
+
+```ts
+import {
+  SandboxClient,
+  apt,
+  bakeTemplate,
+  check,
+  defineTemplate,
+  run,
+} from "@omg-dev/sandbox";
+
+const template = defineTemplate({
+  id: "my-agent",
+  version: "1",
+  title: "My agent",
+  ports: [3000],
+  install: [
+    apt.packages(["tmux"]),
+    run({ user: "user", command: "bun install -g my-agent@1.2.3" }),
+  ],
+  checks: [check.command("tmux"), check.command("my-agent", { user: "user" })],
+  start: {
+    user: "user",
+    command: "my-agent serve --host 0.0.0.0 --port 3000",
+    readiness: { port: 3000 },
+  },
+});
+
+const client = new SandboxClient({
+  baseUrl: process.env.VIBES_SANDBOX_URL!,
+  token: process.env.VIBES_INFRA_SERVICE_TOKEN!,
+  ownerId: "user-or-org-id",
+});
+
+await bakeTemplate(client, template);
+```
+
+`bakeTemplate` creates a raw sandbox, applies each typed step, verifies checks,
+writes a generic boot contract, snapshots it, waits for durable upload, and
+publishes both `my-agent-v1` and `my-agent` (latest). Direct service clients
+publish an immutable version in the global system catalogue; clients with an
+`ownerId` publish both names in that user's private namespace. A deployment
+consumes either with `{ templateId: "my-agent-v1" }` or `{ templateId:
+"my-agent" }`.
+
+Publication also records the compiled start command, ports, and readiness probe
+in the template registry. Creation copies that executable contract onto the
+sandbox row, so hibernate/resume never re-reads mutable registry state and a
+later `latest` publish cannot change an existing sandbox.
+
+Repository templates live at `templates/<id>/template.ts`. The existing Build
+Templates workflow discovers them and uses the same baker. `agent-catalog.ts`
+is the source of truth for the first-party coding-agent images.
+
+Never import this package in browser code: its client accepts privileged API
+credentials. User-authenticated server routes may instantiate it with the
+caller's token and owner ID; install commands still run only inside the
+Firecracker guest.

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { a as compileStartScript, c as download, d as templateRuntimeContract, f as templateVersionRef, h as assertTemplateId, i as check, l as run, m as SandboxClient, n as apt, o as compileStep, p as waitForSnapshotUpload, r as bakeTemplate, s as defineTemplate, t as applyTemplate, u as templateDefinitionHash } from "./templates-CdQWcmOC.mjs";
+export { SandboxClient, applyTemplate, apt, assertTemplateId, bakeTemplate, check, compileStartScript, compileStep, defineTemplate, download, run, templateDefinitionHash, templateRuntimeContract, templateVersionRef, waitForSnapshotUpload };

package/dist/templates-CdQWcmOC.mjs

@@ -0,0 +1,251 @@
+import { createHash } from "node:crypto";
+//#region src/client.ts
+const TEMPLATE_ID = /^[a-z0-9][a-z0-9-]{0,38}[a-z0-9]$/;
+function assertTemplateId(id) {
+	const normalized = id.trim().toLowerCase();
+	if (!TEMPLATE_ID.test(normalized)) throw new Error(`invalid template id ${JSON.stringify(id)} (want 2-40 lowercase letters, digits, or hyphens)`);
+	return normalized;
+}
+var SandboxClient = class {
+	baseUrl;
+	ownerId;
+	token;
+	fetchImpl;
+	constructor(options) {
+		this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+		this.token = options.token;
+		this.ownerId = options.ownerId;
+		this.fetchImpl = options.fetch ?? fetch;
+		if (!this.baseUrl) throw new Error("sandbox baseUrl is required");
+		if (!this.token) throw new Error("sandbox token is required");
+	}
+	async request(method, path, body) {
+		const headers = {
+			authorization: `Bearer ${this.token}`,
+			"content-type": "application/json"
+		};
+		if (this.ownerId) headers["x-on-behalf-of"] = this.ownerId;
+		const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+			method,
+			headers,
+			body: body === void 0 ? void 0 : JSON.stringify(body)
+		});
+		if (response.status === 204) return void 0;
+		const text = await response.text();
+		let parsed = text;
+		try {
+			parsed = text ? JSON.parse(text) : void 0;
+		} catch {}
+		if (!response.ok) {
+			const detail = parsed && typeof parsed === "object" && "error" in parsed ? String(parsed.error) : text || `HTTP ${response.status}`;
+			throw new Error(`sandbox API ${method} ${path}: ${response.status} ${detail}`);
+		}
+		return parsed;
+	}
+	async create(options = {}) {
+		const meta = await this.request("POST", "/v1/sandboxes", options);
+		return this.wrap(meta.id);
+	}
+	async getSnapshot(id) {
+		return this.request("GET", `/v1/snapshots/${encodeURIComponent(id)}`);
+	}
+	async publishTemplate(templateId, snapshotId, runtime) {
+		const id = assertTemplateId(templateId);
+		await this.request("POST", `/v1/templates/${id}/latest`, {
+			snapshotId,
+			...runtime
+		});
+	}
+	async resolveTemplate(templateId) {
+		const id = assertTemplateId(templateId);
+		return this.request("GET", `/v1/templates/${id}/latest`);
+	}
+	wrap(id) {
+		return {
+			id,
+			exec: (command, args = [], options = {}) => this.request("POST", `/v1/sandboxes/${id}/exec`, {
+				cmd: command,
+				args,
+				...options
+			}),
+			shell: (script, options = {}) => this.request("POST", `/v1/sandboxes/${id}/exec`, {
+				cmd: "/bin/bash",
+				args: ["-lc", script],
+				...options
+			}),
+			writeFiles: async (files) => {
+				await this.request("POST", `/v1/sandboxes/${id}/files`, files.map((file) => ({
+					path: file.path,
+					content: Buffer.from(file.content).toString("base64"),
+					mode: file.mode
+				})));
+			},
+			snapshot: () => this.request("POST", `/v1/sandboxes/${id}/snapshot`),
+			stop: () => this.request("DELETE", `/v1/sandboxes/${id}`)
+		};
+	}
+};
+//#endregion
+//#region src/templates.ts
+const apt = { packages(packages) {
+	if (!packages.length) throw new Error("apt.packages requires at least one package");
+	for (const name of packages) if (!/^[a-z0-9][a-z0-9+.-]*$/.test(name)) throw new Error(`invalid apt package ${name}`);
+	return {
+		kind: "apt",
+		packages: [...packages]
+	};
+} };
+const download = { archive(options) {
+	return {
+		kind: "archive",
+		...options
+	};
+} };
+function run(options) {
+	return {
+		kind: "run",
+		...options
+	};
+}
+const check = {
+	command(command, options = {}) {
+		return {
+			kind: "command",
+			command,
+			...options
+		};
+	},
+	file(path) {
+		return {
+			kind: "file",
+			path
+		};
+	}
+};
+function defineTemplate(definition) {
+	assertTemplateId(definition.id);
+	if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,19}$/.test(definition.version)) throw new Error("invalid template version");
+	if (!definition.title.trim()) throw new Error("template title is required");
+	for (const port of definition.ports ?? []) if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`invalid template port ${port}`);
+	return Object.freeze(definition);
+}
+function templateVersionRef(definition) {
+	const suffix = `-v${definition.version.toLowerCase().replace(/[^a-z0-9-]+/g, "-")}`;
+	const maxBase = 40 - suffix.length;
+	if (maxBase < 2) throw new Error("template id and version are too long for registry");
+	return assertTemplateId(`${definition.id.slice(0, maxBase).replace(/-+$/, "")}${suffix}`);
+}
+function templateDefinitionHash(definition) {
+	return createHash("sha256").update(JSON.stringify(definition)).digest("hex");
+}
+function templateRuntimeContract(definition, immutableRef) {
+	return {
+		immutableRef,
+		startCommand: definition.start ? "exec /home/user/.omg/template/bootstrap.sh" : void 0,
+		readinessPort: definition.start?.readiness?.port,
+		readinessPath: definition.start?.readiness?.path,
+		ports: [...definition.ports ?? []]
+	};
+}
+function quote(value) {
+	return `'${value.replaceAll("'", `'\"'\"'`)}'`;
+}
+function commandForUser(command, user) {
+	if (!user) return `/bin/bash -lc ${quote(command)}`;
+	const home = user === "root" ? "/root" : `/home/${user}`;
+	return `sudo -u ${quote(user)} -H env HOME=${quote(home)} PATH=${quote(`${home}/.bun/bin:/usr/local/bin:/usr/bin:/bin`)} /bin/bash -c ${quote(command)}`;
+}
+function shellEnvAssignments(env) {
+	return Object.entries(env).map(([key, value]) => {
+		if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) throw new Error(`invalid environment variable ${JSON.stringify(key)}`);
+		return `${key}=${quote(value)}`;
+	});
+}
+function compileStep(step) {
+	if (step.kind === "apt") return { script: `set -euo pipefail\napt-get update -qq\nDEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends ${step.packages.map(quote).join(" ")}\nrm -rf /var/lib/apt/lists/*` };
+	if (step.kind === "archive") {
+		const strip = step.stripComponents ?? 1;
+		if (!Number.isInteger(strip) || strip < 0 || strip > 20) throw new Error("invalid stripComponents");
+		return { script: `set -euo pipefail\ntmp=$(mktemp /tmp/template-archive-XXXXXX)\ntrap 'rm -f \"$tmp\"' EXIT\ncurl -fSL --retry 3 --retry-delay 2 ${quote(step.url)} -o \"$tmp\"\nmkdir -p ${quote(step.destination)}\nTAR_OPTIONS= tar -xzf \"$tmp\" -C ${quote(step.destination)} --strip-components=${strip} --overwrite --no-same-owner --no-same-permissions --touch` };
+	}
+	const env = shellEnvAssignments(step.env ?? {}).join(" ");
+	return {
+		script: `set -euo pipefail\n${commandForUser(`${step.cwd ? `cd ${quote(step.cwd)} && ` : ""}${env ? `export ${env} && ` : ""}${step.command}`, step.user)}`,
+		timeoutMs: step.timeoutMs
+	};
+}
+function compileStartScript(start) {
+	const port = start.readiness?.port;
+	const timeout = start.readiness?.timeoutSeconds ?? 60;
+	const foreground = commandForUser(`${shellEnvAssignments({
+		HOME: start.user ? `/home/${start.user}` : "/root",
+		...start.env ?? {}
+	}).map((assignment) => `export ${assignment}`).join("\n")}\n${`${start.cwd ? `cd ${quote(start.cwd)} && ` : ""}${start.command}`}`, start.user);
+	const probe = port ? `for _ in $(seq 1 ${timeout}); do curl -fsS -m1 -o /dev/null ${quote(`http://127.0.0.1:${port}${start.readiness?.path ?? "/"}`)} && exit 0; sleep 1; done\necho 'template service did not become ready on :${port}' >&2\nexit 1` : "exit 0";
+	return `#!/usr/bin/env bash\nset -euo pipefail\nmkdir -p /home/user/.omg/template\npidfile=/home/user/.omg/template/start.pid\nif [ -s \"$pidfile\" ] && kill -0 \"$(cat \"$pidfile\")\" 2>/dev/null; then exit 0; fi\nnohup /bin/bash -lc ${quote(`while true; do ${foreground} >>/home/user/.omg/template/start.log 2>&1 || true; sleep 2; done`)} >/dev/null 2>&1 &\necho $! > \"$pidfile\"\n${probe}\n`;
+}
+async function assertExec(label, result) {
+	if (result.exitCode !== 0) throw new Error(`${label} failed (${result.exitCode}): ${(result.stderr || result.stdout).trim().slice(-1200)}`);
+}
+async function applyTemplate(sandbox, definition, onLog = () => {}) {
+	for (const [index, step] of definition.install.entries()) {
+		onLog(`install ${index + 1}/${definition.install.length}: ${step.kind}`);
+		const compiled = compileStep(step);
+		await assertExec(`template step ${index + 1}`, await sandbox.shell(compiled.script, { timeoutMs: compiled.timeoutMs ?? 10 * 6e4 }));
+	}
+	if (definition.start) await sandbox.writeFiles([{
+		path: "/home/user/.omg/template/bootstrap.sh",
+		content: compileStartScript(definition.start),
+		mode: 493
+	}]);
+	const manifest = {
+		...definition,
+		definitionHash: templateDefinitionHash(definition)
+	};
+	await sandbox.writeFiles([{
+		path: "/home/user/.omg/template/definition.json",
+		content: `${JSON.stringify(manifest, null, 2)}\n`,
+		mode: 420
+	}]);
+	for (const item of definition.checks ?? []) {
+		const test = item.kind === "file" ? `test -e ${quote(item.path)}` : commandForUser(`command -v ${quote(item.command)}`, item.user);
+		await assertExec(`template check ${item.kind === "file" ? item.path : item.command}`, await sandbox.shell(`set -euo pipefail\n${test}`));
+	}
+}
+async function waitForSnapshotUpload(client, snapshot, timeoutMs = 10 * 6e4) {
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		if ((await client.getSnapshot(snapshot.id)).uploadedToTigris) return;
+		await new Promise((resolve) => setTimeout(resolve, 2e3));
+	}
+	throw new Error(`snapshot ${snapshot.id} was not uploaded within ${timeoutMs}ms`);
+}
+async function bakeTemplate(client, definition, options = {}) {
+	const log = options.onLog ?? (() => {});
+	const versionRef = templateVersionRef(definition);
+	const sandbox = await client.create({
+		ports: [...definition.ports ?? []],
+		skipAppProcesses: true,
+		projectSlug: definition.id
+	});
+	let snapshotted = false;
+	try {
+		await applyTemplate(sandbox, definition, log);
+		const snapshot = await sandbox.snapshot();
+		snapshotted = true;
+		await waitForSnapshotUpload(client, snapshot);
+		const runtime = templateRuntimeContract(definition, client.ownerId ? void 0 : versionRef);
+		await client.publishTemplate(versionRef, snapshot.id, runtime);
+		if (options.publishLatest !== false) await client.publishTemplate(definition.id, snapshot.id, runtime);
+		return {
+			templateId: definition.id,
+			versionRef,
+			definitionHash: templateDefinitionHash(definition),
+			snapshotId: snapshot.id
+		};
+	} finally {
+		if (!snapshotted) await sandbox.stop().catch(() => {});
+	}
+}
+//#endregion
+export { compileStartScript as a, download as c, templateRuntimeContract as d, templateVersionRef as f, assertTemplateId as h, check as i, run as l, SandboxClient as m, apt as n, compileStep as o, waitForSnapshotUpload as p, bakeTemplate as r, defineTemplate as s, applyTemplate as t, templateDefinitionHash as u };

package/dist/templates.mjs

@@ -0,0 +1,2 @@
+import { a as compileStartScript, c as download, d as templateRuntimeContract, f as templateVersionRef, i as check, l as run, n as apt, o as compileStep, p as waitForSnapshotUpload, r as bakeTemplate, s as defineTemplate, t as applyTemplate, u as templateDefinitionHash } from "./templates-CdQWcmOC.mjs";
+export { applyTemplate, apt, bakeTemplate, check, compileStartScript, compileStep, defineTemplate, download, run, templateDefinitionHash, templateRuntimeContract, templateVersionRef, waitForSnapshotUpload };

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@omg-dev/sandbox",
+  "version": "0.4.25",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./dist/index.mjs"
+    },
+    "./templates": {
+      "types": "./src/templates.ts",
+      "default": "./dist/templates.mjs"
+    }
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.0.0",
+    "typescript": "npm:@typescript/typescript6@6.0.2"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BennyKok/vibes.git"
+  },
+  "homepage": "https://docs.omg.dev",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "dist",
+    "src"
+  ]
+}

package/src/client.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test";
+import { SandboxClient } from "./client";
+import { bakeTemplate, defineTemplate } from "./templates";
+
+describe("SandboxClient template bake", () => {
+  test("attributes ownership and publishes private version plus latest pointers", async () => {
+    const calls: Array<{ method: string; path: string; body?: unknown; owner?: string | null }> = [];
+    const fakeFetch = (async (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => {
+      const url = new URL(String(input));
+      const body = init?.body ? JSON.parse(String(init.body)) : undefined;
+      calls.push({ method: init?.method ?? "GET", path: url.pathname, body, owner: new Headers(init?.headers).get("x-on-behalf-of") });
+      const json = (value: unknown) => new Response(JSON.stringify(value), { status: 200, headers: { "content-type": "application/json" } });
+      if (url.pathname === "/v1/sandboxes" && init?.method === "POST") return json({ id: "sb-1" });
+      if (url.pathname.endsWith("/files")) return json({ ok: true });
+      if (url.pathname.endsWith("/snapshot")) return json({ id: "snap-1", sizeBytes: 42, createdAt: "2026-01-01T00:00:00Z" });
+      if (url.pathname === "/v1/snapshots/snap-1") return json({ id: "snap-1", sizeBytes: 42, createdAt: "2026-01-01T00:00:00Z", uploadedToTigris: true });
+      if (url.pathname.startsWith("/v1/templates/")) return json({ ok: true });
+      throw new Error(`unexpected ${init?.method} ${url.pathname}`);
+    }) as typeof fetch;
+    const client = new SandboxClient({ baseUrl: "https://infra.example", token: "secret", ownerId: "user-123", fetch: fakeFetch });
+    const result = await bakeTemplate(client, defineTemplate({
+      id: "my-agent",
+      version: "3",
+      title: "Mine",
+      ports: [8766],
+      install: [],
+      start: { command: "bun start", readiness: { port: 8766, path: "/health" } },
+    }));
+    expect(result.versionRef).toBe("my-agent-v3");
+    expect(calls.every((call) => call.owner === "user-123")).toBe(true);
+    expect(calls.filter((call) => call.path.includes("/v1/templates/")).map((call) => call.path)).toEqual([
+      "/v1/templates/my-agent-v3/latest",
+      "/v1/templates/my-agent/latest",
+    ]);
+    expect(calls[0]?.body).toEqual({ ports: [8766], skipAppProcesses: true, projectSlug: "my-agent" });
+    expect(calls.filter((call) => call.path.includes("/v1/templates/")).map((call) => call.body)).toEqual([
+      {
+        snapshotId: "snap-1",
+        startCommand: "exec /home/user/.omg/template/bootstrap.sh",
+        readinessPort: 8766,
+        readinessPath: "/health",
+        ports: [8766],
+      },
+      {
+        snapshotId: "snap-1",
+        startCommand: "exec /home/user/.omg/template/bootstrap.sh",
+        readinessPort: 8766,
+        readinessPath: "/health",
+        ports: [8766],
+      },
+    ]);
+  });
+});

package/src/client.ts

@@ -0,0 +1,145 @@
+export interface SandboxClientOptions {
+  baseUrl: string;
+  token: string;
+  /** Owner attributed to creates, snapshots, and template publication. */
+  ownerId?: string;
+  fetch?: typeof fetch;
+}
+
+export interface ExecOptions {
+  cwd?: string;
+  env?: Record<string, string>;
+  timeoutMs?: number;
+  detached?: boolean;
+}
+
+export interface ExecResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  commandId?: string;
+}
+
+export interface Snapshot {
+  id: string;
+  sizeBytes: number;
+  createdAt: string;
+  uploadedToTigris?: boolean;
+}
+
+export interface CreateSandboxOptions {
+  ports?: number[];
+  templateId?: string;
+  timeout?: number;
+  sessionId?: string;
+  projectSlug?: string;
+  skipAppProcesses?: boolean;
+}
+
+export interface TemplateRuntimeContract {
+  /** Reserved for service-owned system template versions. */
+  immutableRef?: string;
+  startCommand?: string;
+  readinessPort?: number;
+  readinessPath?: string;
+  ports?: number[];
+}
+
+export interface Sandbox {
+  readonly id: string;
+  exec(command: string, args?: string[], options?: ExecOptions): Promise<ExecResult>;
+  shell(script: string, options?: ExecOptions): Promise<ExecResult>;
+  writeFiles(files: Array<{ path: string; content: Uint8Array | string; mode?: number }>): Promise<void>;
+  snapshot(): Promise<Snapshot>;
+  stop(): Promise<void>;
+}
+
+const TEMPLATE_ID = /^[a-z0-9][a-z0-9-]{0,38}[a-z0-9]$/;
+
+export function assertTemplateId(id: string): string {
+  const normalized = id.trim().toLowerCase();
+  if (!TEMPLATE_ID.test(normalized)) {
+    throw new Error(`invalid template id ${JSON.stringify(id)} (want 2-40 lowercase letters, digits, or hyphens)`);
+  }
+  return normalized;
+}
+
+export class SandboxClient {
+  readonly baseUrl: string;
+  readonly ownerId?: string;
+  private readonly token: string;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(options: SandboxClientOptions) {
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.token = options.token;
+    this.ownerId = options.ownerId;
+    this.fetchImpl = options.fetch ?? fetch;
+    if (!this.baseUrl) throw new Error("sandbox baseUrl is required");
+    if (!this.token) throw new Error("sandbox token is required");
+  }
+
+  async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const headers: Record<string, string> = {
+      authorization: `Bearer ${this.token}`,
+      "content-type": "application/json",
+    };
+    if (this.ownerId) headers["x-on-behalf-of"] = this.ownerId;
+    const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+      method,
+      headers,
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    if (response.status === 204) return undefined as T;
+    const text = await response.text();
+    let parsed: unknown = text;
+    try { parsed = text ? JSON.parse(text) : undefined; } catch { /* keep text */ }
+    if (!response.ok) {
+      const detail = parsed && typeof parsed === "object" && "error" in parsed
+        ? String((parsed as { error: unknown }).error)
+        : text || `HTTP ${response.status}`;
+      throw new Error(`sandbox API ${method} ${path}: ${response.status} ${detail}`);
+    }
+    return parsed as T;
+  }
+
+  async create(options: CreateSandboxOptions = {}): Promise<Sandbox> {
+    const meta = await this.request<{ id: string }>("POST", "/v1/sandboxes", options);
+    return this.wrap(meta.id);
+  }
+
+  async getSnapshot(id: string): Promise<Snapshot> {
+    return this.request("GET", `/v1/snapshots/${encodeURIComponent(id)}`);
+  }
+
+  async publishTemplate(templateId: string, snapshotId: string, runtime?: TemplateRuntimeContract): Promise<void> {
+    const id = assertTemplateId(templateId);
+    await this.request("POST", `/v1/templates/${id}/latest`, { snapshotId, ...runtime });
+  }
+
+  async resolveTemplate(templateId: string): Promise<{ templateId: string; snapshotId: string }> {
+    const id = assertTemplateId(templateId);
+    return this.request("GET", `/v1/templates/${id}/latest`);
+  }
+
+  private wrap(id: string): Sandbox {
+    return {
+      id,
+      exec: (command, args = [], options = {}) => this.request("POST", `/v1/sandboxes/${id}/exec`, {
+        cmd: command, args, ...options,
+      }),
+      shell: (script, options = {}) => this.request("POST", `/v1/sandboxes/${id}/exec`, {
+        cmd: "/bin/bash", args: ["-lc", script], ...options,
+      }),
+      writeFiles: async (files) => {
+        await this.request("POST", `/v1/sandboxes/${id}/files`, files.map((file) => ({
+          path: file.path,
+          content: Buffer.from(file.content).toString("base64"),
+          mode: file.mode,
+        })));
+      },
+      snapshot: () => this.request("POST", `/v1/sandboxes/${id}/snapshot`),
+      stop: () => this.request("DELETE", `/v1/sandboxes/${id}`),
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./client.js";
+export * from "./templates.js";

package/src/templates.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, test } from "bun:test";
+import { apt, check, compileStartScript, compileStep, defineTemplate, download, run, templateRuntimeContract, templateVersionRef } from "./templates";
+import { agentTemplates } from "../../../templates/agent-catalog";
+
+describe("sandbox templates", () => {
+  test("defines a typed, immutable versioned template", () => {
+    const template = defineTemplate({ id: "angel-lfg", version: "12", title: "Angel", install: [apt.packages(["tmux"])], checks: [check.command("tmux")] });
+    expect(templateVersionRef(template)).toBe("angel-lfg-v12");
+    expect(Object.isFrozen(template)).toBe(true);
+  });
+
+  test("archive extraction ignores inherited tar policy", () => {
+    const { script } = compileStep(download.archive({ url: "https://example.com/a.tgz", destination: "/home/user/app" }));
+    expect(script).toContain("TAR_OPTIONS= tar");
+    expect(script).toContain("--no-same-owner");
+  });
+
+  test("quotes run fields and writes a supervised startup contract", () => {
+    expect(compileStep(run({ command: "bun start", cwd: "/home/user/my app", user: "user", env: { VALUE: "a'b" } })).script).toContain("sudo -u 'user'");
+    const script = compileStartScript({ command: "bun start", user: "user", readiness: { port: 8766 } });
+    expect(script).toContain("/home/user/.omg/template/start.pid");
+    expect(script).toContain("http://127.0.0.1:8766/");
+    expect(() => compileStep(run({ command: "true", env: { "BAD-NAME": "x" } }))).toThrow("invalid environment variable");
+  });
+
+  test("LFG owns every runtime dependency and zero-config transport default", () => {
+    const lfg = agentTemplates.lfg;
+    expect(templateVersionRef(lfg)).toBe("agent-lfg-v10");
+    expect(lfg.install).toContainEqual(apt.packages(["tmux"]));
+    expect(lfg.checks).toContainEqual(check.command("tmux"));
+    expect(lfg.start?.env?.LIVE_TRANSPORT).toBe("ws");
+    expect(lfg.start?.readiness?.port).toBe(8766);
+    expect(templateRuntimeContract(lfg, templateVersionRef(lfg))).toEqual({
+      immutableRef: "agent-lfg-v10",
+      startCommand: "exec /home/user/.omg/template/bootstrap.sh",
+      readinessPort: 8766,
+      readinessPath: "/",
+      ports: [8766],
+    });
+  });
+});

package/src/templates.ts

@@ -0,0 +1,189 @@
+import { createHash } from "node:crypto";
+import type { Sandbox, SandboxClient, Snapshot } from "./client.js";
+import { assertTemplateId } from "./client.js";
+
+export type TemplateStep =
+  | { kind: "apt"; packages: readonly string[] }
+  | { kind: "archive"; url: string; destination: string; stripComponents?: number }
+  | { kind: "run"; command: string; cwd?: string; user?: string; env?: Record<string, string>; timeoutMs?: number };
+
+export type TemplateCheck =
+  | { kind: "command"; command: string; user?: string }
+  | { kind: "file"; path: string };
+
+export interface TemplateStart {
+  command: string;
+  cwd?: string;
+  user?: string;
+  env?: Record<string, string>;
+  readiness?: { port: number; path?: string; timeoutSeconds?: number };
+}
+
+export interface SandboxTemplate {
+  id: string;
+  version: string;
+  title: string;
+  description?: string;
+  ports?: readonly number[];
+  install: readonly TemplateStep[];
+  checks?: readonly TemplateCheck[];
+  start?: TemplateStart;
+  metadata?: Record<string, string | number | boolean>;
+}
+
+export interface BakeResult {
+  templateId: string;
+  versionRef: string;
+  definitionHash: string;
+  snapshotId: string;
+}
+
+export const apt = {
+  packages(packages: readonly string[]): TemplateStep {
+    if (!packages.length) throw new Error("apt.packages requires at least one package");
+    for (const name of packages) if (!/^[a-z0-9][a-z0-9+.-]*$/.test(name)) throw new Error(`invalid apt package ${name}`);
+    return { kind: "apt", packages: [...packages] };
+  },
+};
+
+export const download = {
+  archive(options: Omit<Extract<TemplateStep, { kind: "archive" }>, "kind">): TemplateStep {
+    return { kind: "archive", ...options };
+  },
+};
+
+export function run(options: Omit<Extract<TemplateStep, { kind: "run" }>, "kind">): TemplateStep {
+  return { kind: "run", ...options };
+}
+
+export const check = {
+  command(command: string, options: { user?: string } = {}): TemplateCheck {
+    return { kind: "command", command, ...options };
+  },
+  file(path: string): TemplateCheck { return { kind: "file", path }; },
+};
+
+export function defineTemplate<const T extends SandboxTemplate>(definition: T): T {
+  assertTemplateId(definition.id);
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,19}$/.test(definition.version)) throw new Error("invalid template version");
+  if (!definition.title.trim()) throw new Error("template title is required");
+  for (const port of definition.ports ?? []) {
+    if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`invalid template port ${port}`);
+  }
+  return Object.freeze(definition);
+}
+
+export function templateVersionRef(definition: SandboxTemplate): string {
+  const suffix = `-v${definition.version.toLowerCase().replace(/[^a-z0-9-]+/g, "-")}`;
+  const maxBase = 40 - suffix.length;
+  if (maxBase < 2) throw new Error("template id and version are too long for registry");
+  return assertTemplateId(`${definition.id.slice(0, maxBase).replace(/-+$/, "")}${suffix}`);
+}
+
+export function templateDefinitionHash(definition: SandboxTemplate): string {
+  return createHash("sha256").update(JSON.stringify(definition)).digest("hex");
+}
+
+export function templateRuntimeContract(definition: SandboxTemplate, immutableRef?: string) {
+  return {
+    immutableRef,
+    startCommand: definition.start ? "exec /home/user/.omg/template/bootstrap.sh" : undefined,
+    readinessPort: definition.start?.readiness?.port,
+    readinessPath: definition.start?.readiness?.path,
+    ports: [...(definition.ports ?? [])],
+  };
+}
+
+function quote(value: string): string { return `'${value.replaceAll("'", `'\"'\"'`)}'`; }
+
+function commandForUser(command: string, user?: string): string {
+  if (!user) return `/bin/bash -lc ${quote(command)}`;
+  const home = user === "root" ? "/root" : `/home/${user}`;
+  return `sudo -u ${quote(user)} -H env HOME=${quote(home)} PATH=${quote(`${home}/.bun/bin:/usr/local/bin:/usr/bin:/bin`)} /bin/bash -c ${quote(command)}`;
+}
+
+function shellEnvAssignments(env: Record<string, string>): string[] {
+  return Object.entries(env).map(([key, value]) => {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) throw new Error(`invalid environment variable ${JSON.stringify(key)}`);
+    return `${key}=${quote(value)}`;
+  });
+}
+
+export function compileStep(step: TemplateStep): { script: string; timeoutMs?: number } {
+  if (step.kind === "apt") {
+    return { script: `set -euo pipefail\napt-get update -qq\nDEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends ${step.packages.map(quote).join(" ")}\nrm -rf /var/lib/apt/lists/*` };
+  }
+  if (step.kind === "archive") {
+    const strip = step.stripComponents ?? 1;
+    if (!Number.isInteger(strip) || strip < 0 || strip > 20) throw new Error("invalid stripComponents");
+    return { script: `set -euo pipefail\ntmp=$(mktemp /tmp/template-archive-XXXXXX)\ntrap 'rm -f \"$tmp\"' EXIT\ncurl -fSL --retry 3 --retry-delay 2 ${quote(step.url)} -o \"$tmp\"\nmkdir -p ${quote(step.destination)}\nTAR_OPTIONS= tar -xzf \"$tmp\" -C ${quote(step.destination)} --strip-components=${strip} --overwrite --no-same-owner --no-same-permissions --touch` };
+  }
+  const env = shellEnvAssignments(step.env ?? {}).join(" ");
+  const inner = `${step.cwd ? `cd ${quote(step.cwd)} && ` : ""}${env ? `export ${env} && ` : ""}${step.command}`;
+  return { script: `set -euo pipefail\n${commandForUser(inner, step.user)}`, timeoutMs: step.timeoutMs };
+}
+
+export function compileStartScript(start: TemplateStart): string {
+  const port = start.readiness?.port;
+  const timeout = start.readiness?.timeoutSeconds ?? 60;
+  const env = { HOME: start.user ? `/home/${start.user}` : "/root", ...(start.env ?? {}) };
+  const exports = shellEnvAssignments(env).map((assignment) => `export ${assignment}`).join("\n");
+  const command = `${start.cwd ? `cd ${quote(start.cwd)} && ` : ""}${start.command}`;
+  const foreground = commandForUser(`${exports}\n${command}`, start.user);
+  const probe = port
+    ? `for _ in $(seq 1 ${timeout}); do curl -fsS -m1 -o /dev/null ${quote(`http://127.0.0.1:${port}${start.readiness?.path ?? "/"}`)} && exit 0; sleep 1; done\necho 'template service did not become ready on :${port}' >&2\nexit 1`
+    : "exit 0";
+  return `#!/usr/bin/env bash\nset -euo pipefail\nmkdir -p /home/user/.omg/template\npidfile=/home/user/.omg/template/start.pid\nif [ -s \"$pidfile\" ] && kill -0 \"$(cat \"$pidfile\")\" 2>/dev/null; then exit 0; fi\nnohup /bin/bash -lc ${quote(`while true; do ${foreground} >>/home/user/.omg/template/start.log 2>&1 || true; sleep 2; done`)} >/dev/null 2>&1 &\necho $! > \"$pidfile\"\n${probe}\n`;
+}
+
+async function assertExec(label: string, result: { exitCode: number; stdout: string; stderr: string }): Promise<void> {
+  if (result.exitCode !== 0) throw new Error(`${label} failed (${result.exitCode}): ${(result.stderr || result.stdout).trim().slice(-1200)}`);
+}
+
+export async function applyTemplate(sandbox: Sandbox, definition: SandboxTemplate, onLog: (line: string) => void = () => {}): Promise<void> {
+  for (const [index, step] of definition.install.entries()) {
+    onLog(`install ${index + 1}/${definition.install.length}: ${step.kind}`);
+    const compiled = compileStep(step);
+    await assertExec(`template step ${index + 1}`, await sandbox.shell(compiled.script, { timeoutMs: compiled.timeoutMs ?? 10 * 60_000 }));
+  }
+  if (definition.start) {
+    await sandbox.writeFiles([{ path: "/home/user/.omg/template/bootstrap.sh", content: compileStartScript(definition.start), mode: 0o755 }]);
+  }
+  const manifest = { ...definition, definitionHash: templateDefinitionHash(definition) };
+  await sandbox.writeFiles([{ path: "/home/user/.omg/template/definition.json", content: `${JSON.stringify(manifest, null, 2)}\n`, mode: 0o644 }]);
+  for (const item of definition.checks ?? []) {
+    const test = item.kind === "file" ? `test -e ${quote(item.path)}` : commandForUser(`command -v ${quote(item.command)}`, item.user);
+    await assertExec(`template check ${item.kind === "file" ? item.path : item.command}`, await sandbox.shell(`set -euo pipefail\n${test}`));
+  }
+}
+
+export async function waitForSnapshotUpload(client: SandboxClient, snapshot: Snapshot, timeoutMs = 10 * 60_000): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if ((await client.getSnapshot(snapshot.id)).uploadedToTigris) return;
+    await new Promise((resolve) => setTimeout(resolve, 2_000));
+  }
+  throw new Error(`snapshot ${snapshot.id} was not uploaded within ${timeoutMs}ms`);
+}
+
+export async function bakeTemplate(client: SandboxClient, definition: SandboxTemplate, options: { onLog?: (line: string) => void; publishLatest?: boolean } = {}): Promise<BakeResult> {
+  const log = options.onLog ?? (() => {});
+  const versionRef = templateVersionRef(definition);
+  const sandbox = await client.create({ ports: [...(definition.ports ?? [])], skipAppProcesses: true, projectSlug: definition.id });
+  let snapshotted = false;
+  try {
+    await applyTemplate(sandbox, definition, log);
+    const snapshot = await sandbox.snapshot();
+    snapshotted = true;
+    await waitForSnapshotUpload(client, snapshot);
+    // A client with ownerId acts on behalf of a user and publishes into that
+    // user's private namespace. Only the direct service client may mark a
+    // global system version immutable.
+    const runtime = templateRuntimeContract(definition, client.ownerId ? undefined : versionRef);
+    await client.publishTemplate(versionRef, snapshot.id, runtime);
+    if (options.publishLatest !== false) await client.publishTemplate(definition.id, snapshot.id, runtime);
+    return { templateId: definition.id, versionRef, definitionHash: templateDefinitionHash(definition), snapshotId: snapshot.id };
+  } finally {
+    if (!snapshotted) await sandbox.stop().catch(() => {});
+  }
+}