dreamteamer 0.28.0 → 0.30.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 machine — `http://localhost:<port>/`, its home (every workspace, create, clone); the host port comes from DT_PORT_BASE upward, bound to DT_BIND (127.0.0.1). Never carries the image's URL token — `dt open container <name>` prints the URL that does.
+    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]` — targets under /workspaces · /home/node · /files · /mnt only, none at or under another mount's target (the own volumes included), and no bind source inside another.
+    # ---- 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.30.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

@@ -17,6 +17,7 @@ import { compile, staleness, warnIfStale, discoverModules, CHANNEL_LABEL, locati
 import { check } from './check.js';
 import { collectionCommand, emit, relationsCommand, parseArgs, refuseUnknownFlags } from './collections-cli.js';
 import { driverTarget, driverCommand, setup as hostSetup, parseFlags as hostFlags, DRIVER_VERBS, LIFECYCLE_VERBS, CONTAINER_FLAGS } from './containers.js';
+import { archiveCommand } from './container-archive.js';
 import { init, installClone, update, listRepos } from './init.js';
 import { installCommand, describeCheckout, listWorktrees, worktreeCommand } from './checkout.js';
 import { proveCommand, readLedger, flagEnabled } from './prove.js';
@@ -247,19 +248,47 @@ 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.
+              http://localhost:<port>/ — the machine home — over a compiled workspace, three named
+              volumes (workspace · home · files), its own bridge network dreamteamer-<name>, image
+              <DT_REGISTRY>/<template>:<tag> or DT_IMAGE_<template>. The workspace is mounted at
+              /workspaces/<name>. Idempotent. NO credential is ever injected — log in INSIDE, once;
+              the home volume keeps it. An image with a URL token (hq 0.6+) prints the URL as
+              ?tkn=<token>, read from the container; the token is never written on the host.
+              [--rotate-token]    replace the image's URL token and print the new URL
+              [--workspace [<w>]] open /workspaces/<w> (default: its own) instead of the home
+              [--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; targets
+                                  under /workspaces · /home/node · /files · /mnt, none at or under
+                                  another mount's target, no bind source inside another
               [--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]
+  open        container <name>                  print (and open) its URL, token included [--no-open] [--json]
+              [--workspace [<w>]]
+              [--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
+  rm          container <name> [--force]        removes it and its network; keeps the volumes unless --force
   add         image --template <t>              pull a template's image; rm image <ref> removes one
+  export      container <name> --out <file>     its WORKSPACES as one file — every folder under
+              /workspaces, never the home or a login; node_modules and .files stay behind. Works on
+              a stopped container. Encrypted with the owner passphrase (DT_EXPORT_PASSPHRASE, else a
+              prompt — never a flag). [--workspace <w>]... only these  [--no-encrypt] a plain .tar.gz
+              [--json] (both verbs) the summary as JSON on stdout, every other line on stderr
+              Secrets stay behind: .env and .env.* (not .example/.sample/.template), .envrc,
+              .npmrc, .netrc, .git-credentials, .pypirc, .docker/config.json, and the credentials in
+              each .git/config. [--with-secrets] carries them unchanged
+  import      container <name> <file>           unpack an export into a RUNNING container, owned by
+              node. Refuses a wrong passphrase, a damaged file, an entry leaving its workspace and a
+              workspace already holding files — each before anything is written.
+              [--workspace <w>]... only these  [--replace] empty a workspace that holds files first
+              [--as <name>] land the ONE workspace in /workspaces/<name> — e.g. another container's
+                            own volume folder (dt-new's name rule; never the container's own layer)
 
   changes     what changed in every repo that holds records, as record events
               [--since <sha|YYYY-MM-DD>] (default: HEAD~1 — the last commit's own changes) [--json]
@@ -318,7 +347,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', 'workspace'],
 	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
@@ -791,6 +820,9 @@ function hostDispatch(cmd, rest) {
 		return hostSetup(hostFlags(rest).flags);
 	}
 	const target = driverTarget(rest[0]);
+	// `export container` is the driver's; `export notebooklm` stays the workspace verb below
+	if (target && (cmd === 'export' || cmd === 'import')) return archiveCommand(cmd, target, rest.slice(1));
+	if (cmd === 'import') return Promise.reject(new Error('dt import container <name> <file> [--workspace <w>]... [--replace]'));
 	if (target && DRIVER_VERBS.has(cmd)) return driverCommand(cmd, target, rest.slice(1));
 	// A lifecycle verb aimed at anything else is refused by name: `dt start tasks` is not a
 	// server and not a container, and "unknown collection" would send the reader the wrong way.

package/src/container-archive.js

@@ -0,0 +1,356 @@
+// container-archive.js — `dt export container` and `dt import container`: a machine's WORKSPACES out
+// of one container and into another, as one file. The move primitive between two laptops (and, when
+// the other side implements docs/container-export-format.md, between a laptop and a hosted machine).
+//
+// WHAT TRAVELS. The trees under /workspaces, one folder per workspace — never the home, so never a
+// login: there is no flag that adds it. `node_modules` and `.files` folders stay behind at any depth
+// (a reinstall and a files folder are both per-machine). Hard links, devices and fifos are skipped on
+// the way out and REFUSED on the way in, with setuid bits and owners dropped both ways: this file
+// writes every tar header itself rather than passing Docker's through.
+//
+// NO SECRETS BY DEFAULT (principle 8: an export strips them unless the owner asks). Every `.env` and
+// `.git-credentials` stays behind, and each `.git/config` travels with the userinfo cut from its
+// http(s) URLs and its `extraheader` lines (where CI tooling parks a token) dropped. `--with-secrets`
+// carries all of it unchanged and says so. Encryption is on either way.
+//
+// WHY THE TAR IS PARSED HERE. The Engine API speaks tar both ways (GET/PUT …/archive) and cannot
+// filter, re-root or check it. Node has gzip and AES-GCM but no tar, and the subset needed — ustar
+// headers, PAX and GNU long names in, ustar plus PAX out — is ~60 lines, against a dependency.
+//
+// ENCRYPTED BY DEFAULT, under the owner's passphrase: scrypt (N=2^17) → AES-256-GCM over 64 KiB
+// chunks, each with its own nonce and tag and the LAST one marked, so a flipped byte, a dropped chunk
+// and a truncated file all fail authentication. The header carries an HMAC under the derived key, so
+// a wrong passphrase is told apart from damage before a single byte is decrypted. The passphrase comes
+// from DT_EXPORT_PASSPHRASE (the process env only, never ~/.dreamteamer/.env) or a no-echo prompt —
+// never a flag, because every local user's `ps` reads argv.
+//
+// IMPORT WRITES NOTHING until the whole file has been read once: pass 1 authenticates every chunk and
+// checks every entry (no absolute path, no `..`, no symlink leaving its workspace, no link or device),
+// pass 2 uploads. Then `chown -R node:node` on the imported folders, as root, by exec.
+import fs from 'node:fs';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import crypto from 'node:crypto';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { api, ok, inspectContainer, exec, parseFlags } from './containers.js';
+import { emit } from './collections-cli.js';
+
+const ROOT = '/workspaces';
+const WS_NAME = /^[a-z0-9][a-z0-9_.-]*$/;
+// `--as` names a NEW folder, so it takes dt-new's rule (hq image, new-workspace.sh), reserved words included
+const NEW_NAME = /^[a-z0-9][a-z0-9-]{0,39}$/;
+const RESERVED = new Set(['files', 'lost-found', 'trash']);
+const LEFT_BEHIND = new Set(['node_modules', '.files']);
+// credential files by NAME, at any depth: `.env` and every `.env.*` but the three template spellings,
+// and the dotfiles package managers and git keep tokens in — docs/container-export-format.md
+const SECRET_FILES = new Set(['.env', '.envrc', '.npmrc', '.netrc', '.git-credentials', '.pypirc']);
+const ENV_TEMPLATES = new Set(['.env.example', '.env.sample', '.env.template']);
+export const isSecretFile = (segs) => { const b = segs[segs.length - 1]; return SECRET_FILES.has(b) || (b.startsWith('.env.') && !ENV_TEMPLATES.has(b)) || (b === 'config.json' && segs[segs.length - 2] === '.docker'); };
+/** A `.git/config` minus its credentials: every `[credential]` / `[credential "…"]` section dropped
+ *  (an inline `!` helper can hold a password), every `extraheader` line dropped (where CI parks a
+ *  token), and the userinfo cut from every http(s) URL — values and `[url "…"]` section names alike. */
+export function stripGitConfig(text) {
+	let drop = false;
+	const kept = text.split(/(?<=\n)/).filter((line) => {
+		const head = /^\s*\[\s*([^\]\s."]+)/.exec(line);
+		if (head) drop = head[1].toLowerCase() === 'credential';
+		return !drop && !/^\s*extraheader\s*=/i.test(line);
+	});
+	return kept.join('').replace(/(https?:\/\/)[^@/\s"\]]*@/gi, '$1');
+}
+const FILE = '0', DIR = '5', SYMLINK = '2';
+const FLAGS = { export: ['workspace', 'out', 'no-encrypt', 'with-secrets', 'json'], import: ['workspace', 'replace', 'as', 'json'] };
+
+// ---- tar: read any of ustar · PAX · GNU long names, write ustar (+ PAX when a name is long) -------
+const str = (b, o, n) => { const e = b.indexOf(0, o); return b.toString('utf8', o, e === -1 || e > o + n ? o + n : e); };
+const num = (b, o, n) => (b[o] & 0x80 ? b.readUIntBE(o + n - 6, 6) : parseInt(str(b, o, n).trim() || '0', 8)); // base-256 above 8 GiB
+const sum = (h) => { let s = 0; for (let i = 0; i < 512; i++) s += i >= 148 && i < 156 ? 32 : h[i]; return s; };
+const pad = (n) => (512 - (n % 512)) % 512;
+export const TAR_END = Buffer.alloc(1024);
+
+function header({ name, type, mode, size, mtime, linkname = '' }) {
+	const h = Buffer.alloc(512);
+	const oct = (v, o, n) => h.write(`${Math.floor(v).toString(8).padStart(n - 1, '0')}\0`, o, n, 'latin1');
+	h.write(name, 0, 100); oct(mode, 100, 8); oct(0, 108, 8); oct(0, 116, 8);
+	if (size < 8 ** 11) oct(size, 124, 12); else { h[124] = 0x80; h.writeUIntBE(size, 130, 6); }
+	oct(mtime, 136, 12); h.write(type, 156, 1, 'latin1'); h.write(linkname, 157, 100); h.write('ustar\u000000', 257, 8, 'latin1');
+	oct(sum(h), 148, 7); h[155] = 32;
+	if (Buffer.byteLength(name) <= 100 && Buffer.byteLength(linkname) <= 100) return h;
+	// a PAX record's length counts its own digits
+	const rec = (k, v) => { const body = ` ${k}=${v}\n`; const n = Buffer.byteLength(body); return `${n + String(n + String(n).length).length}${body}`; };
+	const pax = Buffer.from(rec('path', name) + (linkname ? rec('linkpath', linkname) : ''));
+	return Buffer.concat([header({ name: 'PaxHeader', type: 'x', mode: 0o644, size: pax.length, mtime }), pax, Buffer.alloc(pad(pax.length)), h]);
+}
+
+/** Re-emit a tar: `decide(entry)` answers the name to write it under, or null to drop it, or
+ *  { name, rewrite } to replace a small file's body. Headers are rewritten (owner 0, permission bits
+ *  only); bodies stream through. No end marker — the caller adds one. */
+export async function* retar(source, decide) {
+	const it = source[Symbol.asyncIterator]();
+	let buf = Buffer.alloc(0);
+	const fill = async (n) => { while (buf.length < n) { const r = await it.next(); if (r.done) return false; buf = buf.length ? Buffer.concat([buf, r.value]) : r.value; } return true; };
+	const take = async (n) => { if (!(await fill(n))) throw new Error('the archive ends in the middle of an entry'); const b = buf.subarray(0, n); buf = buf.subarray(n); return b; };
+	let ext = {};
+	for (;;) {
+		if (!(await fill(512))) throw new Error('the archive ends without its end marker');
+		const h = await take(512);
+		if (h.every((b) => b === 0)) return;
+		if (num(h, 148, 8) !== sum(h)) throw new Error('an archive header fails its checksum');
+		const type = h[156] ? String.fromCharCode(h[156]) : FILE;
+		let size = num(h, 124, 12);
+		if ('xgLK'.includes(type)) {
+			if (size > 1 << 20) throw new Error('an archive extension header is over 1 MiB');
+			const body = (await take(size + pad(size))).subarray(0, size);
+			if (type === 'L') ext.path = str(body, 0, size);
+			else if (type === 'K') ext.linkpath = str(body, 0, size);
+			else if (type === 'x') for (const m of body.toString('utf8').matchAll(/\d+ ([^=]+)=([^\n]*)\n/g)) ext[m[1]] = m[2];
+			continue;
+		}
+		const prefix = str(h, 345, 155);
+		const e = { name: ext.path ?? (prefix ? `${prefix}/${str(h, 0, 100)}` : str(h, 0, 100)), linkname: ext.linkpath ?? str(h, 157, 100), type: type === '7' ? FILE : type, mode: num(h, 100, 8) & 0o777, mtime: num(h, 136, 12) };
+		size = ext.size !== undefined ? Number(ext.size) : size;
+		e.size = e.type === FILE ? size : 0;
+		ext = {};
+		const d = decide(e);
+		if (d?.rewrite && e.type === FILE && size <= 1 << 20) {
+			const body = d.rewrite((await take(size + pad(size))).subarray(0, size));
+			yield header({ ...e, name: d.name, size: body.length }); yield body; yield Buffer.alloc(pad(body.length));
+			continue;
+		}
+		const name = d?.name ?? d;
+		if (name) yield header({ ...e, name });
+		const keep = name && e.type === FILE; // only a file's body is written; any other entry's is read past
+		for (let left = size + pad(size); left > 0;) {
+			if (!(await fill(1))) throw new Error('the archive ends in the middle of a file');
+			const b = buf.subarray(0, Math.min(left, buf.length)); buf = buf.subarray(b.length); left -= b.length;
+			if (keep) yield b;
+		}
+	}
+}
+
+// ---- the sealed format (docs/container-export-format.md) ---------------------------------------
+const MAGIC = Buffer.from('DTEXPORT');
+const HEAD = 40, MAC = 32, CHUNK = 64 * 1024;
+const KDF = { log2N: 17, r: 8, p: 1 }; // the ONLY parameters v1 writes or reads — see openSeal
+
+function scryptKeys(pass, salt, log2N, r, p) {
+	return new Promise((resolve, reject) => crypto.scrypt(pass.normalize('NFC'), salt, 64, { N: 2 ** log2N, r, p, maxmem: 256 * 2 ** log2N * r * p }, (e, k) => (e ? reject(e) : resolve({ enc: k.subarray(0, 32), mac: k.subarray(32) }))));
+}
+const hmac = (key, b) => crypto.createHmac('sha256', key).update(b).digest();
+const nonce = (prefix, i, last) => { const n = Buffer.alloc(12); prefix.copy(n); n.writeUInt32BE(i, 7); n[11] = last ? 1 : 0; return n; };
+
+async function newSeal(pass) {
+	const h = Buffer.alloc(HEAD);
+	MAGIC.copy(h); h[8] = 1; h[9] = KDF.log2N; h[10] = KDF.r; h[11] = KDF.p; h.writeUInt32BE(CHUNK, 12);
+	crypto.randomFillSync(h, 16, 23); // salt 16..31 · nonce prefix 32..38 · 39 reserved
+	const keys = await scryptKeys(pass, h.subarray(16, 32), KDF.log2N, KDF.r, KDF.p);
+	return { keys, head: Buffer.concat([h, hmac(keys.mac, h)]) };
+}
+
+/** Parse and authenticate a header — a wrong passphrase fails HERE, before any chunk is opened.
+ *  The KDF parameters are read BEFORE the MAC can be checked (the MAC needs the key they derive), so
+ *  they are an attacker's to choose: only the exact values this version writes are accepted, before
+ *  scrypt runs and before the passphrase is even asked for (`pass` may be a function that asks). */
+export async function openSeal(file, pass) {
+	const fd = fs.openSync(file, 'r');
+	const h = Buffer.alloc(HEAD + MAC);
+	const n = fs.readSync(fd, h, 0, h.length, 0); fs.closeSync(fd);
+	if (n < h.length) throw new Error(`${file} is too short to be an encrypted export`);
+	if (h[8] !== 1) throw new Error(`${file} is export format version ${h[8]} — this engine reads version 1; upgrade dreamteamer`);
+	const [log2N, r, p, chunk] = [h[9], h[10], h[11], h.readUInt32BE(12)];
+	if (log2N !== KDF.log2N || r !== KDF.r || p !== KDF.p || chunk !== CHUNK) throw new Error(`${file}: its header asks for scrypt N=2^${log2N} r=${r} p=${p} and ${chunk}-byte chunks — version 1 is exactly N=2^${KDF.log2N} r=${KDF.r} p=${KDF.p}, ${CHUNK}; refusing these parameters before any work`);
+	const keys = await scryptKeys(typeof pass === 'function' ? await pass() : pass, h.subarray(16, 32), log2N, r, p);
+	if (!crypto.timingSafeEqual(hmac(keys.mac, h.subarray(0, HEAD)), h.subarray(HEAD))) throw new Error(`wrong passphrase for ${file} (or its header is damaged) — nothing was written`);
+	return { keys, prefix: h.subarray(32, 39), chunk };
+}
+
+async function* seal(src, { keys, head }) {
+	const prefix = head.subarray(32, 39);
+	const box = (pt, i, last) => { const c = crypto.createCipheriv('aes-256-gcm', keys.enc, nonce(prefix, i, last)); return Buffer.concat([c.update(pt), c.final(), c.getAuthTag()]); };
+	yield head;
+	let buf = Buffer.alloc(0), i = 0;
+	for await (const b of src) { buf = Buffer.concat([buf, b]); while (buf.length > CHUNK) { yield box(buf.subarray(0, CHUNK), i++, false); buf = buf.subarray(CHUNK); } }
+	yield box(buf, i, true); // a final chunk always exists, empty or not — its flag is what makes truncation visible
+}
+
+async function* unseal(src, { keys, prefix, chunk }) {
+	const open = (b, i, last) => {
+		const d = crypto.createDecipheriv('aes-256-gcm', keys.enc, nonce(prefix, i, last));
+		d.setAuthTag(b.subarray(b.length - 16));
+		try { return Buffer.concat([d.update(b.subarray(0, b.length - 16)), d.final()]); } catch { throw new Error(`the export is damaged or truncated (chunk ${i} fails authentication) — nothing was written`); }
+	};
+	let buf = Buffer.alloc(0), i = 0;
+	for await (const b of src) { buf = Buffer.concat([buf, b]); while (buf.length > chunk + 16) { yield open(buf.subarray(0, chunk + 16), i++, false); buf = buf.subarray(chunk + 16); } }
+	if (buf.length < 16) throw new Error('the export is truncated (its last chunk is missing) — nothing was written');
+	yield open(buf, i, true);
+}
+
+// ---- the passphrase: env or a no-echo prompt, never argv -----------------------------------------
+async function passphrase({ confirm }) {
+	let v = process.env.DT_EXPORT_PASSPHRASE;
+	if (v === undefined) {
+		if (!process.stdin.isTTY) throw new Error('an encrypted export needs the owner passphrase — set DT_EXPORT_PASSPHRASE, or run in a terminal to be asked (it is never a flag); --no-encrypt writes a plain .tar.gz');
+		v = await ask('passphrase: ');
+		if (confirm && (await ask('again: ')) !== v) throw new Error('the two passphrases differ — nothing was written');
+	}
+	if (confirm && v.length < 8) throw new Error('the passphrase must be at least 8 characters');
+	if (!v) throw new Error('the passphrase is empty');
+	return v;
+}
+
+function ask(prompt) {
+	return new Promise((resolve, reject) => {
+		const s = process.stdin; let v = '';
+		const done = (f) => { s.off('data', on); s.setRawMode(false); s.pause(); process.stderr.write('\n'); f(); };
+		const on = (d) => {
+			for (const ch of d) {
+				if (ch === '\r' || ch === '\n') return done(() => resolve(v));
+				if (ch === '\u0003' || ch === '\u0004') return done(() => reject(new Error('cancelled — nothing was written')));
+				v = ch === '\u007f' || ch === '\b' ? v.slice(0, -1) : v + ch;
+			}
+		};
+		process.stderr.write(prompt); s.setRawMode(true); s.setEncoding('utf8'); s.on('data', on); s.resume();
+	});
+}
+
+// ---- export --------------------------------------------------------------------------------------
+export async function exportContainer(name, flags, log = console.log) {
+	const out = typeof flags.out === 'string' ? path.resolve(flags.out) : null;
+	if (!out) throw new Error(`dt export container ${name} --out <file> — where the export is written`);
+	if (fs.existsSync(out)) throw new Error(`${out} already exists — name a new file`);
+	const only = flags.workspaces ?? [];
+	for (const w of only) if (typeof w !== 'string' || !WS_NAME.test(w)) throw new Error(`--workspace takes a workspace folder name under ${ROOT} — got "${w}"`);
+	const c = await inspectContainer(name);
+	if (!c) throw new Error(`no container "${name}" — dt list containers`);
+	const encrypt = flags['no-encrypt'] !== true;
+	const secrets = flags['with-secrets'] === true;
+	const sealer = encrypt ? await newSeal(await passphrase({ confirm: true })) : null;
+	// one read of the root, or one per named workspace so the others never leave the container
+	const sources = only.length ? only.map((w) => ({ at: `${ROOT}/${w}`, strip: '' })) : [{ at: ROOT, strip: `${path.posix.basename(ROOT)}/` }];
+	const stats = new Map(); const left = new Set(); const skipped = [];
+	const decide = (strip) => (e) => {
+		const rel = e.name.slice(strip.length).replace(/\/+$/, '');
+		if (!e.name.startsWith(strip) || !rel) return null;
+		const segs = rel.split('/');
+		if (segs.some((s) => LEFT_BEHIND.has(s))) { left.add(segs.slice(0, segs.findIndex((s) => LEFT_BEHIND.has(s)) + 1).join('/')); return null; }
+		if (!WS_NAME.test(segs[0]) || (segs.length === 1 && e.type !== DIR)) { if (segs.length === 1) skipped.push(`${rel} (not a workspace folder)`); return null; }
+		if (!secrets && isSecretFile(segs) && e.type !== DIR) { left.add(rel); return null; }
+		if (![FILE, DIR, SYMLINK].includes(e.type)) { skipped.push(`${rel} (${e.type === '1' ? 'hard link' : 'device or fifo'})`); return null; }
+		const s = stats.get(segs[0]) ?? { files: 0, bytes: 0 }; stats.set(segs[0], s);
+		if (e.type === FILE) { s.files++; s.bytes += e.size; }
+		if (!secrets && e.type === FILE && rel.endsWith('/.git/config')) return { name: rel, rewrite: (b) => Buffer.from(stripGitConfig(b.toString('utf8'))) };
+		return e.type === DIR ? `${rel}/` : rel;
+	};
+	async function* tar() {
+		for (const s of sources) {
+			const r = await api('GET', `/containers/${c.Id}/archive?path=${encodeURIComponent(s.at)}`, undefined, { stream: true });
+			if (r.status === 404) throw new Error(`${name} has no ${s.at}`);
+			ok(r, `read ${s.at} from ${name}`);
+			yield* retar(r.res, decide(s.strip));
+		}
+		yield TAR_END;
+	}
+	const tmp = `${out}.partial`;
+	// an interrupted export leaves nothing: not a half file that looks like a whole one, not ciphertext
+	const onSignal = (sig) => { fs.rmSync(tmp, { force: true }); process.exit(sig === 'SIGINT' ? 130 : 143); };
+	process.once('SIGINT', onSignal); process.once('SIGTERM', onSignal);
+	try {
+		await pipeline(Readable.from(tar()), zlib.createGzip(), ...(sealer ? [(src) => seal(src, sealer)] : []), fs.createWriteStream(tmp, { flags: 'wx', mode: 0o600 }));
+		fs.renameSync(tmp, out);
+	} catch (e) { fs.rmSync(tmp, { force: true }); throw e; } finally { process.off('SIGINT', onSignal); process.off('SIGTERM', onSignal); }
+	if (!stats.size) { fs.rmSync(out); throw new Error(`${name} holds no workspace folder under ${ROOT} — nothing was written`); }
+	for (const [w, s] of stats) log(`  ${w}  ${s.files} files · ${(s.bytes / 1e6).toFixed(1)} MB`);
+	if (left.size) log(`  left behind: ${[...left].join(' · ')}`);
+	for (const s of skipped) log(`  skipped: ${s}`);
+	if (secrets) log('⚠ --with-secrets: every credential file (.env*, .npmrc, .netrc, …) and .git/config credential is INCLUDED, unchanged — whoever opens this file holds them');
+	else log('  secrets left out: credential files (.env*, .envrc, .npmrc, .netrc, .git-credentials, .pypirc, .docker/config.json); credentials cut from .git/config (--with-secrets keeps them)');
+	log(`✔ exported ${stats.size} workspace(s) from ${name} to ${out} · ${encrypt ? 'encrypted with the owner passphrase' : 'NOT encrypted (--no-encrypt): a plain .tar.gz anyone holding the file can read'}`);
+	return { container: name, out, encrypted: encrypt, with_secrets: secrets, workspaces: [...stats].map(([w, s]) => ({ name: w, ...s })), left_behind: [...left], skipped };
+}
+
+// ---- import --------------------------------------------------------------------------------------
+/** The name to upload an entry under — re-rooted at `as` when given — null to leave it out
+ *  (`--workspace`), or a refusal. `found` collects the SOURCE workspace names. */
+function checkEntry(e, only, found, as) {
+	const name = e.name.replace(/^(\.\/)+/, '');
+	const rel = name.replace(/\/+$/, '');
+	const segs = rel.split('/');
+	const refuse = (why) => { throw new Error(`the export holds "${e.name}", which ${why} — nothing was written`); };
+	if (name.startsWith('/')) refuse('is an absolute path');
+	if (segs.some((s) => s === '..' || s === '.' || s === '')) refuse(`leaves ${ROOT}`);
+	if (!WS_NAME.test(segs[0]) || (segs.length === 1 && e.type !== DIR)) refuse(`is not inside a workspace folder`);
+	if (![FILE, DIR, SYMLINK].includes(e.type)) refuse(`is a ${e.type === '1' ? 'hard link' : 'device, fifo or unknown entry'}`);
+	const dest = [as ?? segs[0], ...segs.slice(1)].join('/');
+	if (e.type === SYMLINK) {
+		const own = `${ROOT}/${as ?? segs[0]}`;
+		const to = path.posix.resolve(path.posix.dirname(`${ROOT}/${dest}`), e.linkname);
+		if (to !== own && !to.startsWith(`${own}/`)) refuse(`is a symlink to ${e.linkname}, outside its workspace`);
+	}
+	if (only.size && !only.has(segs[0])) return null;
+	found.add(segs[0]);
+	if (segs.length === 2 && segs[1] === 'package.json' && e.type === FILE) found.add(`${segs[0]}/package.json`);
+	return e.type === DIR ? `${dest}/` : dest;
+}
+
+export async function importContainer(name, file, flags, log = console.log) {
+	if (!file) throw new Error(`dt import container ${name} <file>`);
+	const c = await inspectContainer(name);
+	if (!c) throw new Error(`no container "${name}" — dt list containers`);
+	if (c.State?.Status !== 'running') throw new Error(`${name} is ${c.State?.Status} — import needs it running: dt start container ${name}`);
+	const head = Buffer.alloc(8); { const fd = fs.openSync(file, 'r'); fs.readSync(fd, head, 0, 8, 0); fs.closeSync(fd); }
+	const sealed = head.equals(MAGIC);
+	if (!sealed && !(head[0] === 0x1f && head[1] === 0x8b)) throw new Error(`${file} is neither a dreamteamer export nor a .tar.gz`);
+	const key = sealed ? await openSeal(file, () => passphrase({ confirm: false })) : null;
+	if (!sealed) log(`… ${file} is NOT encrypted — reading it as a plain .tar.gz`);
+	const only = new Set(flags.workspaces ?? []);
+	const as = flags.as;
+	if (as !== undefined && (typeof as !== 'string' || !NEW_NAME.test(as) || RESERVED.has(as))) throw new Error(`--as takes a workspace name: 1–40 of a-z, 0-9 and '-', starting with a letter or digit, not files · lost-found · trash (got "${as === true ? '' : as}")`);
+	const read = (found) => [fs.createReadStream(file, { start: sealed ? HEAD + MAC : 0 }), ...(key ? [(src) => unseal(src, key)] : []), zlib.createGunzip(),
+		async function* (src) { yield* retar(src, (e) => checkEntry(e, only, found, as)); yield TAR_END; }];
+	// pass 1: every chunk authenticated and every entry checked before anything is written
+	const found = new Set();
+	await pipeline(...read(found), async (src) => { for await (const _ of src); });
+	const installs = [...found].filter((w) => w.endsWith('/package.json')).map((w) => `${ROOT}/${as ?? w.split('/')[0]}`);
+	for (const w of [...found]) if (w.includes('/')) found.delete(w);
+	const missing = [...only].filter((w) => !found.has(w));
+	if (missing.length) throw new Error(`the export holds no workspace ${missing.join(', ')} — it holds ${[...found].join(', ') || 'none'}`);
+	if (!found.size) throw new Error(`${file} holds no workspace`);
+	if (as && found.size !== 1) throw new Error(`--as names ONE workspace, and the export holds ${[...found].join(', ')} — pick it with --workspace <w>`);
+	const targets = as ? [`${ROOT}/${as}`] : [...found].map((w) => `${ROOT}/${w}`);
+	// a folder on the container's own layer vanishes with the container — the rule dt-new keeps
+	const mounts = (await exec(name, ['cat', '/proc/mounts'])).stdout.split('\n').map((l) => l.split(' ')).filter((m) => m[1]);
+	for (const t of targets) {
+		const m = mounts.filter(([, at]) => t === at || t.startsWith(at === '/' ? '/' : `${at}/`)).sort((a, b) => b[1].length - a[1].length)[0];
+		if (!m || ['overlay', 'tmpfs', 'ramfs'].includes(m[2])) throw new Error(`${t} would land on ${m ? m[2] : 'an unknown filesystem'}, not a volume, and vanish with the container — import into the container whose own workspace it is (dt start container <w> makes ${ROOT}/<w> a volume). Nothing was written`);
+	}
+	const full = [];
+	for (const t of targets) { const r = await exec(name, ['find', t, '-mindepth', '1', '-maxdepth', '1', '-print', '-quit']); if (r.code === 0 && r.stdout.trim()) full.push(t); }
+	if (full.length && flags.replace !== true) throw new Error(`${full.join(', ')} already hold${full.length === 1 ? 's' : ''} files in ${name} — --replace empties and replaces ${full.length === 1 ? 'it' : 'them'}. Nothing was written`);
+	for (const t of full) { const r = await exec(name, ['find', t, '-mindepth', '1', '-delete'], { user: 'root' }); if (r.code !== 0) throw new Error(`emptying ${t} failed (exit ${r.code}) — ${r.stderr.trim()}`); }
+	// pass 2: the same checks again on the way up, so a file changed between the passes is still refused
+	await pipeline(...read(new Set()), async (src) => ok(await api('PUT', `/containers/${c.Id}/archive?path=${encodeURIComponent(ROOT)}&noOverwriteDirNonDir=true`, undefined, { send: Readable.from(src) }), `write ${ROOT} in ${name}`));
+	const own = await exec(name, ['chown', '-R', 'node:node', ...targets], { user: 'root' });
+	if (own.code !== 0) throw new Error(`chown of ${targets.join(' ')} failed (exit ${own.code}) — ${own.stderr.trim()}`);
+	log(`✔ imported ${targets.join(', ')} into ${name}${full.length ? ` · replaced ${full.join(', ')}` : ''} · owned by node`);
+	// principle 3: an install runs code the workspace chose (lifecycle scripts, a pinned engine), so
+	// import names the step and the person takes it
+	if (installs.length) log(`next, in ${installs.join(', ')}: npm ci && npx dreamteamer compile — import ran neither (both run code the workspace chose)`);
+	return { container: name, imported: targets, replaced: full, next: installs };
+}
+
+/** `dt export|import container <name> …` → exit code. */
+export async function archiveCommand(verb, target, args) {
+	const { flags, pos } = parseFlags(args);
+	if ('passphrase' in flags) throw new Error('the passphrase is never a flag (every local user\'s `ps` reads argv) — set DT_EXPORT_PASSPHRASE, or let the prompt ask');
+	const bad = Object.keys(flags).find((f) => f !== 'workspaces' && !FLAGS[verb].includes(f));
+	if (bad) throw new Error(`unknown flag "--${bad}" on \`dt ${verb} container\` — known: ${FLAGS[verb].map((f) => `--${f}`).join(', ')}`);
+	const name = target.id ?? pos.shift();
+	if (target.collection !== 'containers' || !name) throw new Error(verb === 'export' ? 'dt export container <name> [--workspace <w>]... --out <file> [--no-encrypt]' : 'dt import container <name> <file> [--workspace <w>]... [--replace]');
+	// the driver's rule: under --json stdout carries ONLY the JSON, every human line goes to stderr
+	const json = flags.json === true;
+	const say = json ? console.error : console.log;
+	const r = verb === 'export' ? await exportContainer(name, flags, say) : await importContainer(name, pos[0], flags, say);
+	if (json) emit(JSON.stringify(r, null, 2));
+	return 0;
+}

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.
@@ -29,6 +37,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { execFileSync, spawn } from 'node:child_process';
+import { pipeline } from 'node:stream/promises';
 import { parseEnvValues } from './env-vars.js';
 import { emit } from './collections-cli.js';
 
