dreamteamer 0.28.0 → 0.29.0

package/collections/collections.collection.yaml

@@ -67,6 +67,15 @@ schema:
             have lived in `modules/<module>/<kind>/` since the 2026-08-05 flatten, and a `system/`
             prefix is only how `runtime.js` recognises a RUNTIME collection in a descriptor compiled
             by a pre-flatten engine.
+        driver:
+          type: string
+          description: >-
+            The name of an engine DRIVER that answers this collection's verbs instead of a folder of
+            files — `docker` is the one shipped (src/containers.js: `containers`, `images`). A driver
+            collection has no records on disk: its derived `path` names a folder that never exists,
+            so check, commit and the store read zero records and never write one; the CLI and the REST
+            route dispatch to the driver first. A string checked against the drivers the engine has,
+            not an enum — one implementation, and a second is a code change, not a vocabulary change.
         codec:
           type: string
           enum: [md, yaml, json, file]

package/collections/containers.collection.yaml

@@ -0,0 +1,81 @@
+name: containers
+description: >-
+  A workspace running as a container — one person's editor, harness and compiled workspace over a
+  named volume set, answered over the Docker Engine API rather than from a folder of files.
+use_when: >-
+  a workspace has to RUN somewhere for someone — `dt start container <name> --template <t>` makes
+  one and prints its editor URL; `dt list containers` says what is running and where; `stop`, `open`,
+  `rm` are the lifecycle. Not a record: nothing lands under data/, nothing is committed, and Docker
+  keeps the history
+# MACHINERY WITH A DRIVER, NOT A RECORD COLLECTION. `storage.driver: docker` says every verb on this
+# collection is answered by src/containers.js over the Engine API: `list` is GET /containers/json,
+# `get` is an inspect, `add`/`start` create-and-start, `rm` removes. The derived storage.path names a
+# folder that never exists, so every walker (check, commit, the store's index) reads zero records here
+# and never writes one; the REST route and the CLI dispatch to the driver before the store is asked.
+# `group: system` folds it out of the orientation block's domain listing, beside `repos` and the
+# compiled kinds, which is where a stranger's mental model puts "the thing my workspace runs in".
+storage:
+  driver: docker
+schema:
+  type: object
+  required: [name, template]
+  properties:
+    # ---- identity ----
+    name:
+      type: string
+      description: The workspace name — also the container name and the stem of its three volumes (`dreamteamer-<name>-workspace` · `-home` · `-files`).
+    template:
+      type: string
+      description: The template it was made from — an image carrying `dreamteamer.template`, `dreamteamer.ports` and `dreamteamer.modules` labels; `--template hq` resolves to `<DT_REGISTRY>/hq:<DT_TEMPLATE_TAG>` or to `DT_IMAGE_hq`.
+    image:
+      type: string
+      description: The image reference the container runs.
+    id:
+      type: string
+      description: Docker's short id.
+    # ---- runtime ----
+    state:
+      type: string
+      enum: [created, running, paused, restarting, exited, dead]
+      description: Docker's container state.
+    status:
+      type: string
+      description: Docker's own phrase — `Up 2 hours`, `Exited (0) 3 minutes ago`.
+    started:
+      type: string
+      format: date-time
+      description: When it last started.
+    # ---- network ----
+    editor_url:
+      type: string
+      description: Where the person opens the editor — `http://localhost:<port>/?folder=<workspace dir>`; the host port comes from DT_PORT_BASE upward, bound to DT_BIND (127.0.0.1).
+    port:
+      type: integer
+      description: The host port the editor is published on.
+    bind:
+      type: string
+      description: The host address it is bound to — loopback unless the host .env says otherwise.
+    # ---- storage ----
+    workspace_dir:
+      type: string
+      description: Where the workspace is mounted inside — `/workspaces/<name>`, the dev-container convention.
+    volumes:
+      type: object
+      description: The three named volumes — `workspace` (the repo), `home` (the person's logins and editor settings), `files` (FILES_FOLDER). Plain `rm` keeps them; `rm --force` removes them.
+    mounts:
+      type: array
+      items: { type: string }
+      description: Extra bind or volume mounts passed as `--mount <host-path|volume>:<container-path>[:ro]`.
+    # ---- person ----
+    person:
+      type: string
+      description: Whose container this is — the git identity injected as env; the harness login happens INSIDE, once, and is never injected.
+    # ---- provenance ----
+    created:
+      type: string
+      format: date-time
+      description: When Docker created it.
+order: 146
+list_fields: [name, template, state, editor_url, person]
+icon: deployed_code
+group: system

package/collections/images.collection.yaml

@@ -0,0 +1,46 @@
+name: images
+description: >-
+  A template a workspace container is made from — a Docker image carrying the `dreamteamer.template`,
+  `dreamteamer.ports` and `dreamteamer.modules` labels — as the local Docker holds it.
+use_when: >-
+  choosing what a container runs — `dt list images` shows the templates present, `dt add image
+  --template <t>` pulls one, `dt rm image <ref>` removes one; a template is an IMAGE WITH LABELS, not
+  a record here, so there is nothing to author — publish an image with the labels and it appears
+# The second driver-backed collection (see containers.collection.yaml for what that means). `list` is
+# GET /images/json filtered to the template label, `get` an inspect, `add --template` a pull, `rm` a
+# delete. No records, no folder, no commit.
+storage:
+  driver: docker
+schema:
+  type: object
+  required: [image]
+  properties:
+    # ---- identity ----
+    image:
+      type: string
+      description: The image reference — `<registry>/<template>:<tag>`.
+    template:
+      type: string
+      description: The `dreamteamer.template` label — the word `--template` takes.
+    id:
+      type: string
+      description: Docker's image id.
+    # ---- what it runs ----
+    ports:
+      type: string
+      description: The `dreamteamer.ports` label — the in-container port the editor listens on (8080 by convention).
+    modules:
+      type: string
+      description: The `dreamteamer.modules` label — the modules the template installs, comma-separated.
+    # ---- size and time ----
+    size_mb:
+      type: integer
+      description: Image size in megabytes.
+    created:
+      type: string
+      format: date
+      description: When the image was built.
+order: 147
+list_fields: [template, image, size_mb, created]
+icon: layers
+group: system

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dreamteamer",
-	"version": "0.28.0",
+	"version": "0.29.0",
 	"description": "A workspace compiler for coding agents — schema-validated records as plain files over git, compiled into every harness",
 	"license": "Apache-2.0",
 	"author": "Gilad Khen <giladkhen@gmail.com>",

package/src/cli.js

@@ -247,15 +247,22 @@ workspace verbs:
 containers — a workspace as a running container (Docker Engine API over its socket, no dependency;
 these verbs work with NO workspace, so npm i -g dreamteamer and Docker Desktop are enough):
   setup       make THIS MACHINE ready: checks Docker, writes ~/.dreamteamer/.env with its defaults
-              (DT_PORT_BASE 8100 · DT_BIND 127.0.0.1 · DT_REGISTRY · DT_TEMPLATE_TAG), lists the
-              templates present, pulls one on request [--template <t>] [--json]
+              (DT_PORT_BASE 8100 · DT_BIND 127.0.0.1 · DT_REGISTRY · DT_TEMPLATE_TAG ·
+              DT_DOCKER_TIMEOUT 30 — seconds a request to Docker may sit idle before the verb
+              fails), lists the templates present, pulls one on request [--template <t>] [--json]
   start       container <name> --template <t>   create-if-absent and start: a code-server editor at
               http://localhost:<port>/?folder=/workspace over a compiled workspace, three named volumes
               (workspace · home · files), image <DT_REGISTRY>/<template>:<tag> or DT_IMAGE_<template>.
-              Idempotent. NO token is ever injected — log in INSIDE, once; the home volume keeps it.
+              The workspace is mounted at /workspaces/<name>. Idempotent. NO token is ever injected —
+              log in INSIDE, once; the home volume keeps it.
+              [--repo <git url>]  clone an EXISTING workspace into the volume on first start, instead
+                                  of laying the template down — how a person joins one on GitHub
+              [--mount <host-path|volume>:<container-path>[:ro]]  extra mounts, repeatable
               [--name <git name>] [--email <git email>] [--no-open] [--json]
   stop        container <name>                  stop it; every volume kept [--json]
   open        container <name>                  print (and open) its editor URL [--no-open]
+              [--vscode]  print (and open) the Dev Containers attach URI instead — the host's own
+                          VS Code inside the container, extensions from the image's metadata label
   list        containers | images               the record verbs, answered over Docker instead of a
   get         container <name> | image <ref>    folder — singular or plural, either spelling.
   rm          container <name> [--force]        plain rm keeps the volumes; --force removes them too
@@ -318,7 +325,7 @@ export const WORKSPACE_FLAGS = {
 	// `start` is TWO forms: bare, the REST api (--port); with a `container <name>` target, the
 	// lifecycle verb — whose flags are the driver's. One table, because `flags-honoured` reads it.
 	start: ['port', ...CONTAINER_FLAGS], compile: ['watch'], check: [], status: ['strict'],
-	setup: ['template', 'json'], stop: ['json'], open: ['json', 'no-open'],
+	setup: ['template', 'json'], stop: ['json'], open: ['json', 'no-open', 'vscode'],
 	changes: ['since', 'json'], commit: ['dry-run', 'json'],
 	export: EXPORT_FLAGS,
 	// the UNION of every form's flags — the outer typo gate. Which flags each FORM takes is refused

package/src/containers.js

@@ -21,6 +21,14 @@
 // `.dreamteamer/collections` either — these two nouns resolve HERE, ahead of workspace discovery,
 // so `dt list containers` answers identically inside a workspace and on a bare host.
 //
+// EVERY REQUEST CARRIES A TIMER. Docker Desktop paused, or still starting, ACCEPTS the socket and
+// says nothing — and a client with no timer then hangs every verb, and everything waiting on it,
+// forever (measured 2026-09-24: a fake that accepts and never answers held `dt list containers`
+// until the harness killed it at 20 s). So `api()` sets an IDLE timer of `DT_DOCKER_TIMEOUT`
+// seconds (default 30, host `.env` or env) on the socket: idle, not total, so a pull that keeps
+// streaming progress lines is never cut off, while a silent daemon fails the verb with the knob
+// named. `DT_HEALTH_TIMEOUT` (default 90) bounds the other wait, code-server's /healthz.
+//
 // TEST KNOBS, stated once: `DT_DOCKER_SOCKET` points the client at any socket (a fake in tests);
 // `DT_HOME` relocates `~/.dreamteamer`; `DT_HEALTH_TIMEOUT=0` skips the wait for code-server's
 // /healthz. None is documented in help — they are how the suite drives this file without Docker.
@@ -54,8 +62,9 @@ export function driverTarget(word) {
 export const HOST_DEFAULTS = {
 	DT_PORT_BASE: '8100',       // NOT 8080: that is code-server's in-container port, `dt start`'s REST default, and the old dev image's exposed port — three things on one number
 	DT_BIND: '127.0.0.1',       // loopback only; a remote tier puts auth in front before this changes
-	DT_REGISTRY: 'dreamteamer', // `<registry>/<template>:<tag>` is the image a template name resolves to
+	DT_REGISTRY: 'ghcr.io/dreamteamer', // `<registry>/<template>:<tag>` is the image a template name resolves to — the public images repo publishes here
 	DT_TEMPLATE_TAG: 'latest',
+	DT_DOCKER_TIMEOUT: '30',    // seconds a request to Docker may sit IDLE before the verb fails — see the header
 };
 
 export function hostDir() { return process.env.DT_HOME ?? path.join(os.homedir(), '.dreamteamer'); }
@@ -87,8 +96,15 @@ function unreachable(sock) {
 
 /** One request. Resolves { status, body } where body is parsed JSON when the response is JSON,
  *  else the raw text. `onLine` receives each JSON line of a streaming response (a pull). */
+/** Seconds a request may sit idle before it fails; 0 disables — `DT_DOCKER_TIMEOUT`, env over file over default. */
+export function dockerTimeoutSeconds() {
+	const n = Number(hostEnv().DT_DOCKER_TIMEOUT);
+	return Number.isFinite(n) && n >= 0 ? n : Number(HOST_DEFAULTS.DT_DOCKER_TIMEOUT);
+}
+
 export function api(method, urlPath, body, { onLine } = {}) {
 	const sock = socketPath();
+	const seconds = dockerTimeoutSeconds();
 	return new Promise((resolve, reject) => {
 		const payload = body === undefined ? undefined : JSON.stringify(body);
 		const req = http.request({
@@ -114,6 +130,9 @@ export function api(method, urlPath, body, { onLine } = {}) {
 			});
 		});
 		req.on('error', (e) => reject(e.code === 'ENOENT' || e.code === 'ECONNREFUSED' ? unreachable(sock) : e));
+		// idle-based: fires only when NOTHING has moved on the socket for `seconds` — a streaming
+		// pull resets it with every progress line, a paused daemon never does
+		if (seconds) req.setTimeout(seconds * 1000, () => req.destroy(new Error(`${method} ${urlPath}: Docker did not answer within ${seconds}s — is Docker Desktop paused or still starting? DT_DOCKER_TIMEOUT=<seconds> in ${path.join(hostDir(), '.env')} changes the wait (0 disables it)`)));
 		if (payload) req.write(payload);
 		req.end();
 	});
@@ -126,7 +145,7 @@ function ok(res, what) {
 	throw new Error(`${what}: Docker answered ${res.status}${msg ? ` — ${msg}` : ''}`);
 }
 
-const LABEL = { workspace: 'dreamteamer.workspace', template: 'dreamteamer.template', person: 'dreamteamer.person', ports: 'dreamteamer.ports', modules: 'dreamteamer.modules' };
+const LABEL = { workspace: 'dreamteamer.workspace', template: 'dreamteamer.template', person: 'dreamteamer.person', ports: 'dreamteamer.ports', modules: 'dreamteamer.modules', workdir: 'dreamteamer.workdir' };
 const filters = (label) => encodeURIComponent(JSON.stringify({ label: [label] }));
 
 // ---- images ------------------------------------------------------------------------------------
@@ -177,11 +196,29 @@ const containerRow = (c) => {
 	const port = (c.Ports ?? []).find((p) => p.PublicPort)?.PublicPort;
 	return {
 		name, template: c.Labels?.[LABEL.template] ?? '', state: c.State, status: c.Status,
-		editor_url: port ? editorUrl(port) : '', image: c.Image, person: c.Labels?.[LABEL.person] ?? '',
+		editor_url: port ? editorUrl(port, name) : '', image: c.Image, person: c.Labels?.[LABEL.person] ?? '',
 		created: c.Created ? new Date(c.Created * 1000).toISOString().slice(0, 16).replace('T', ' ') : '', id: c.Id,
 	};
 };
-const editorUrl = (port) => `http://localhost:${port}/?folder=/workspace`;
+/** The dev-container convention: the workspace is mounted at `/workspaces/<name>`, so the folder the
+ *  editor opens, the URL, and a VS Code attach all name the workspace rather than a fixed word. */
+export const workspaceDir = (name) => `/workspaces/${name}`;
+const editorUrl = (port, name) => `http://localhost:${port}/?folder=${workspaceDir(name)}`;
+/** `--mount <host-path|volume>:<container-path>[:ro]` → a Docker Mount. A source starting with `/`,
+ *  `~` or `.` is a bind mount of a host path (resolved against cwd); anything else is a named volume. */
+export function parseMount(spec) {
+	const parts = String(spec).split(':');
+	if (parts.length < 2 || parts.length > 3 || !parts[0] || !parts[1].startsWith('/')) throw new Error(`--mount takes <host-path|volume>:<container-path>[:ro] — got "${spec}"`);
+	const [src, target, mode] = parts;
+	if (mode !== undefined && mode !== 'ro' && mode !== 'rw') throw new Error(`--mount "${spec}": the third part is ro or rw`);
+	const isPath = /^[/~.]/.test(src);
+	const source = isPath ? path.resolve(src.replace(/^~(?=\/|$)/, os.homedir())) : src;
+	if (!isPath && !/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(src)) throw new Error(`--mount "${spec}": "${src}" is neither a path nor a volume name`);
+	return { Type: isPath ? 'bind' : 'volume', Source: source, Target: target, ReadOnly: mode === 'ro' };
+}
+/** The URI VS Code on the host opens to attach to this container (Dev Containers extension). The
+ *  container name is hex-encoded, as the extension spells it. */
+export const attachUri = (name) => `vscode-remote://attached-container+${Buffer.from(name, 'utf8').toString('hex')}${workspaceDir(name)}`;
 const volumeNames = (name) => ({ workspace: `dreamteamer-${name}-workspace`, home: `dreamteamer-${name}-home`, files: `dreamteamer-${name}-files` });
 
 export async function listContainers() {
@@ -200,14 +237,21 @@ export async function inspectContainer(name) {
 /** The shape `dt get container <name>` prints: the categorised view over `docker inspect`. */
 export function containerDetail(c) {
 	const binding = Object.values(c.HostConfig?.PortBindings ?? {}).flat()[0];
+	const name = c.Name.replace(/^\//, '');
+	const wsDir = c.Config.Labels?.[LABEL.workdir] ?? workspaceDir(name);
+	const own = new Set([wsDir, '/home/node', '/files']);
 	const mounts = Object.fromEntries((c.Mounts ?? []).filter((m) => m.Type === 'volume').map((m) => [m.Destination, m.Name]));
 	return {
-		name: c.Name.replace(/^\//, ''), id: c.Id.slice(0, 12),
+		name, id: c.Id.slice(0, 12),
 		template: c.Config.Labels[LABEL.template] ?? '', image: c.Config.Image,
 		state: c.State?.Status, started: c.State?.StartedAt, restarts: c.RestartCount ?? 0,
 		bind: binding?.HostIp ?? '', port: binding ? Number(binding.HostPort) : undefined,
-		editor_url: binding ? editorUrl(binding.HostPort) : '',
-		volumes: { workspace: mounts['/workspace'] ?? '', home: mounts['/home/node'] ?? '', files: mounts['/files'] ?? '' },
+		editor_url: binding ? editorUrl(binding.HostPort, name) : '',
+		attach_uri: attachUri(name),
+		workspace_dir: wsDir,
+		volumes: { workspace: mounts[wsDir] ?? '', home: mounts['/home/node'] ?? '', files: mounts['/files'] ?? '' },
+		mounts: (c.Mounts ?? []).filter((m) => !own.has(m.Destination)).map((m) => `${m.Type === 'bind' ? m.Source : m.Name}:${m.Destination}${m.RW === false ? ':ro' : ''}`),
+		repo: (c.Config.Env ?? []).find((e) => e.startsWith('DT_REPO='))?.slice(8) ?? '',
 		person: c.Config.Labels[LABEL.person] ?? '', created: c.Created, labels: c.Config.Labels,
 	};
 }
@@ -254,11 +298,21 @@ export async function startContainer(name, flags, log = console.log) {
 		const port = await allocatePort(env);
 		const who = person(flags, env);
 		const vols = volumeNames(name);
+		const wsDir = workspaceDir(name);
+		// `--mount` adds bind or volume mounts beside the three the container always has; a mount aimed
+		// at one of those three targets is refused rather than silently shadowing the volume.
+		const extra = (flags.mount ?? []).map(parseMount);
+		for (const m of extra) if ([wsDir, '/home/node', '/files'].includes(m.Target)) throw new Error(`--mount cannot target ${m.Target} — that is one of the container's own volumes (${wsDir} · /home/node · /files)`);
+		// `--repo <url>` clones an EXISTING workspace into the workspace volume on first start instead of
+		// laying the template down — the way a person joins a workspace that already lives on GitHub.
+		const repo = typeof flags.repo === 'string' ? flags.repo : undefined;
+		if (repo !== undefined && !/^(https?:\/\/|git@|ssh:\/\/|file:\/\/|\/)/.test(repo)) throw new Error(`--repo takes a git URL or an absolute path — got "${repo}"`);
 		const body = {
 			Image: ref,
-			Labels: { [LABEL.workspace]: name, [LABEL.template]: template, [LABEL.person]: who.name },
+			Labels: { [LABEL.workspace]: name, [LABEL.template]: template, [LABEL.person]: who.name, [LABEL.workdir]: wsDir },
 			Env: [
-				`DT_WORKSPACE=${name}`, `DT_TEMPLATE=${template}`, 'FILES_FOLDER=/files',
+				`DT_WORKSPACE=${name}`, `DT_TEMPLATE=${template}`, `DT_WORKSPACE_DIR=${wsDir}`, 'FILES_FOLDER=/files',
+				...(repo ? [`DT_REPO=${repo}`] : []),
 				...(who.name ? [`GIT_AUTHOR_NAME=${who.name}`, `GIT_COMMITTER_NAME=${who.name}`] : []),
 				...(who.email ? [`GIT_AUTHOR_EMAIL=${who.email}`, `GIT_COMMITTER_EMAIL=${who.email}`] : []),
 			],
@@ -266,16 +320,17 @@ export async function startContainer(name, flags, log = console.log) {
 			HostConfig: {
 				PortBindings: { [`${inner}/tcp`]: [{ HostIp: env.DT_BIND, HostPort: String(port) }] },
 				Mounts: [
-					{ Type: 'volume', Source: vols.workspace, Target: '/workspace' },
+					{ Type: 'volume', Source: vols.workspace, Target: wsDir },
 					{ Type: 'volume', Source: vols.home, Target: '/home/node' },
 					{ Type: 'volume', Source: vols.files, Target: '/files' },
+					...extra,
 				],
 				RestartPolicy: { Name: 'unless-stopped' },
 			},
 		};
 		ok(await api('POST', `/containers/create?name=${encodeURIComponent(name)}`, body), `create container ${name}`);
 		c = await inspectContainer(name);
-		log(`✔ created ${name} from ${ref} · ${env.DT_BIND}:${port} → ${inner} · volumes ${Object.values(vols).join(', ')}`);
+		log(`✔ created ${name} from ${ref} · ${env.DT_BIND}:${port} → ${inner} · ${wsDir} · volumes ${Object.values(vols).join(', ')}${extra.length ? ` · mounts ${extra.map((m) => `${m.Source}→${m.Target}${m.ReadOnly ? ' (ro)' : ''}`).join(', ')}` : ''}${repo ? ` · clones ${repo} on first start` : ''}`);
 	}
 	if (c.State?.Status !== 'running') {
 		const res = await api('POST', `/containers/${c.Id}/start`);
@@ -399,7 +454,20 @@ export async function driverCommand(verb, target, args) {
 	if (verb === 'get') { const c = await inspectContainer(id); if (!c) throw new Error(`no container "${id}" — dt list containers`); emit(JSON.stringify(json ? c : containerDetail(c), null, 2)); return 0; }
 	if (verb === 'start' || verb === 'add') { const d = await startContainer(id, flags); if (json) emit(JSON.stringify(d, null, 2)); return 0; }
 	if (verb === 'stop') { const d = await stopContainer(id); console.log(`✔ stopped ${id} · volumes kept`); if (json) emit(JSON.stringify(d, null, 2)); return 0; }
-	if (verb === 'open') { const c = await inspectContainer(id); if (!c) throw new Error(`no container "${id}"`); const d = containerDetail(c); if (!d.editor_url) throw new Error(`${id} publishes no port`); console.log(d.editor_url); if (!flags['no-open']) openUrl(d.editor_url); return 0; }
+	if (verb === 'open') {
+		const c = await inspectContainer(id); if (!c) throw new Error(`no container "${id}"`);
+		const d = containerDetail(c);
+		if (flags.vscode) {
+			// Dev Containers attach: the host's own VS Code opens the workspace INSIDE the container, and
+			// installs the extensions the image's `devcontainer.metadata` label names into the container's
+			// VS Code Server — a second extension host beside code-server's, over the same files.
+			console.log(d.attach_uri);
+			if (!flags['no-open']) { try { spawn('code', ['--folder-uri', d.attach_uri], { stdio: 'ignore', detached: true }).unref(); } catch { /* the URI is printed either way */ } }
+			return 0;
+		}
+		if (!d.editor_url) throw new Error(`${id} publishes no port`);
+		console.log(d.editor_url); if (!flags['no-open']) openUrl(d.editor_url); return 0;
+	}
 	if (verb === 'rm') { await removeContainer(id, { force: flags.force === true }); return 0; }
 	return 1;
 }
@@ -408,15 +476,17 @@ export async function driverCommand(verb, target, args) {
  *  record parser's promotion rules — a repeated flag on these verbs is a mistake, not an array. */
 export function parseFlags(args) {
 	const flags = {}; const pos = [];
+	// `--mount` is the one flag that repeats — every other repeat is a mistake and the LAST wins.
+	const put = (k, v) => { if (k === 'mount') flags.mount = [...(flags.mount ?? []), v]; else flags[k] = v; };
 	for (let i = 0; i < args.length; i++) {
 		const a = args[i];
 		if (!a.startsWith('--')) { pos.push(a); continue; }
 		const eq = a.indexOf('=');
-		if (eq > -1) flags[a.slice(2, eq)] = a.slice(eq + 1);
-		else if (i + 1 < args.length && !args[i + 1].startsWith('--')) flags[a.slice(2)] = args[++i];
-		else flags[a.slice(2)] = true;
+		if (eq > -1) put(a.slice(2, eq), a.slice(eq + 1));
+		else if (i + 1 < args.length && !args[i + 1].startsWith('--')) put(a.slice(2), args[++i]);
+		else put(a.slice(2), true);
 	}
 	return { flags, pos };
 }
 
-export const CONTAINER_FLAGS = ['template', 'name', 'email', 'no-open', 'json', 'force'];
+export const CONTAINER_FLAGS = ['template', 'name', 'email', 'no-open', 'json', 'force', 'mount', 'repo', 'vscode'];

package/src/harnesses.js

@@ -295,6 +295,7 @@ function buildCollectionsIndex(entries) {
 			// the domain listing — the visible failure rather than the silent one.
 			systemGroup: d.group === 'system',
 			generated: d.storage?.base === 'runtime',
+			driver: d.storage?.driver ?? null,
 			description: flat(d.description),
 			useWhen: flat(d.use_when),
 			module: d.module ?? '',
@@ -418,7 +419,10 @@ function collectionsSection(index, modules, workspaceModule) {
 	}
 	const sys = index.filter((c) => c.systemGroup);
 	const system = sys.filter((c) => c.generated).map((c) => c.name);
-	const kept = sys.filter((c) => !c.generated).map((c) => c.name);
+	const kept = sys.filter((c) => !c.generated && !c.driver).map((c) => c.name);
+	// A DRIVER collection is neither build output nor files: its verbs are answered by a driver over
+	// something that runs (Docker), so it gets its own clause rather than being called either.
+	const driven = sys.filter((c) => c.driver).map((c) => `${c.name} (${c.driver})`);
 	// ⚠ THIS LINE IS THE FIRST THING A SESSION READS about the system collections, and until 0.19.0
 	// it said "schema-ops only", which named an internal module and a grammar that no longer exists.
 	// It now names the VERBS and the one policy difference, because an agent that knows the verbs
@@ -428,7 +432,7 @@ function collectionsSection(index, modules, workspaceModule) {
 	// told "it is build output" — a sentence that was false of it and is false of the next data-backed
 	// system collection too, since the split is derived rather than naming one.
 	if (sys.length) {
-		lines.push('', `- system collections — the SAME verbs (add · set · rm · rename · list · get), plus \`dt add-field\`/\`set-field\`/\`rm-field\`/\`rename-field <collection>\`. A system write COMMITS ITSELF, in the repo holding the source; a record write does not (\`dt commit\` publishes).${system.length ? ` Never hand-edit \`.dreamteamer/\` — it is build output: ${system.join(' · ')}.` : ''}${kept.length ? ` Machinery whose records are real files you edit like any other: ${kept.join(' · ')}` : ''}`);
+		lines.push('', `- system collections — the SAME verbs (add · set · rm · rename · list · get), plus \`dt add-field\`/\`set-field\`/\`rm-field\`/\`rename-field <collection>\`. A system write COMMITS ITSELF, in the repo holding the source; a record write does not (\`dt commit\` publishes).${system.length ? ` Never hand-edit \`.dreamteamer/\` — it is build output: ${system.join(' · ')}.` : ''}${kept.length ? ` Machinery whose records are real files you edit like any other: ${kept.join(' · ')}.` : ''}${driven.length ? ` Answered by a DRIVER, not files — nothing under data/, nothing to commit, the same verbs plus start · stop · open: ${driven.join(' · ')}` : ''}`);
 	}
 	return lines;
 }

package/src/schema-ops.js

@@ -754,6 +754,7 @@ const COLLECTION_SETTABLE = {
 	use_when: (v) => String(v),
 	title: (v) => String(v),
 	title_template: (v) => String(v),
+	singular: (v) => String(v), // the word the CLI accepts beside the name; compile refuses a collision
 	icon: (v) => String(v),
 	// The collection's partition. `group=system` is the reserved value: it moves the collection out
 	// of the block's domain listing and onto a surface's schema surface, and changes nothing about

package/src/server.js

@@ -22,6 +22,7 @@ import { sortRows } from './temporal.js';
 import { placementKey } from './fractional-index.js';
 import { commandsFor, recordResolver } from './record-commands.js';
 import { distinctValues } from './field-values.js';
+import { listContainers, listImages, inspectContainer, inspectImage, containerDetail } from './containers.js';
 
 
 export function startServer(ws, { port = 8080, host = '127.0.0.1' } = {}) {
@@ -77,6 +78,33 @@ export function startServer(ws, { port = 8080, host = '127.0.0.1' } = {}) {
 	// wildcard, a literal and a second wildcard in one pattern, so `/collections/a/b/records/c` has
 	// several readings and the router picks one. Encoding keeps the boundary explicit at the caller,
 	// which is the same reason references declare their namespace instead of having it inferred.
+	// A DRIVER collection (`storage.driver: docker`) has no records on disk: list and get are answered
+	// by the driver, and every write is refused with the verb that does it — the same interception the
+	// CLI performs, at the same surface, so the extension's tree and record views work without either
+	// side learning Docker. Wrapped in `driven` so an unreachable daemon is a 502 with its sentence,
+	// not a 500 from the store looking for a folder that never exists.
+	const driverOf = (name) => store.descriptors.get(name)?.storage?.driver;
+	const driven = (fn) => (req, res, next) => {
+		if (!driverOf(req.params.name)) return next();
+		fn(req, res).catch((e) => res.status(502).json({ error: e.message }));
+	};
+	api.get('/collections/:name/records', driven(async (req, res) => {
+		const rows = req.params.name === 'images' ? await listImages() : await listContainers();
+		res.json({ records: rows.map((r) => ({ ...r, id: r.name ?? r.image })), total: rows.length });
+	}));
+	api.get('/collections/:name/records/*id', driven(async (req, res) => {
+		const id = idParam(req);
+		const fields = req.params.name === 'images' ? await inspectImage(id) : (await inspectContainer(id).then((c) => c && containerDetail(c)));
+		if (!fields) return res.status(404).json({ error: `no ${req.params.name === 'images' ? 'image' : 'container'} "${id}"` });
+		res.json({ id, fields, path: null });
+	}));
+	for (const [method, route] of [['post', '/collections/:name/records'], ['patch', '/collections/:name/records/*id'], ['delete', '/collections/:name/records/*id'], ['patch', '/collections/:name/position/*id'], ['post', '/collections/:name/rename']]) {
+		api[method](route, (req, res, next) => {
+			if (!driverOf(req.params.name)) return next();
+			const noun = req.params.name === 'images' ? 'image' : 'container';
+			res.status(405).json({ error: `"${req.params.name}" is a ${driverOf(req.params.name)} driver collection — it is written with the CLI, not as a record: dt start ${noun} <name> --template <t> · dt stop ${noun} <name> · dt rm ${noun} <name>` });
+		});
+	}
 	api.get('/collections/:name/records', (req, res) => {
 		const d = store.descriptor(req.params.name);
 		const bf = bodyField(d);