Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
#!/usr/bin/env npx tsx
/**
* Generate the source-backed Sandbox package and image facts: the image
* catalog and the runtime support matrix of the Cua SDK reference. The
* curated body of each page lives in headers/cua-sdk/<page>.md; its
* `GENERATED:<name>` regions are filled from source manifests here.
*/
import * as fs from 'node:fs';
import * as path from 'node:path';
import { parseArgs } from 'node:util';
import { HEADERS_DIR, renderPage } from './lib/mdx';
import { SOFTWARE_DIR, loadInventories, renderSoftware } from './image-software';
const ROOT = path.resolve(__dirname, '../..');
const FACTS_PATH = path.join(__dirname, 'sandbox-facts.json');
const RUNTIME_DOC = path.join(ROOT, 'docs/content/docs/cua-sdk/reference/runtime-support.mdx');
const CATALOG_DOC = path.join(ROOT, 'docs/content/docs/cua-sdk/reference/os-image-catalog.mdx');
const SOFTWARE_DOC = path.join(ROOT, 'docs/content/docs/cua-sdk/reference/image-software.mdx');
const RUNTIME_TEMPLATE = path.join(HEADERS_DIR, 'cua-sdk', 'runtime-support.md');
const CATALOG_TEMPLATE = path.join(HEADERS_DIR, 'cua-sdk', 'os-image-catalog.md');
const GENERATOR = 'pnpm --dir docs docs:generate:sandbox';
const SOURCE = 'scripts/docs-generators/sandbox-facts.json and the cua, cua-sandbox and cua-image sources';
type Services = { server: number; mcp: number };
type Components = { computerServer: string; embeddedDriver: string; directDriver: string };
export interface QualifiedImage {
id: string;
image: string;
os: string;
distribution: string;
architecture: string;
desktop: string;
kind: string;
services: Services;
components: Components;
qualification: { boot: true; serviceReadiness: true };
}
export interface PublishedCandidate {
os: string;
distribution: string;
desktop: string;
kind: string;
image: string;
limits: string;
}
export interface SandboxFactsManifest {
$schema: string;
schemaVersion: 1;
qualifiedImages: QualifiedImage[];
publishedCandidates: PublishedCandidate[];
}
interface SourceFacts {
sandboxVersion: string;
cuaVersion: string;
sandboxDriverVersion: string;
qualifiedDirectDriverVersion: string;
linuxImage: string;
windowsImage: string;
macosTahoeImage: string;
macosSequoiaImage: string;
}
const VERSION = /^\d+\.\d+\.\d+$/;
const DIGEST_REF = /@sha256:[0-9a-f]{64}$/;
function object(value: unknown, label: string): Record<string, unknown> {
if (value === null || typeof value !== 'object' || Array.isArray(value)) {
throw new Error(`${label} must be an object`);
}
return value as Record<string, unknown>;
}
function exactKeys(value: Record<string, unknown>, keys: readonly string[], label: string): void {
const expected = [...keys].sort();
const actual = Object.keys(value).sort();
if (actual.join('\n') !== expected.join('\n')) {
throw new Error(`${label} keys must be ${expected.join(', ')}; got ${actual.join(', ')}`);
}
}
function string(value: unknown, label: string, pattern?: RegExp): string {
if (typeof value !== 'string' || value.length === 0 || (pattern && !pattern.test(value))) {
throw new Error(`${label} is invalid`);
}
return value;
}
function port(value: unknown, label: string): number {
if (!Number.isInteger(value) || Number(value) < 1 || Number(value) > 65535) {
throw new Error(`${label} must be a TCP port`);
}
return Number(value);
}
/** Validate without a network fetch or an unpinned schema-validator dependency. */
export function validateManifest(value: unknown): SandboxFactsManifest {
const root = object(value, 'manifest');
exactKeys(
root,
['$schema', 'schemaVersion', 'qualifiedImages', 'publishedCandidates'],
'manifest'
);
if (root.$schema !== './sandbox-facts.schema.json' || root.schemaVersion !== 1) {
throw new Error('manifest schema identity or version is invalid');
}
if (!Array.isArray(root.qualifiedImages) || root.qualifiedImages.length === 0) {
throw new Error('qualifiedImages must be a non-empty array');
}
const ids = new Set<string>();
const qualifiedImages = root.qualifiedImages.map((entry, index): QualifiedImage => {
const item = object(entry, `qualifiedImages[${index}]`);
exactKeys(
item,
[
'id',
'image',
'os',
'distribution',
'architecture',
'desktop',
'kind',
'services',
'components',
'qualification',
],
`qualifiedImages[${index}]`
);
const id = string(item.id, `qualifiedImages[${index}].id`, /^[a-z0-9-]+$/);
if (ids.has(id)) throw new Error(`duplicate qualified image id ${id}`);
ids.add(id);
const services = object(item.services, `${id}.services`);
exactKeys(services, ['server', 'mcp'], `${id}.services`);
const components = object(item.components, `${id}.components`);
exactKeys(components, ['computerServer', 'embeddedDriver', 'directDriver'], `${id}.components`);
const qualification = object(item.qualification, `${id}.qualification`);
exactKeys(qualification, ['boot', 'serviceReadiness'], `${id}.qualification`);
if (qualification.boot !== true || qualification.serviceReadiness !== true) {
throw new Error(`${id}.qualification must record boot and service readiness`);
}
return {
id,
image: string(item.image, `${id}.image`, DIGEST_REF),
os: string(item.os, `${id}.os`),
distribution: string(item.distribution, `${id}.distribution`),
architecture: string(item.architecture, `${id}.architecture`),
desktop: string(item.desktop, `${id}.desktop`),
kind: string(item.kind, `${id}.kind`),
services: {
server: port(services.server, `${id}.services.server`),
mcp: port(services.mcp, `${id}.services.mcp`),
},
components: {
computerServer: string(components.computerServer, `${id}.computerServer`, VERSION),
embeddedDriver: string(components.embeddedDriver, `${id}.embeddedDriver`, VERSION),
directDriver: string(components.directDriver, `${id}.directDriver`, VERSION),
},
qualification: { boot: true, serviceReadiness: true },
};
});
if (!Array.isArray(root.publishedCandidates)) {
throw new Error('publishedCandidates must be an array');
}
const publishedCandidates = root.publishedCandidates.map((entry, index): PublishedCandidate => {
const item = object(entry, `publishedCandidates[${index}]`);
exactKeys(
item,
['os', 'distribution', 'desktop', 'kind', 'image', 'limits'],
`publishedCandidates[${index}]`
);
return {
os: string(item.os, `publishedCandidates[${index}].os`),
distribution: string(item.distribution, `publishedCandidates[${index}].distribution`),
desktop: string(item.desktop, `publishedCandidates[${index}].desktop`),
kind: string(item.kind, `publishedCandidates[${index}].kind`),
image: string(item.image, `publishedCandidates[${index}].image`),
limits: string(item.limits, `publishedCandidates[${index}].limits`),
};
});
return {
$schema: './sandbox-facts.schema.json',
schemaVersion: 1,
qualifiedImages,
publishedCandidates,
};
}
export function loadManifest(file = FACTS_PATH): SandboxFactsManifest {
return validateManifest(JSON.parse(fs.readFileSync(file, 'utf8')));
}
function read(relativePath: string): string {
return fs.readFileSync(path.join(ROOT, relativePath), 'utf8');
}
function capture(contents: string, pattern: RegExp, label: string): string {
const match = contents.match(pattern);
if (!match?.[1]) throw new Error(`Could not extract ${label}`);
return match[1];
}
function projectVersion(relativePath: string): string {
const contents = read(relativePath);
return capture(contents, /\[project\][\s\S]*?\nversion\s*=\s*"([^"]+)"/, relativePath);
}
const CANONICAL_RS = 'libs/cua/crates/cua-image/src/canonical.rs';
/** A `pub const NAME: &str = "..."` of the canonical-image module. */
function rustConstant(contents: string, name: string): string {
return capture(
contents,
new RegExp(`^pub const ${name}: &str = "([^"]+)";`, 'm'),
`${CANONICAL_RS}:${name}`
);
}
export function loadSourceFacts(): SourceFacts {
const sandboxProject = read('libs/python/cua-sandbox/pyproject.toml');
const canonical = read(CANONICAL_RS);
const profile = JSON.parse(
read('libs/cua-driver/hyprland-plugin/packaging/release/profiles/omarchy-stable-20260910.json')
) as { source?: { driver_version?: string } };
return {
sandboxVersion: projectVersion('libs/python/cua-sandbox/pyproject.toml'),
cuaVersion: projectVersion('libs/cua/python/pyproject.toml'),
sandboxDriverVersion: capture(sandboxProject, /"cua-driver==([^"]+)"/, 'Sandbox Driver pin'),
qualifiedDirectDriverVersion: string(
profile.source?.driver_version,
'Omarchy release profile Driver version',
VERSION
),
linuxImage: `${rustConstant(canonical, 'LINUX_REPO')}:${rustConstant(canonical, 'LINUX_DEFAULT_VERSION')}`,
windowsImage: `${rustConstant(canonical, 'WINDOWS_REPO')}:${rustConstant(canonical, 'WINDOWS_DEFAULT_VERSION')}`,
macosTahoeImage: `${rustConstant(canonical, 'MACOS_REPO')}:${rustConstant(canonical, 'MACOS_DEFAULT_VERSION')}`,
// `Image.macos("15")` and the `macos:sequoia` alias (canonical.rs version_tag).
macosSequoiaImage: `${rustConstant(canonical, 'MACOS_REPO')}:${capture(
canonical,
/\(Self::Macos, "sequoia"\) => "([^"]+)"/,
`${CANONICAL_RS}:sequoia`
)}`,
};
}
function assertQualificationSources(manifest: SandboxFactsManifest, source: SourceFacts): void {
// computer-server left this repository; its version and embedded Driver in a
// qualified image are facts about that published artifact, recorded in the
// schema-checked manifest rather than cross-checked against source here.
for (const image of manifest.qualifiedImages) {
if (image.components.directDriver !== source.qualifiedDirectDriverVersion) {
throw new Error(
`${image.id} direct Driver disagrees with the public Omarchy release profile`
);
}
}
}
function generatedSection(name: string, body: string): string {
return `{/* GENERATED:${name}:start */}\n${body.trim()}\n{/* GENERATED:${name}:end */}`;
}
export function replaceGeneratedSection(document: string, name: string, body: string): string {
const start = `{/* GENERATED:${name}:start */}`;
const end = `{/* GENERATED:${name}:end */}`;
const startIndex = document.indexOf(start);
const endIndex = document.indexOf(end);
if (startIndex < 0 || endIndex < startIndex || document.indexOf(start, startIndex + 1) >= 0) {
throw new Error(`Expected one generated section named ${name}`);
}
return `${document.slice(0, startIndex)}${generatedSection(name, body)}${document.slice(
endIndex + end.length
)}`;
}
export function renderRuntimePackageFacts(source: SourceFacts): string {
return `This reference describes the Python Sandbox SDK in \`cua-sandbox\` **${source.sandboxVersion}**, exported
by \`cua\` **${source.cuaVersion}**. An accepted image specification is evidence of SDK behavior,
not proof that a guest boots on every host or deployment.`;
}
export function renderBuiltinMappings(source: SourceFacts): string {
return `| Constructor | Canonical image | Variant a backend runs |
| --- | --- | --- |
| \`Image.linux()\` | \`${source.linuxImage}\` | Rootfs for containers; the \`-disk\` containerDisk for \`kind="vm"\` |
| \`Image.windows()\` | \`${source.windowsImage}\` | The \`-disk\` containerDisk (VM) |
| \`Image.macos()\` | \`${source.macosTahoeImage}\` | Lume, local only (\`Image.macos("15")\`: \`${source.macosSequoiaImage}\`) |`;
}
export function renderEvidence(source: SourceFacts): string {
return `- \`cua-sandbox\` ${source.sandboxVersion} source: image constructors, runtime selection,
firmware, and services.
- \`cua-image\` source (\`canonical.rs\`): the canonical image references.
- \`cua\` ${source.cuaVersion} source: public Python exports.
- \`cua-sandbox[driver]\` ${source.sandboxVersion} maps direct Driver use to \`cua-driver\`
${source.sandboxDriverVersion}. This client mapping is not the Driver version inside a particular
published or deployment-qualified guest image.`;
}
/** One entry of `libs/images/sandbox-images.json`, the image list the apps and docs share. */
export type SandboxImage = {
ref: string;
group: 'canonical' | 'benchmark' | 'distro';
os: 'linux' | 'windows' | 'macos';
name: string;
/** The guest's distribution: its id picks the apps' OS icon, its name is
* what they show until a Space reports its own. */
distro: { id: string; name: string };
variant: 'container' | 'vm';
summary: string;
spacesd: boolean;
/** `false`: the guest cannot use GPU acceleration. */
gpu?: false;
/** Browsers the image ships; cua-driver's browser tools drive the Chromium-family ones. */
browsers: string[];
/** Platforms the image is published for. */
arch: Array<'amd64' | 'arm64'>;
/** Optional SDK constructor that names the image (`Image.linux()`). */
sdk?: string;
local: 'container' | 'qemu' | 'lume' | null;
cloud: 'gvisor' | 'kubevirt' | null;
published: boolean;
/** Canonical images: `slim`, `full` (the default, no tag suffix) or `xcode` (macOS). */
tier?: 'slim' | 'full' | 'xcode';
/** Optional docs path of the image's guide (benchmark images: their Cua Bench guide). */
guide?: string;
/** Benchmark images: the bench publisher's lock file (promoted tags and digests). */
lock?: string;
/** The published digest the moving tag was verified at (`sha256:<hex>`). */
digest?: string;
/** Benchmark images: the benchmarks the image runs, for the docs tables. */
benchmarks?: Benchmark[];
};
/** One benchmark a benchmark image runs. */
export type Benchmark = { name: string; what: string; tasks: number; guide: string };
export type SandboxImageList = {
schemaVersion: 1;
/** `picker: false` keeps a group out of pickers and the image tables (benchmark images). */
groups: Array<{ id: SandboxImage['group']; label: string; picker?: boolean }>;
images: SandboxImage[];
};
export const IMAGE_LIST_PATH = 'libs/images/sandbox-images.json';
const OPTIONAL_IMAGE_FIELDS = ['guide', 'lock', 'benchmarks', 'sdk', 'digest', 'sizes', 'tier', 'gpu', 'derived_from'];
/** The tag suffix each tier puts before `-disk`: `<os-version>[-<tier>][-disk]`. */
const TIER_SUFFIX: Record<string, string> = { slim: '-slim', full: '', xcode: '-xcode', docker: '-docker' };
/** Tiers that exist only as a VM disk (their rootfs never runs the tier's point, dockerd). */
const VM_ONLY_TIERS = new Set(['docker']);
const IMAGE_FIELDS = [
'ref',
'group',
'os',
'name',
'distro',
'variant',
'summary',
'spacesd',
'browsers',
'arch',
'local',
'cloud',
'published',
];
/** Parses and validates the shared image list; canonical entries must match canonical.rs. */
export function validateImageList(value: unknown, source: SourceFacts): SandboxImageList {
const root = value as Partial<SandboxImageList> & Record<string, unknown>;
if (root.schemaVersion !== 1 || !Array.isArray(root.images) || !Array.isArray(root.groups)) {
throw new Error(`${IMAGE_LIST_PATH}: expected schemaVersion 1 with groups and images`);
}
const groups = new Set(root.groups.map((g) => g.id));
const seen = new Set<string>();
for (const image of root.images) {
const record = image as unknown as Record<string, unknown>;
const keys = Object.keys(record)
.filter((k) => !OPTIONAL_IMAGE_FIELDS.includes(k))
.sort();
if (keys.join() !== [...IMAGE_FIELDS].sort().join()) {
throw new Error(`${IMAGE_LIST_PATH}: ${String(record.ref)} has fields ${keys.join(', ')}`);
}
if (!/^ghcr\.io\/trycua\/[a-z0-9-]+:[A-Za-z0-9._-]+$/.test(image.ref)) {
throw new Error(`${IMAGE_LIST_PATH}: ${image.ref} is not a ghcr.io/trycua tag`);
}
if (seen.has(image.ref)) throw new Error(`${IMAGE_LIST_PATH}: duplicate ${image.ref}`);
if (image.digest !== undefined && !/^sha256:[0-9a-f]{64}$/.test(image.digest)) {
throw new Error(`${IMAGE_LIST_PATH}: ${image.ref} digest must be sha256:<64 hex>`);
}
// Sizes are measured at the digest (scripts/images/record-image-sizes.py).
const sizes = (record.sizes ?? undefined) as { digest?: string } | undefined;
if ((sizes === undefined) !== (image.digest === undefined) || (sizes && sizes.digest !== image.digest)) {
throw new Error(
`${IMAGE_LIST_PATH}: ${image.ref} sizes must be measured at its digest (run python3 scripts/images/record-image-sizes.py)`,
);
}
seen.add(image.ref);
if (!groups.has(image.group)) {
throw new Error(`${IMAGE_LIST_PATH}: ${image.ref} has unknown group ${image.group}`);
}
if (!['linux', 'windows', 'macos'].includes(image.os)) {
throw new Error(`${IMAGE_LIST_PATH}: ${image.ref} has unknown os ${image.os}`);
}
const distro = image.distro as unknown as Record<string, unknown> | null;
if (
typeof distro !== 'object' ||
distro === null ||
Object.keys(distro).sort().join() !== 'id,name' ||
typeof distro.id !== 'string' ||
!/^[a-z0-9-]+$/.test(distro.id) ||
typeof distro.name !== 'string' ||
distro.name.trim() === ''
) {
throw new Error(`${IMAGE_LIST_PATH}: ${image.ref} distro must be { id, name }`);
}
if (!Array.isArray(image.browsers) || image.browsers.some((b) => typeof b !== 'string')) {
throw new Error(`${IMAGE_LIST_PATH}: ${image.ref} browsers must be a list of names`);
}
if (
!Array.isArray(image.arch) ||
image.arch.length === 0 ||
image.arch.some((a) => a !== 'amd64' && a !== 'arm64')
) {
throw new Error(`${IMAGE_LIST_PATH}: ${image.ref} arch must list amd64 and/or arm64`);
}
if (image.sdk !== undefined && !/^Image\.[a-z]+\(.*\)$/.test(image.sdk)) {
throw new Error(`${IMAGE_LIST_PATH}: ${image.ref} sdk ${image.sdk} is not an Image constructor`);
}
if (image.guide !== undefined && !/^\/[a-z0-9/#-]+$/.test(image.guide)) {
throw new Error(`${IMAGE_LIST_PATH}: ${image.ref} guide ${image.guide} is not a docs path`);
}
if (image.group === 'benchmark' && !/^ghcr\.io\/trycua\/bench-/.test(image.ref)) {
throw new Error(`${IMAGE_LIST_PATH}: benchmark image ${image.ref} is not a bench-* image`);
}
if (image.group === 'benchmark') {
if (!image.lock || !fs.existsSync(path.join(ROOT, image.lock))) {
throw new Error(`${IMAGE_LIST_PATH}: benchmark image ${image.ref} needs an existing lock file`);
}
const lock = JSON.parse(read(image.lock)) as { repository?: string };
if (lock.repository !== image.ref.split(':')[0]) {
throw new Error(`${IMAGE_LIST_PATH}: ${image.lock} is not the lock of ${image.ref}`);
}
} else if (image.lock !== undefined || image.benchmarks !== undefined) {
throw new Error(`${IMAGE_LIST_PATH}: only benchmark images have a lock or benchmarks`);
}
if (image.tier !== undefined) {
if (image.group !== 'canonical' || !(image.tier in TIER_SUFFIX)) {
throw new Error(`${IMAGE_LIST_PATH}: ${image.ref} tier must be slim, full, docker or xcode on a canonical image`);
}
if (image.tier === 'xcode' && image.os !== 'macos') {
throw new Error(`${IMAGE_LIST_PATH}: ${image.ref} the xcode tier is macOS only`);
}
if (image.tier === 'docker' && image.os !== 'linux') {
throw new Error(`${IMAGE_LIST_PATH}: ${image.ref} the docker tier is Linux only`);
}
const base = image.ref.split(':')[1].replace(/-disk$/, '');
const suffix = base.match(/-(slim|docker|xcode(-[0-9.]+)?)$/)?.[0] ?? '';
if (suffix.replace(/-[0-9.]+$/, '') !== TIER_SUFFIX[image.tier]) {
throw new Error(`${IMAGE_LIST_PATH}: ${image.ref} tag does not match tier ${image.tier}`);
}
}
for (const b of image.benchmarks ?? []) {
const keys = Object.keys(b).sort().join();
if (
keys !== 'guide,name,tasks,what' ||
!Number.isInteger(b.tasks) ||
!/^\/[a-z0-9/#-]+$/.test(b.guide)
) {
throw new Error(`${IMAGE_LIST_PATH}: ${image.ref} has an invalid benchmark ${JSON.stringify(b)}`);
}
}
}
const canonical = root.images
.filter((i) => i.group === 'canonical')
.map((i) => i.ref)
.sort();
const expected = [
source.linuxImage,
`${source.linuxImage}-disk`,
source.windowsImage,
`${source.windowsImage}-disk`,
`${source.linuxImage}-slim`,
`${source.linuxImage}-slim-disk`,
`${source.linuxImage}-docker`,
`${source.linuxImage}-docker-disk`,
source.macosTahoeImage,
`${source.macosTahoeImage}-slim`,
`${source.macosTahoeImage}-xcode`,
source.macosSequoiaImage,
].sort();
if (canonical.join() !== expected.join()) {
throw new Error(
`${IMAGE_LIST_PATH}: canonical images ${canonical.join(', ')} disagree with ${CANONICAL_RS} (${expected.join(', ')})`
);
}
return root as SandboxImageList;
}
export function loadImageList(source: SourceFacts = loadSourceFacts()): SandboxImageList {
return validateImageList(JSON.parse(read(IMAGE_LIST_PATH)), source);
}
/** The images every picker and the docs show: published entries, in file order. */
export function pickerImages(list: SandboxImageList): SandboxImage[] {
const offered = new Set(list.groups.filter((g) => g.picker !== false).map((g) => g.id));
return list.images.filter((image) => image.published && offered.has(image.group));
}
const LOCAL_RUNTIME: Record<string, string> = {
container: 'Container (gVisor when installed)',
qemu: 'QEMU VM',
lume: 'Lume VM (Apple silicon)',
};
const BROWSER_NAME: Record<string, string> = {
chromium: 'Chromium',
chrome: 'Google Chrome',
firefox: 'Firefox',
safari: 'Safari',
edge: 'Edge',
};
function browserName(id: string): string {
return BROWSER_NAME[id] ?? id;
}
export function renderImageList(list: SandboxImageList): string {
const lines = [
'| Image | Group | Name | Tier | Local | cua-spacesd | Browsers |',
'| --- | --- | --- | --- | --- | --- | --- |',
];
const label = new Map(list.groups.map((g) => [g.id, g.label]));
for (const image of pickerImages(list)) {
lines.push(
`| \`${image.ref}\` | ${label.get(image.group)} | ${image.guide ? `[${image.name}](${image.guide})` : image.name} | ${image.tier ?? '-'} | ${
image.local ? LOCAL_RUNTIME[image.local] : 'Not available'
} | ${image.spacesd ? 'Yes' : 'No'} | ${image.browsers.map(browserName).join(', ') || 'None'} |`
);
}
return lines.join('\n');
}
/**
* Every canonical tier, published or not: `<os-version>[-<tier>][-disk]`
* refs with the SDK call that names each one.
*/
export function renderTiers(list: SandboxImageList): string {
const lines = ['| Image | Tier | SDK | Status |', '| --- | --- | --- | --- |'];
// A VM-only tier (docker) is named by its disk; the others by their rootfs.
const named = (i: SandboxImage) =>
i.tier !== undefined && (VM_ONLY_TIERS.has(i.tier) ? i.ref.endsWith('-disk') : !i.ref.endsWith('-disk'));
for (const image of list.images.filter(named)) {
lines.push(
`| \`${image.ref}\` | ${image.tier} | ${image.sdk ? `\`${image.sdk}\`` : '-'} | ${
// An unpublished tier's ref is not pullable yet: the docs image-ref
// gate skips a line carrying the unverified marker.
image.published ? 'Published' : 'Not published yet {/* cua-image-unverified */}'
} |`
);
}
return lines.join('\n');
}
/** The published Cua images (not benchmarks): the table hand-written pages embed. */
export function renderCuaImages(list: SandboxImageList): string {
const lines = [
'| Image | Name | Local | cua-spacesd |',
'| --- | --- | --- | --- |',
];
for (const image of pickerImages(list)) {
lines.push(
`| \`${image.ref}\` | ${image.name} | ${image.local ? LOCAL_RUNTIME[image.local] : 'Not available'} | ${
image.spacesd ? 'Yes' : 'No'
} |`
);
}
return lines.join('\n');
}
/** Every benchmark a benchmark image runs, with its guide and the image's container tag. */
export function renderBenchmarks(list: SandboxImageList): string {
const lines = ['| Benchmark | What | Tasks | Image |', '| --- | --- | --- | --- |'];
for (const image of list.images.filter((i) => i.group === 'benchmark')) {
for (const b of image.benchmarks ?? []) {
lines.push(
`| [${b.name}](${b.guide}) | ${b.what} | ${b.tasks.toLocaleString('en-US')} | \`${image.ref}\` |`
);
}
}
return lines.join('\n');
}
const OS_HEADING: Record<SandboxImage['os'], string> = {
linux: 'Linux',
windows: 'Windows',
macos: 'macOS',
};
/** A 1-2 word label for a bullet, only where the ref alone is ambiguous. */
function imageLabel(image: SandboxImage): string {
if (image.os === 'macos') {
// "macOS Tahoe 26" -> "Tahoe"
return image.name.replace(/^macOS\s+/, '').replace(/\s+\d+$/, '');
}
return image.variant === 'vm' && image.ref.endsWith('-disk') ? 'VM' : '';
}
/**
* The images, terse: a heading per OS and one for benchmarks,
* one bullet per ref, a short label only where needed. Published Cua images
* and every benchmark image (its container tag links the guide).
*/
export function renderImageBullets(list: SandboxImageList): string {
const sections: Array<[string, string[]]> = [];
const push = (heading: string, line: string) => {
let section = sections.find(([h]) => h === heading);
if (!section) sections.push((section = [heading, []]));
section[1].push(line);
};
for (const image of pickerImages(list)) {
const label = imageLabel(image);
push(OS_HEADING[image.os], `- \`${image.ref}\`${label ? ` (${label})` : ''}`);
}
for (const image of list.images.filter((i) => i.group === 'benchmark')) {
const label = imageLabel(image);
const runs = (image.benchmarks ?? []).map((b) => `[${b.name}](${b.guide})`).join(', ');
const note = label || (runs ? `run ${runs}` : image.guide ? `[guide](${image.guide})` : '');
push('Adapter benchmark images', `- \`${image.ref}\`${note ? ` (${note})` : ''}`);
}
return sections.map(([h, lines]) => [`### ${h}`, '', ...lines].join('\n')).join('\n\n');
}
/**
* Regions hand-written docs pages embed: `GENERATED:<name>:start` and `:end`
* markers in MDX comments. Any page under docs/content may carry them, and
* the generator fills every one it finds.
*/
export const CATALOG_REGIONS: Record<string, (list: SandboxImageList) => string> = {
'catalog-cua-images': renderCuaImages,
'catalog-benchmarks': renderBenchmarks,
'catalog-image-list': renderImageBullets,
};
function walk(dir: string): string[] {
const out: string[] = [];
for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
const full = path.join(dir, entry.name);
if (entry.isDirectory()) out.push(...walk(full));
else if (entry.name.endsWith('.mdx')) out.push(full);
}
return out;
}
/** Fills every catalog region of `document`. */
export function fillCatalogRegions(document: string, list: SandboxImageList): string {
let out = document;
for (const [name, render] of Object.entries(CATALOG_REGIONS)) {
const start = `{/* GENERATED:${name}:start */}`;
const end = `{/* GENERATED:${name}:end */}`;
let from = 0;
for (;;) {
const i = out.indexOf(start, from);
if (i < 0) break;
const j = out.indexOf(end, i);
if (j < 0) throw new Error(`GENERATED:${name} has no end marker`);
const body = `${start}\n${render(list).trim()}\n${end}`;
out = out.slice(0, i) + body + out.slice(j + end.length);
from = i + body.length;
}
}
return out;
}
/** Hand-written pages with catalog regions, filled: path -> contents. */
export function catalogRegionDocuments(list: SandboxImageList): Map<string, string> {
const out = new Map<string, string>();
for (const f of walk(path.join(ROOT, 'docs/content/docs'))) {
const text = fs.readFileSync(f, 'utf8');
if (!text.includes('GENERATED:catalog-')) continue;
out.set(f, fillCatalogRegions(text, list));
}
return out;
}
function row(columns: string[]): string {
return `| ${columns.join(' | ')} |`;
}
export function renderCatalog(manifest: SandboxFactsManifest, source: SourceFacts): string {
const legacyAgent =
'Ships the legacy `cua-computer-server` guest agent, not cua-spacesd; reach it through services you declare.';
const lumeAgentless =
'`cua sb exec`, `cua sb screenshot` and `cua sb view` (and `sb.shell`, `sb.screen`) reach it without cua-spacesd, over SSH and VNC.';
const rows = [
row([
'Linux',
'Ubuntu 24.04, amd64 and arm64',
'XFCE on Xvfb, HTML5 viewer on 3211 (`/viewer/`)',
'Container (Docker or Podman, gVisor when installed); `kind="vm"`: the `-disk` containerDisk (QEMU)',
`\`${source.linuxImage}\``,
`\`Image.linux()\` default. Built from \`libs/images/linux\`; ships cua-spacesd on 3211 (service \`env\`). The resolver pins the digest.`,
]),
];
for (const image of manifest.qualifiedImages) {
rows.push(
row([
image.os,
image.distribution,
image.desktop,
image.kind,
`\`${image.image}\``,
`Deployment qualification recorded boot and readiness for \`server:${image.services.server}\` and \`mcp:${image.services.mcp}\` with \`cua-computer-server\` ${image.components.computerServer} (legacy guest agent) and embedded Driver ${image.components.embeddedDriver}; direct Driver qualification used ${image.components.directDriver}. The \`cua-sandbox\` interfaces need cua-spacesd, which this artifact does not ship; use its declared services directly.`,
])
);
}
for (const image of manifest.publishedCandidates) {
rows.push(
row([
image.os,
image.distribution,
image.desktop,
image.kind,
`\`${image.image}\``,
image.limits,
])
);
}
rows.push(
row([
'Windows',
'Server 2022, amd64',
'Native Windows desktop',
'VM from the `-disk` containerDisk (QEMU); EFI firmware',
`\`${source.windowsImage}\``,
`\`Image.windows()\` default. Ships cua-spacesd (a logon task in the desktop session) with input through the Windows cua-driver.`,
]),
row([
'macOS',
'Tahoe 26',
'Native macOS desktop',
'Local Lume VM',
`\`${source.macosTahoeImage}\``,
`\`Image.macos()\` default (full tier; \`tier="slim"\` for \`:26-slim\`). Compatible Apple silicon host required. Built from \`libs/images/macos\`; ships cua-spacesd at login on 3211 (service \`env\`), gated on \`cua-spacesd doctor --strict\` and the accessibility probe. The resolver pins the digest.`,
]),
row([
'macOS',
'Sequoia 15',
'Native macOS desktop',
'Local Lume VM',
`\`${source.macosSequoiaImage}\``,
`\`Image.macos("15")\`. Compatible Apple silicon host required. ${legacyAgent} ${lumeAgentless}`,
])
);
return `| OS | Distribution / version / architecture | Desktop / window manager | Image kind / runtime | Registry image or source | Evidence / limits |
| --- | --- | --- | --- | --- | --- |
${rows.join('\n')}`;
}
export function generateDocuments(): Map<string, string> {
const manifest = loadManifest();
const source = loadSourceFacts();
assertQualificationSources(manifest, source);
let runtime = fs.readFileSync(RUNTIME_TEMPLATE, 'utf8');
runtime = replaceGeneratedSection(
runtime,
'sandbox-package-facts',
renderRuntimePackageFacts(source)
);
runtime = replaceGeneratedSection(
runtime,
'sandbox-builtin-mappings',
renderBuiltinMappings(source)
);
runtime = replaceGeneratedSection(runtime, 'sandbox-evidence', renderEvidence(source));
let catalog = fs.readFileSync(CATALOG_TEMPLATE, 'utf8');
catalog = replaceGeneratedSection(
catalog,
'sandbox-image-catalog',
renderCatalog(manifest, source)
);
catalog = replaceGeneratedSection(catalog, 'sandbox-image-list', renderImageList(loadImageList(source)));
catalog = replaceGeneratedSection(catalog, 'sandbox-image-tiers', renderTiers(loadImageList(source)));
const list = loadImageList(source);
const page = (title: string, description: string, body: string) =>
renderPage({ title, description, generator: GENERATOR, source: SOURCE, version: `cua ${source.cuaVersion}`, body });
return new Map([
[
RUNTIME_DOC,
page(
'Runtime support',
'Which images run on which local runtime, what customization each accepts, and how ports reach them.',
runtime
),
],
[
CATALOG_DOC,
page('Image catalog details', 'Every image variant, its runtimes, guest services and limits.', catalog),
],
[
SOFTWARE_DOC,
page(
"What's installed",
'The apps, tools and simulator runtimes each image tier ships, as the strict doctor measured them.',
renderSoftware(
loadInventories(path.join(ROOT, SOFTWARE_DIR)),
list.images
.filter((i) => i.group === 'canonical' && i.spacesd && !i.ref.endsWith('-disk'))
.map((i) => ({ ref: i.ref, published: i.published }))
)
),
],
...catalogRegionDocuments(list),
]);
}
function main(): void {
const { values } = parseArgs({ options: { check: { type: 'boolean' } } });
const generated = generateDocuments();
let drift = false;
for (const [file, contents] of generated) {
const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;
if (current === contents) continue;
if (values.check) {
console.error(`Generated Sandbox documentation is stale: ${path.relative(ROOT, file)}`);
drift = true;
} else {
fs.mkdirSync(path.dirname(file), { recursive: true });
fs.writeFileSync(file, contents);
console.log(`Generated ${path.relative(ROOT, file)}`);
}
}
if (drift) process.exitCode = 1;
else if (values.check) console.log('Sandbox package and image facts are up to date.');
}
if (require.main === module) main();