@@ -54,8 +63,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_TEMPLATE_TAG: 'latest',
+	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: '0.6.0',   // the image release this engine is tested against, bumped with it; `setup` never writes it, so an upgrade moves it
+	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,18 +97,31 @@ 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). */
-export function api(method, urlPath, body, { onLine } = {}) {
+/** 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);
+}
+
+/** `send` streams a body (a tar upload) instead of JSON; `stream` resolves a 2xx with the response
+ *  itself, unread (a tar download) — both under the same idle timer, which keeps running while the
+ *  bytes move. */
+export function api(method, urlPath, body, { onLine, raw, send, stream } = {}) {
 	const sock = socketPath();
+	const seconds = dockerTimeoutSeconds();
 	return new Promise((resolve, reject) => {
 		const payload = body === undefined ? undefined : JSON.stringify(body);
 		const req = http.request({
 			socketPath: sock, method, path: urlPath,
-			headers: payload ? { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) } : {},
+			headers: payload ? { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) } : send ? { 'Content-Type': 'application/x-tar' } : {},
 		}, (res) => {
+			if (stream && res.statusCode < 300) return resolve({ status: res.statusCode, res });
 			let text = '';
 			let pending = '';
-			res.setEncoding('utf8');
+			const bufs = []; // `raw`: an exec's multiplexed stream is binary framing, so it stays bytes
+			if (!raw) res.setEncoding('utf8');
 			res.on('data', (chunk) => {
+				if (raw) { bufs.push(chunk); return; }
 				text += chunk;
 				if (!onLine) return;
 				pending += chunk;
@@ -107,6 +130,7 @@ export function api(method, urlPath, body, { onLine } = {}) {
 				for (const l of lines) if (l.trim()) { try { onLine(JSON.parse(l)); } catch { /* not JSON */ } }
 			});
 			res.on('end', () => {
+				if (raw) return resolve({ status: res.statusCode, body: Buffer.concat(bufs) });
 				const isJson = /json/.test(res.headers['content-type'] ?? '');
 				let parsed = text;
 				if (isJson && !onLine) { try { parsed = text ? JSON.parse(text) : null; } catch { parsed = text; } }
@@ -114,19 +138,23 @@ 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 (send) return pipeline(send, req).catch((e) => req.destroy(e));
 		if (payload) req.write(payload);
 		req.end();
 	});
 }
 
 /** Throw the daemon's own sentence on a non-2xx, so a refusal reads as Docker's rather than ours. */
-function ok(res, what) {
+export function ok(res, what) {
 	if (res.status >= 200 && res.status < 400) return res.body;
 	const msg = res.body && typeof res.body === 'object' && res.body.message ? res.body.message : String(res.body ?? '').trim();
 	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 ------------------------------------------------------------------------------------
@@ -181,7 +209,38 @@ const containerRow = (c) => {
 		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}`;
+/** A bare URL opens the machine home (`/opt/dt-launcher`: every workspace, create, clone) — `?folder=`
+ *  only when the caller asks for one workspace (`--workspace`). */
+const editorUrl = (port, folder) => `http://localhost:${port}/${folder ? `?folder=${folder}` : ''}`;
+/** Where `--mount` may land: the image's own trees. Anywhere else (`/etc`, `/usr/local/bin`, `/opt`)
+ *  replaces what the image runs — a mount there is a way round the image, not a mount. */
+export const MOUNT_ROOTS = ['/workspaces', '/home/node', '/files', '/mnt'];
+/** `--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, rawTarget, mode] = parts;
+	const target = path.posix.normalize(rawTarget).replace(/(.)\/$/, '$1'); // `/mnt/../etc` is `/etc`
+	if (!MOUNT_ROOTS.some((r) => target === r || target.startsWith(`${r}/`))) throw new Error(`--mount "${spec}": the target must be under ${MOUNT_ROOTS.join(' · ')} — ${target} is not`);
+	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)}`;
+/** Each container gets its OWN user-defined bridge, so it shares no network with another
+ *  workspace and its network carries its name. That is NOT isolation on its own: measured 2026-09-28
+ *  on Docker Desktop 29.3.1, a container on one user-defined bridge reaches another's by IP and via
+ *  host.docker.internal:<its published port>. What isolates is the image's egress firewall (see
+ *  CapAdd below); the bridge still helps where the platform does separate bridges. */
+export const networkName = (name) => `dreamteamer-${name}`;
 const volumeNames = (name) => ({ workspace: `dreamteamer-${name}-workspace`, home: `dreamteamer-${name}-home`, files: `dreamteamer-${name}-files` });
 
 export async function listContainers() {
@@ -200,14 +259,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'] ?? '' },
+		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,
 	};
 }
@@ -237,7 +303,8 @@ function person(flags, env) {
 }
 
 /** Create-if-absent and start. Idempotent: a second call on an existing name starts it and prints
- *  the same URL. Never injects a token — the person logs in INSIDE, once, and the home volume keeps it. */
+ *  the same URL. Never injects a credential — the person logs in INSIDE, once, and the home volume
+ *  keeps it. The one secret that crosses is the image's own URL token, read back OUT (launchUrl). */
 export async function startContainer(name, flags, log = console.log) {
 	if (!/^[a-z0-9][a-z0-9_.-]*$/.test(name)) throw new Error(`"${name}" is not a container name — lowercase letters, digits, "-", "_" and "."; e.g. hq-dana`);
 	const env = hostEnv();
@@ -254,11 +321,51 @@ 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, '/workspaces', '/home/node', '/files'].includes(m.Target)) throw new Error(`--mount cannot target ${m.Target} — that is one of the container's own volumes, or holds them (${wsDir} · /home/node · /files)`);
+		// No mount point INSIDE another mount, the three own volumes included. runc resolves a mount
+		// destination through symlinks in the rootfs, and a mounted volume is writable by whoever runs
+		// in it: `evil -> /opt` inside /workspaces/<name> makes a mount at /workspaces/<name>/evil land
+		// on the image's real /opt (measured with plain Docker). Only the image's own filesystem — no
+		// symlinks on these roots, which the image pins with a test — may lie between / and a mount point.
+		const under = (t, r) => t === r || t.startsWith(`${r}/`);
+		const targets = [wsDir, '/home/node', '/files', ...extra.map((m) => m.Target)];
+		extra.forEach((m, i) => { for (const [j, t] of targets.entries()) if (j !== i + 3 && (under(m.Target, t) || under(t, m.Target))) throw new Error(`--mount ${m.Source}:${m.Target} lies at or under ${t}, another mount of this container — a mount point inside a mount resolves through whatever symlinks were written there; mount it beside, e.g. /mnt/<name>`); });
+		// A bind whose source lies inside another bind's (or IS it) reaches the same files twice — the
+		// way a `:ro` mount of a folder is undone by a writable mount of the folder it sits in.
+		// "Inside" is decided by IDENTITY, not spelling: realpath keeps the case it was given, so on a
+		// case-insensitive volume (APFS, NTFS by default) `/x/INNER` passes a path comparison against `/x`.
+		// So walk up a's real path and compare each ancestor's dev+ino with b's — the filesystem's own
+		// rules (case, Unicode normalisation) answer, none guessed here. A source that does not exist has
+		// no inode (Docker refuses the bind anyway); it falls back to a path compare, case-folded where
+		// the platform's default volume folds.
+		const real = (p) => { try { return fs.realpathSync(p); } catch { return p; } };
+		const ident = (p) => { try { const s = fs.statSync(p, { bigint: true }); return `${s.dev}:${s.ino}`; } catch { return null; } };
+		const fold = (p) => (['darwin', 'win32'].includes(process.platform) ? p.toLowerCase() : p);
+		const inside = (a, b) => {
+			const want = ident(b.real);
+			if (!want) return !path.relative(fold(b.real), fold(a.real)).startsWith('..');
+			for (let p = a.real; ; p = path.dirname(p)) { if (ident(p) === want) return true; if (path.dirname(p) === p) return false; }
+		};
+		const binds = extra.filter((m) => m.Type === 'bind').map((m) => ({ m, real: real(m.Source) }));
+		for (const a of binds) for (const b of binds) if (a !== b && inside(a, b)) throw new Error(`--mount ${a.m.Source}:${a.m.Target} lies inside ${b.m.Source} (mounted at ${b.m.Target}) — one container reaches a host folder through one mount`);
+		// `--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 network = await ensureNetwork(name);
 		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',
+				// the editor listens on every interface INSIDE the container so the port mapping reaches
+				// it; the host side stays DT_BIND (loopback) — and the image's proxy checks a token
+				'DT_LOCAL_BIND=0.0.0.0',
+				...(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 +373,37 @@ 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' },
+				NetworkMode: network.net, // its own bridge ONLY — never the default one; naming, not the isolation
+				// NET_ADMIN, and nothing else, for the image's ROOT phase: the entrypoint applies the local
+				// egress policy (what the container may reach — not another workspace, not the host's
+				// published ports) before it drops to the editor and agents, which run with NO capabilities,
+				// so none of them can change the rules. Separate bridges alone do not isolate (above).
+				CapAdd: ['NET_ADMIN'],
 			},
 		};
-		ok(await api('POST', `/containers/create?name=${encodeURIComponent(name)}`, body), `create container ${name}`);
+		// A create Docker refuses must not leave this attempt's debris: the network ensureNetwork just
+		// made, and the named volumes Docker makes during create. Only what did NOT exist before is
+		// removed — a pre-existing volume holds someone's work. Docker refuses to remove either while a
+		// container uses it, which covers the create that did land before its answer was lost.
+		const fresh = [];
+		try {
+			for (const m of body.HostConfig.Mounts) if (m.Type === 'volume' && (await api('GET', `/volumes/${encodeURIComponent(m.Source)}`)).status === 404) fresh.push(m.Source);
+			ok(await api('POST', `/containers/create?name=${encodeURIComponent(name)}`, body), `create container ${name}`);
+		} catch (e) {
+			try {
+				for (const v of fresh) await api('DELETE', `/volumes/${encodeURIComponent(v)}`);
+				if (network.created) await api('DELETE', `/networks/${encodeURIComponent(network.net)}`);
+			} catch { /* the create's own failure is the one to report */ }
+			throw e;
+		}
 		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`);
@@ -284,11 +412,56 @@ export async function startContainer(name, flags, log = console.log) {
 	}
 	const detail = containerDetail(c);
 	await waitHealthy(detail, log);
-	log(`✔ container ${name} · ${detail.state} · ${detail.editor_url}`);
-	if (!flags['no-open'] && detail.editor_url) openUrl(detail.editor_url);
+	const url = await launchUrl(detail, flags);
+	log(`✔ container ${name} · ${detail.state} · ${url.text}`);
+	if (!flags['no-open'] && detail.port) openUrl(url, log);
 	return detail;
 }
 
+async function ensureNetwork(name) {
+	const net = networkName(name);
+	const res = await api('GET', `/networks/${encodeURIComponent(net)}`);
+	if (res.status === 404) { ok(await api('POST', '/networks/create', { Name: net, Driver: 'bridge', Labels: { dreamteamer: '1', 'dreamteamer.name': name } }), `create network ${net}`); return { net, created: true }; }
+	if (ok(res, `get network ${net}`).Labels?.['dreamteamer.name'] !== name) throw new Error(`a Docker network "${net}" exists that dreamteamer did not make — remove or rename it (docker network rm ${net})`);
+	return { net, created: false };
+}
+
+/** Run `cmd` (an argv, never a shell line) in a running container as `user` — one Docker exec under
+ *  the same idle timer as every request. Answers { code, stdout, stderr }; a non-zero exit is the
+ *  caller's to judge. */
+export async function exec(name, cmd, { user } = {}) {
+	const what = `exec ${cmd[0]} in ${name}`;
+	const { Id } = ok(await api('POST', `/containers/${encodeURIComponent(name)}/exec`, { Cmd: cmd, AttachStdout: true, AttachStderr: true, ...(user ? { User: user } : {}) }), what);
+	const res = await api('POST', `/exec/${Id}/start`, { Detach: false, Tty: false }, { raw: true });
+	ok({ status: res.status, body: res.body.toString('utf8') }, what);
+	// Tty:false answers Docker's multiplexed stream: per frame an 8-byte header — stream (1 out, 2 err),
+	// three zero bytes, a big-endian length — then that many bytes
+	const out = { stdout: '', stderr: '' };
+	for (let b = res.body, i = 0, n; i + 8 <= b.length; i += 8 + n) { n = b.readUInt32BE(i + 4); out[b[i] === 2 ? 'stderr' : 'stdout'] += b.subarray(i + 8, i + 8 + n).toString('utf8'); }
+	return { code: ok(await api('GET', `/exec/${Id}/json`), what).ExitCode, ...out };
+}
+
+/** The URL to print and open. An image that lists `url-token` in /opt/dt-image/features (hq 0.6+)
+ *  holds a secret its proxy checks; it is read by exec as root, lives in this process only, and
+ *  reaches the person as `?tkn=` on the ONE line that prints the URL. An older image has no file and
+ *  gets the plain URL. `text` is that line's URL; `secret` says the token rides on it. */
+async function launchUrl(detail, flags) {
+	const folder = flags.workspace === true ? detail.workspace_dir : typeof flags.workspace === 'string' ? workspaceDir(flags.workspace) : undefined;
+	if (folder && !/^\/workspaces\/[a-z0-9][a-z0-9_.-]*$/.test(folder)) throw new Error(`--workspace takes a workspace folder name under /workspaces — got "${flags.workspace}"`);
+	const plain = detail.port ? editorUrl(detail.port, folder) : '';
+	const features = await exec(detail.name, ['cat', '/opt/dt-image/features']);
+	const tokened = features.code === 0 && features.stdout.split('\n').some((l) => l.trim() === 'url-token');
+	const rotate = flags['rotate-token'] === true;
+	if (!tokened) {
+		if (rotate) throw new Error(`${detail.name} runs an image with no URL token (no url-token in /opt/dt-image/features) — --rotate-token needs hq 0.6 or later`);
+		return { text: plain, secret: false };
+	}
+	const r = await exec(detail.name, ['dt-url-token', rotate ? 'rotate' : 'show'], { user: 'root' });
+	const token = r.stdout.trim();
+	if (r.code !== 0 || !/^[A-Za-z0-9_-]{16,}$/.test(token)) throw new Error(`dt-url-token ${rotate ? 'rotate' : 'show'} in ${detail.name} failed (exit ${r.code})${r.stderr.trim() ? ` — ${r.stderr.trim()}` : ''}`);
+	return { text: `${plain}${folder ? '&' : '?'}tkn=${token}`, secret: true };
+}
+
 /** Poll code-server's /healthz so the URL printed is one that already answers. */
 async function waitHealthy(detail, log) {
 	const seconds = process.env.DT_HEALTH_TIMEOUT !== undefined ? Number(process.env.DT_HEALTH_TIMEOUT) : 90;
@@ -307,9 +480,19 @@ async function waitHealthy(detail, log) {
 	log(`⚠ the editor did not answer within ${seconds}s — \`docker logs ${detail.name}\` says why`);
 }
 
-function openUrl(url) {
-	const cmd = process.platform === 'darwin' ? ['open', url] : process.platform === 'win32' ? ['cmd', '/c', 'start', '', url] : ['xdg-open', url];
-	try { spawn(cmd[0], cmd.slice(1), { stdio: 'ignore', detached: true }).unref(); } catch { /* printing the URL is the contract; opening it is a courtesy */ }
+/** Printing the URL is the contract; opening it is a courtesy. A tokened URL never becomes a process
+ *  ARGUMENT (every local user's `ps` reads those): on macOS it reaches `osascript` on stdin; where no
+ *  opener takes stdin (xdg-open, start) it is printed and left for the person to open. */
+function openUrl({ text, secret }, log) {
+	try {
+		if (secret && process.platform === 'darwin') {
+			const p = spawn('osascript', ['-'], { stdio: ['pipe', 'ignore', 'ignore'], detached: true });
+			p.on('error', () => {}); p.stdin.end(`open location "${text}"\n`); p.unref(); return;
+		}
+		if (secret) { log('  (open the URL above yourself — this platform\'s opener would put the token in a process argument)'); return; }
+		const cmd = process.platform === 'darwin' ? ['open', text] : process.platform === 'win32' ? ['cmd', '/c', 'start', '', text] : ['xdg-open', text];
+		spawn(cmd[0], cmd.slice(1), { stdio: 'ignore', detached: true }).on('error', () => {}).unref();
+	} catch { /* the URL is printed either way */ }
 }
 
 export async function stopContainer(name) {
@@ -325,14 +508,17 @@ export async function removeContainer(name, { force = false } = {}, log = consol
 	const c = await inspectContainer(name);
 	if (!c) throw new Error(`no container "${name}" — dt list containers`);
 	const vols = containerDetail(c).volumes;
-	if (c.State?.Status === 'running') await api('POST', `/containers/${c.Id}/stop?t=10`);
+	// `restarting` too: a crash-looping container refuses DELETE until it is stopped (measured, Docker Desktop)
+	if (['running', 'restarting'].includes(c.State?.Status)) await api('POST', `/containers/${c.Id}/stop?t=10`);
 	ok(await api('DELETE', `/containers/${c.Id}?v=false`), `rm container ${name}`);
+	const net = await api('GET', `/networks/${encodeURIComponent(networkName(name))}`);
+	if (net.status === 200 && net.body?.Labels?.['dreamteamer.name'] === name) ok(await api('DELETE', `/networks/${encodeURIComponent(networkName(name))}`), `rm network ${networkName(name)}`);
 	const named = Object.values(vols).filter(Boolean);
 	if (force) {
 		for (const v of named) { const r = await api('DELETE', `/volumes/${encodeURIComponent(v)}`); if (r.status !== 204 && r.status !== 404) ok(r, `rm volume ${v}`); }
-		log(`✔ removed ${name} and its volumes ${named.join(', ')}`);
+		log(`✔ removed ${name}, its network and its volumes ${named.join(', ')}`);
 	} else {
-		log(`✔ removed ${name} · kept volumes ${named.join(', ')} (dt rm container ${name} --force removes them too; dt start container ${name} --template <t> reattaches them)`);
+		log(`✔ removed ${name} and its network · kept volumes ${named.join(', ')} (dt rm container ${name} --force removes them too; dt start container ${name} --template <t> reattaches them)`);
 	}
 }
 
@@ -342,7 +528,7 @@ export async function setup(flags, log = console.log) {
 	const file = path.join(dir, '.env');
 	fs.mkdirSync(dir, { recursive: true });
 	const existing = fs.existsSync(file) ? Object.fromEntries(parseEnvValues(fs.readFileSync(file, 'utf8'))) : {};
-	const missing = Object.entries(HOST_DEFAULTS).filter(([k]) => !(k in existing));
+	const missing = Object.entries(HOST_DEFAULTS).filter(([k]) => k !== 'DT_TEMPLATE_TAG' && !(k in existing));
 	if (missing.length) {
 		const header = fs.existsSync(file) ? '' : '# dreamteamer host configuration — read by `dt setup`, `dt start container` and friends.\n# DT_IMAGE_<template>=<ref> pins a template to an image; DT_PERSON_NAME / DT_PERSON_EMAIL are the git identity containers get.\n';
 		fs.appendFileSync(file, header + missing.map(([k, v]) => `${k}=${v}`).join('\n') + '\n');
@@ -385,6 +571,9 @@ export async function driverCommand(verb, target, args) {
 	const id = target.id ?? pos[0];
 	const json = flags.json === true;
 	const col = target.collection;
+	// under --json stdout is the JSON document and nothing else — every human line (the URL carrying
+	// the image's token among them) goes to stderr, so a script parsing or logging stdout never holds it
+	const say = json ? console.error : console.log;
 	if (!DRIVER_VERBS.has(verb)) throw new Error(`\`${verb}\` is not a verb on ${col} — list · get · add · rm${col === 'containers' ? ' · start · stop · open' : ''}`);
 	if (col === 'images') {
 		if (LIFECYCLE_VERBS.has(verb)) throw new Error(`\`${verb}\` is a container verb — an image is started by starting a container from it: dt start container <name> --template <t>`);
@@ -397,9 +586,27 @@ export async function driverCommand(verb, target, args) {
 	if (verb === 'list') { const rows = await listContainers(); json ? emit(JSON.stringify(rows, null, 2)) : console.log(table(rows, ['name', 'template', 'state', 'editor_url', 'person', 'created'])); return 0; }
 	if (!id) throw new Error(`dt ${verb} container <name>${verb === 'start' || verb === 'add' ? ' --template <t>' : ''}`);
 	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 === 'start' || verb === 'add') { const d = await startContainer(id, flags, say); if (json) emit(JSON.stringify(d, null, 2)); return 0; }
+	if (verb === 'stop') { const d = await stopContainer(id); say(`✔ 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 (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.
+			say(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 */ } }
+			if (json) emit(JSON.stringify(d, null, 2));
+			return 0;
+		}
+		if (!d.editor_url) throw new Error(`${id} publishes no port`);
+		if (d.state !== 'running') throw new Error(`${id} is ${d.state} — dt start container ${id} starts it and prints its URL`);
+		const url = await launchUrl(d, flags);
+		say(url.text); if (!flags['no-open']) openUrl(url, say);
+		if (json) emit(JSON.stringify(d, null, 2)); // containerDetail: its editor_url never carries the token
+		return 0;
+	}
 	if (verb === 'rm') { await removeContainer(id, { force: flags.force === true }); return 0; }
 	return 1;
 }
@@ -408,15 +615,21 @@ 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` repeats; `--workspace` repeats on export/import, which read every value from
+	// `workspaces` while start/open keep the last. Any 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;
+		if (k === 'workspace') flags.workspaces = [...(flags.workspaces ?? []), 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', 'rotate-token', 'workspace', 'out', 'no-encrypt', 'replace', 'with-secrets', 'as'];

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);