@wpelevator/tug 0.9.0 → 0.10.0

package/dist/cli-install.js

@@ -1,7 +1,6 @@
 import * as yaml from 'js-yaml';
 /** The agent dials container IPs for health checks; from the default bridge they are unreachable on current Docker (29.x), so it always shares the host network namespace. */
 export const HOST_NETWORK_FLAG = '--network host';
-export const MESH_RUN_FLAGS = `${HOST_NETWORK_FLAG} --cap-add NET_ADMIN`;
 /** Docker platform for the architecture a host reports with `uname -m`. */
 export function dockerPlatform(uname) {
     const arch = uname.trim();
@@ -18,8 +17,8 @@ export function localImageBuildArgs(imageTag, uname) {
 export function shellQuote(value) {
     return `'${String(value).replace(/'/g, `'\\''`)}'`;
 }
-export function dockerRunSnippet(image, joinKey, mesh = false) {
-    return `docker run -d --name tug-agent --restart unless-stopped ${mesh ? `${MESH_RUN_FLAGS} -e TUG_MESH=true ` : `${HOST_NETWORK_FLAG} `}-v /var/run/docker.sock:/var/run/docker.sock -v tug-agent:/var/lib/tug -e TUG_JOIN_KEY=${shellQuote(joinKey)} ${shellQuote(image)} agent`;
+export function dockerRunSnippet(image, joinKey, address) {
+    return `docker run -d --name tug-agent --restart unless-stopped ${HOST_NETWORK_FLAG} -v /var/run/docker.sock:/var/run/docker.sock -v tug-agent:/var/lib/tug -e TUG_JOIN_KEY=${shellQuote(joinKey)} ${address ? `-e TUG_NODE_ADDRESS=${shellQuote(address)} ` : ''}${shellQuote(image)} agent`;
 }
 /** The bootstrap runs in its own shell so its idempotent early exit cannot skip enrollment. */
 export function enrollmentCloudInit(bootstrap, command) {
@@ -42,24 +41,23 @@ ss -ltn | awk '{print $4}' | grep -qE '[.:]${port}$' || exit 0
 [ -n "$(docker ps -q --filter 'name=^/${CONTROL_CONTAINER}$' --filter 'publish=${port}' 2>/dev/null)" ]
 `;
 }
-/** An occupied mesh port is reusable only when the installed Tug agent owns the live key. */
-export function meshPortCheck(port) {
-    if (!Number.isInteger(port) || port < 1 || port > 65535)
-        throw new Error('mesh port must be an integer from 1 to 65535');
-    return `command -v ss >/dev/null 2>&1 || exit 1
-listeners=$(ss -lun) || exit 1
-if ! printf '%s\\n' "$listeners" | awk '{print $4}' | grep -qE '[.:]${port}$'; then exit 0; fi
-[ "$(docker inspect --format '{{.HostConfig.NetworkMode}}' tug-agent 2>/dev/null)" = host ] || exit 1
-[ "$(docker inspect --format '{{.State.Running}}' tug-agent 2>/dev/null)" = true ] || exit 1
-docker inspect --format '{{range .Config.Env}}{{println .}}{{end}}' tug-agent 2>/dev/null | grep -qx 'TUG_MESH=true' || exit 1
-[ "$(docker inspect --format '{{range .Mounts}}{{if eq .Destination "/var/lib/tug"}}{{.Source}}{{end}}{{end}}' tug-agent 2>/dev/null)" = /var/lib/tug ] || exit 1
-docker exec tug-agent sh -eu -c ${shellQuote(`
-test -s /var/lib/tug/wireguard/private.key
-test -s /var/lib/tug/wireguard/reported.pub
-test "$(wg show wg0 listen-port)" = "${port}"
-live_key=$(wg show wg0 public-key)
-test -n "$live_key"
-test "$live_key" = "$(wg pubkey < /var/lib/tug/wireguard/private.key)"
-test "$live_key" = "$(cat /var/lib/tug/wireguard/reported.pub)"`)}
-`;
+/**
+ * The default control URL for `control-install`: the SSH target's host and the published port. Accepts
+ * `host`, `user@host`, `ssh://user@host:2222` and bracketed IPv6. An SSH alias from ~/.ssh/config is used as written,
+ * so pass `--control-url` when the alias is not a name or address clients can reach.
+ */
+export function defaultControlUrl(sshTarget, port) {
+    let host = sshTarget
+        .trim()
+        .replace(/^ssh:\/\//, '')
+        .replace(/\/.*$/, '');
+    host = host.replace(/^[^@]*@/, '');
+    const bracketed = /^\[([^\]]+)\]/.exec(host);
+    if (bracketed)
+        host = bracketed[1];
+    else if (host.split(':').length === 2)
+        host = host.split(':')[0];
+    if (!host || /[\s'"]/.test(host))
+        throw new Error(`cannot derive a host from SSH target ${sshTarget}`);
+    return `https://${host.includes(':') ? `[${host}]` : host}:${port}`;
 }

package/dist/cli-status.d.ts

@@ -0,0 +1,29 @@
+/** The control status endpoint returns database rows and a JSON-encoded node report. */
+export interface StatusResponse {
+    projects: {
+        id: string;
+        current_deployment_id: string | null;
+    }[];
+    deployments: {
+        id: string;
+        version: string;
+        state: string;
+        error_message: string | null;
+    }[];
+    nodes: {
+        id: string;
+        name: string;
+        status: string;
+        last_seen_at: string | null;
+    }[];
+    statuses: {
+        project_id: string;
+        node_id: string;
+        node: string | null;
+        health: string;
+        observed_version: string | null;
+        status_json: string;
+    }[];
+}
+/** Render observations without treating a stale node's last report as current health. */
+export declare function formatStatus(status: StatusResponse): string;

package/dist/cli-status.js

@@ -0,0 +1,61 @@
+/** Render observations without treating a stale node's last report as current health. */
+export function formatStatus(status) {
+    const lines = [];
+    const nodes = new Map(status.nodes.map((node) => [node.id, node]));
+    for (const project of [...status.projects].sort((a, b) => a.id.localeCompare(b.id))) {
+        const deployment = status.deployments.find((item) => item.id === project.current_deployment_id);
+        lines.push(`Project ${project.id}`);
+        if (deployment) {
+            lines.push(`  Deployment: ${deployment.version} (${deployment.state})`);
+            if (deployment.error_message)
+                lines.push(`  Error: ${deployment.error_message}`);
+        }
+        else {
+            lines.push(project.current_deployment_id
+                ? '  Deployment: current deployment not in recent results'
+                : '  Deployment: none');
+        }
+        const reports = status.statuses
+            .filter((item) => item.project_id === project.id)
+            .sort((a, b) => (a.node || a.node_id).localeCompare(b.node || b.node_id));
+        if (!reports.length)
+            lines.push('  No node reports');
+        for (const report of reports) {
+            const node = nodes.get(report.node_id);
+            lines.push(`  Node ${report.node || report.node_id}: ${node?.status || 'unknown'}; last reported ${report.health}${report.observed_version ? ` (${report.observed_version})` : ''}`);
+            try {
+                const detail = JSON.parse(report.status_json);
+                if (detail &&
+                    typeof detail === 'object' &&
+                    'error' in detail &&
+                    typeof detail.error === 'string' &&
+                    detail.error)
+                    lines.push(`    Error: ${detail.error}`);
+                if (detail &&
+                    typeof detail === 'object' &&
+                    'serviceStates' in detail &&
+                    detail.serviceStates &&
+                    typeof detail.serviceStates === 'object') {
+                    for (const [name, state] of Object.entries(detail.serviceStates).sort(([a], [b]) => a.localeCompare(b))) {
+                        if (!state || typeof state !== 'object')
+                            continue;
+                        const item = state;
+                        if (typeof item.rolloutState === 'string')
+                            lines.push(`    ${name}: ${item.rolloutState}${typeof item.rolloutError === 'string' && item.rolloutError ? ` — ${item.rolloutError}` : ''}`);
+                    }
+                }
+            }
+            catch {
+                lines.push('    Report details unavailable');
+            }
+        }
+    }
+    if (!status.projects.length)
+        lines.push('No projects');
+    lines.push('', 'Nodes');
+    if (!status.nodes.length)
+        lines.push('  No nodes');
+    for (const node of [...status.nodes].sort((a, b) => a.name.localeCompare(b.name)))
+        lines.push(`  ${node.name}: ${node.status}; last seen ${node.last_seen_at || 'never'}`);
+    return lines.join('\n');
+}

package/dist/cli.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
+import { isNodeHost } from "./node-address.js";
 import { Command, Option } from 'commander';
 import { openAsBlob } from 'node:fs';
 import { applyConfigDefaults, integerOption, normalizeControlUrl, nodeSettings, resolveCliConfig, writeInitConfig, } from "./cli-config.js";
-import { dockerRunSnippet, enrollmentCloudInit, shellQuote as sh, HOST_NETWORK_FLAG, MESH_RUN_FLAGS, CONTROL_CONTAINER, controlPortCheck, localImageBuildArgs, meshPortCheck, } from "./cli-install.js";
-import { createSourceArchive, prepareLocalImages } from "./cli-build.js";
+import { dockerRunSnippet, enrollmentCloudInit, shellQuote as sh, HOST_NETWORK_FLAG, CONTROL_CONTAINER, defaultControlUrl, controlPortCheck, localImageBuildArgs, } from "./cli-install.js";
+import { createLocalBuildSnapshot, createSourceArchive, prepareLocalImages } from "./cli-build.js";
 import { saveImageArchive } from "./artifacts.js";
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs/promises';
@@ -16,6 +17,7 @@ import { errMessage, loadTemplate } from "./util.js";
 import { createTransport } from "./agent-credential.js";
 import { decodeCredential, writeFileDurable } from "./pki.js";
 import { backupCheckProblems } from "./backup-check.js";
+import { formatStatus } from "./cli-status.js";
 import { PROJECT_NAME_PATTERN, ROLES, CREDENTIAL_NAME_PATTERN } from "./credentials.js";
 import { packageVersion, resolveImage } from "./image.js";
 import { TERMINAL_DEPLOYMENT_STATES } from "./protocol.js";
@@ -85,7 +87,7 @@ function runCapture(cmd, args, opts = {}) {
         throw new Error(`${cmd} ${args.join(' ')} failed\n${result.stderr || ''}`);
     return String(result.stdout);
 }
-function preflightRemote(target, { controlUrl, ports = [], udpPorts = [], minDiskMb = 1024, mesh = false, compose = false, } = {}) {
+function preflightRemote(target, { controlUrl, ports = [], minDiskMb = 1024, compose = false, } = {}) {
     const checks = [
         [
             'docker.version',
@@ -119,20 +121,6 @@ function preflightRemote(target, { controlUrl, ports = [], udpPorts = [], minDis
             `Port ${port} is already in use on the target host by something other than the Tug control container; stop the conflicting service or choose another port.`,
         ]);
     }
-    if (mesh) {
-        checks.push([
-            'wireguard.kernel',
-            'ip link add tugwgtest type wireguard && ip link del tugwgtest || modprobe -n wireguard 2>/dev/null',
-            'Install WireGuard (kernel 5.6+ has it built in; older kernels need the wireguard-dkms package) and ensure iproute2 is present.',
-        ]);
-    }
-    for (const port of udpPorts) {
-        checks.push([
-            `udp.${port}.free`,
-            meshPortCheck(port),
-            `UDP port ${port} is in use by something other than this node's running Tug mesh agent (or the ss tool is missing). Stop the conflicting service, or choose another port with --wg-port and set TUG_WG_PORT on control.`,
-        ]);
-    }
     if (controlUrl)
         checks.push([
             'control.reachable',
@@ -219,33 +207,27 @@ program
     .requiredOption('--csr <file>', 'PEM certificate request generated on the node (- for stdin)')
     .option('--mode <mode>', 'create a new node or replace an existing node key', 'create')
     .option('--address <addr>')
-    .option('--public-address <addr>')
     .option('--label <label>', 'node label (repeatable)', collect, [])
     .action(async (name, o) => {
     if (o.mode !== 'create' && o.mode !== 'replace')
         throw new Error("--mode must be 'create' or 'replace'");
     const csr = o.csr === '-' ? await readStdin() : await fs.readFile(o.csr, 'utf8');
-    const r = await request('POST', `/api/v1/nodes/${encodeURIComponent(name)}/identity`, { csr, mode: o.mode, address: o.address, publicAddress: o.publicAddress, labels: o.label });
+    const r = await request('POST', `/api/v1/nodes/${encodeURIComponent(name)}/identity`, { csr, mode: o.mode, address: o.address, labels: o.label });
     console.log(JSON.stringify(r, null, 2));
 });
+program
+    .command('node-address <name> <address>')
+    .description("update a node's inter-node address")
+    .action(async (name, address) => {
+    console.log(JSON.stringify(await request('POST', `/api/v1/nodes/${encodeURIComponent(name)}/address`, { address }), null, 2));
+});
 program
     .command('node-disable <name>')
     .description("block a node's key immediately without deleting its metadata or placement (no SSH needed); bring it back with node-replace-identity")
     .action(async (name) => console.log(JSON.stringify(await request('POST', `/api/v1/nodes/${encodeURIComponent(name)}/disable`, {}), null, 2)));
-program
-    .command('node-rotate-wg-key <name>')
-    .description('generate a new WireGuard keypair on the node; peers pick up the new public key on their next poll')
-    .option('--timeout <seconds>', 'wait timeout', '60')
-    .action(async (name, o) => {
-    const created = await request('POST', `/api/v1/nodes/${encodeURIComponent(name)}/rotate-wg-key`, {});
-    const cmd = await waitForCommand(created.commandId, Number(o.timeout));
-    if (cmd.state === 'failed')
-        throw new Error(JSON.parse(cmd.result_json || '{}').error || 'key rotation failed');
-    console.log(JSON.stringify({ ok: true, node: name, ...JSON.parse(cmd.result_json || '{}') }, null, 2));
-});
 program
     .command('node-remove <name>')
-    .description('remove a retired node from the control plane (its identity, WireGuard peer, statuses and queued commands); stop its agent and remove its containers on the host yourself')
+    .description('remove a retired node from the control plane (its identity, statuses and queued commands); stop its agent and remove its containers on the host yourself')
     .option('--force', 'remove even if the node is still reporting')
     .action(async (name, o) => {
     console.log(JSON.stringify(await request('DELETE', `/api/v1/nodes/${encodeURIComponent(name)}${o.force ? '?force=true' : ''}`), null, 2));
@@ -272,7 +254,6 @@ program
 program
     .command('control-install <sshTarget>')
     .description('install the control plane on a Docker-capable host over SSH and issue the root credential into a local 0600 file; it listens for mTLS only, so front it with TCP passthrough rather than a terminating proxy')
-    .requiredOption('--advertise-url <url>', 'credential-free https origin clients use, including the published port')
     .option('--extra-san <name>', 'additional DNS name or IP for the server certificate (repeatable)', collect, [])
     .option('--image <tag>', "Tug image to run (default: ghcr.io/wpelevator/tug:<this CLI's version>)")
     .option('--install-docker', 'install missing Docker Engine and Compose on supported Debian, Ubuntu, Fedora and RHEL-compatible hosts (root required)')
@@ -280,9 +261,12 @@ program
     .option('--port <port>', 'published mTLS port', '8443')
     .option('--credential-out <file>', 'where to write the root credential', 'tug-root.credential.json')
     .option('--recover-root', "replace root's key from the control host without the API (lost credential); other admins are unaffected")
-    .option('--mesh', 'enable the WireGuard mesh on control (TUG_MESH=true); install nodes with --mesh too')
     .action(async (sshTarget, o) => {
-    const advertiseUrl = normalizeControlUrl(o.advertiseUrl);
+    const cfg = await loadCfg();
+    // The control URL clients use: --control-url, TUG_CONTROL_URL or the config's controlUrl, else the SSH target's host
+    // and the published port. Clients verify a name generated from the CA, so this is only an address.
+    const controlUrl = cfg.requestedControlUrl ?? defaultControlUrl(sshTarget, o.port);
+    console.error(`control URL: ${controlUrl} (${cfg.requestedControlUrl ? 'from --control-url, TUG_CONTROL_URL or the config file' : 'from the SSH target and --port'}); clients connect there by default`);
     if (o.installDocker)
         await bootstrapDocker(sshTarget, true);
     preflightRemote(sshTarget, { ports: [Number(o.port)], minDiskMb: 2048, compose: true });
@@ -292,10 +276,9 @@ program
     const yamlValue = (value) => JSON.stringify(value);
     const compose = await loadTemplate(templatesDir, 'control-compose.yml', {
         IMAGE: yamlValue(image),
-        ADVERTISE_URL: yamlValue(new URL(advertiseUrl).origin),
+        CONTROL_URL: yamlValue(new URL(controlUrl).origin),
         EXTRA_SANS: yamlValue(o.extraSan.join(',')),
         PORT: o.port,
-        MESH: yamlValue(o.mesh ? 'true' : 'false'),
     });
     const remote = await loadTemplate(templatesDir, 'control-install.sh', {
         COMPOSE: compose,
@@ -316,7 +299,7 @@ program
         await writeFileDurable(o.credentialOut, `${String(out.stdout).trim()}\n`, 0o600);
         console.error(`root credential written to ${o.credentialOut}; import it with: tug init ${o.credentialOut}`);
     }
-    console.log(JSON.stringify({ ok: true, sshTarget, url: advertiseUrl }, null, 2));
+    console.log(JSON.stringify({ ok: true, sshTarget, url: controlUrl }, null, 2));
 });
 const AGENT_STATE = '/var/lib/tug';
 function addNodeIdentityOptions(command) {
@@ -324,8 +307,6 @@ function addNodeIdentityOptions(command) {
         .option('--name <name>', 'node name')
         .option('--all', 'walk every node with an ssh target in the config file, continuing after failures')
         .option('--agent-control-url <url>', 'connect-only URL the agent dials (for example a private address); the certificate is still verified against the credential URL')
-        .option('--mesh', 'join the WireGuard mesh (agent runs with host networking and NET_ADMIN; control needs TUG_MESH=true)')
-        .option('--wg-port <port>', 'WireGuard UDP port checked by preflight', '51820')
         .option('--image <tag>', "Tug image to run (default: ghcr.io/wpelevator/tug:<this CLI's version>)")
         .option('--install-docker', 'install missing Docker Engine and Compose on supported Debian, Ubuntu, Fedora and RHEL-compatible hosts (root required)')
         .option('--build-local-image', 'build the image from the current checkout and copy it to the host over SSH (tags it tug:local unless --image is set); for development')
@@ -335,7 +316,9 @@ function addNodeIdentityOptions(command) {
  * The SSH-assisted flow: the node makes its own key and CSR, an admin credential authorizes the identity at this moment and
  * the certificate is installed back over SSH, so no bootstrap secret travels and the private key never leaves the node.
  */
-async function installNodeIdentity(sshTarget, name, mode, o, repair = false) {
+async function installNodeIdentity(sshTarget, name, mode, o, repair = false, 
+/** False in batch mode, where only the final per-node results are printed. */
+print = true) {
     const cfg = await loadCfg();
     const connectUrl = o.agentControlUrl ? normalizeControlUrl(o.agentControlUrl) : undefined;
     await transportFor(cfg).then((t) => t.close()); // fail before touching the host when there is no credential
@@ -343,8 +326,6 @@ async function installNodeIdentity(sshTarget, name, mode, o, repair = false) {
         await bootstrapDocker(sshTarget);
     preflightRemote(sshTarget, {
         controlUrl: connectUrl ?? cfg.credential?.url,
-        mesh: o.mesh,
-        udpPorts: o.mesh ? [Number(o.wgPort)] : [],
     });
     const image = resolveImage(o.image, o.buildLocalImage);
     if (o.buildLocalImage)
@@ -358,18 +339,18 @@ async function installNodeIdentity(sshTarget, name, mode, o, repair = false) {
         ]);
     const agent = (command, interactive = false) => `mkdir -p ${AGENT_STATE} && docker run --rm ${interactive ? '-i ' : ''}-v ${AGENT_STATE}:${AGENT_STATE} ${sh(image)} agent ${command}`;
     const csr = runCapture('ssh', ['--', sshTarget, agent('identity')]);
-    const response = await request('POST', `/api/v1/nodes/${encodeURIComponent(name)}/identity`, { csr, mode, address: o.address, publicAddress: o.publicAddress, labels: o.label });
+    const response = await request('POST', `/api/v1/nodes/${encodeURIComponent(name)}/identity`, { csr, mode, address: o.address, labels: o.label });
     runCapture('ssh', ['--', sshTarget, agent('install-cert', true)], {
         input: JSON.stringify(response),
     });
-    const env = (await loadTemplate(templatesDir, 'agent.env', {
+    const env = await loadTemplate(templatesDir, 'agent.env', {
         CONTROL_URL_LINE: connectUrl ? `TUG_CONTROL_URL=${connectUrl}\n` : '',
         NODE_NAME: name,
-    })) + (o.mesh ? 'TUG_MESH=true\n' : '');
+    });
     const remote = await loadTemplate(templatesDir, 'node-install.sh', {
         ENV: env,
         IMAGE_SH: sh(image),
-        RUN_FLAGS: `${o.mesh ? MESH_RUN_FLAGS : HOST_NETWORK_FLAG} `,
+        RUN_FLAGS: `${HOST_NETWORK_FLAG} `,
     });
     runLocal('ssh', ['--', sshTarget, remote]);
     if (o.wait) {
@@ -377,15 +358,19 @@ async function installNodeIdentity(sshTarget, name, mode, o, repair = false) {
         for (let i = 0; i < 30; i++) {
             const { nodes } = await request('GET', '/api/v1/nodes');
             const seen = nodes.find((n) => n.name === name)?.last_seen_at;
-            if (seen && seen > started)
-                return void console.log(JSON.stringify({ ok: true, node: response.node }, null, 2));
+            if (seen && seen > started) {
+                if (print)
+                    console.log(JSON.stringify({ ok: true, node: response.node }, null, 2));
+                return;
+            }
             await new Promise((r) => setTimeout(r, 2000));
         }
         console.error(`node ${name} has not reported yet; check \`docker logs tug-agent\` on the host`);
     }
-    console.log(JSON.stringify({ ok: true, node: response.node }, null, 2));
+    if (print)
+        console.log(JSON.stringify({ ok: true, node: response.node }, null, 2));
 }
-async function runNodeIdentity(sshArgument, o, mode, repair = false) {
+async function runNodeIdentity(sshArgument, o, mode, command, repair = false) {
     const cfg = await loadCfg();
     const verb = repair
         ? 'node-repair-identity'
@@ -398,9 +383,10 @@ async function runNodeIdentity(sshArgument, o, mode, repair = false) {
             const target = settings.ssh;
             if (!target)
                 continue;
-            const merged = { ...o, ...nodeOverrides(settings), name };
+            const merged = { ...o, name };
+            applyConfigDefaults(command, merged, nodeSettings(cfg, name));
             try {
-                await installNodeIdentity(target, name, mode, merged, repair);
+                await installNodeIdentity(target, name, mode, merged, repair, false);
                 results.push({ node: name, ok: true });
             }
             catch (e) {
@@ -419,12 +405,6 @@ async function runNodeIdentity(sshArgument, o, mode, repair = false) {
         throw new Error(`${verb} needs an SSH target: pass <ssh-target> or set nodes.${o.name}.ssh in ${cfg.file}`);
     await installNodeIdentity(sshTarget, o.name, mode, o, repair);
 }
-const nodeOverrides = (settings) => ({
-    ...(settings.address ? { address: settings.address } : {}),
-    ...(settings.publicAddress ? { publicAddress: settings.publicAddress } : {}),
-    ...(Array.isArray(settings.label) ? { label: settings.label } : {}),
-    ...(settings.mesh ? { mesh: true } : {}),
-});
 for (const [verb, description, mode, repair] of [
     [
         'node-install',
@@ -449,22 +429,23 @@ for (const [verb, description, mode, repair] of [
         .command(`${verb} [sshTarget]`)
         .description(description)
         .option('--address <addr>')
-        .option('--public-address <addr>')
         .option('--label <label>', 'node label (repeatable)', collect, []);
-    addNodeIdentityOptions(command).action(async (sshArgument, o) => runNodeIdentity(sshArgument, o, mode, repair));
+    addNodeIdentityOptions(command).action(async (sshArgument, o, command) => runNodeIdentity(sshArgument, o, mode, command, repair));
 }
 program
     .command('node-prepare-enrollment')
     .description('mint a single-use, name-bound join key so a host you cannot SSH to can self-join with one docker run; a saved cloud-init document contains a credential')
     .requiredOption('--name <name>', 'the node name the key is bound to; mint one key per instance')
+    .option('--address <addr>', 'private inter-node address for this node')
     .option('--agent-control-url <url>', 'connect-only URL the agent dials; the certificate is still verified against the credential URL')
     .option('--ttl <seconds>', 'join key lifetime', '3600')
     .option('--image <tag>', "agent image used in the printed docker run (default: ghcr.io/wpelevator/tug:<this CLI's version>)")
-    .option('--mesh', 'print a docker run that joins the WireGuard mesh (host networking, NET_ADMIN)')
     .option('--label <label>', 'node label (repeatable)', collect, [])
     .option('--install-docker', 'print cloud-init that installs Docker and starts the agent')
     .option('--json', 'print JSON including the command or cloud-init payload')
     .action(async (o) => {
+    if (o.address !== undefined && !isNodeHost(o.address))
+        throw new Error('address must be an IP address or hostname without a port');
     const connectUrl = o.agentControlUrl ? normalizeControlUrl(o.agentControlUrl) : undefined;
     const minted = await request('POST', '/api/v1/nodes/enrollment-credential', {
         name: o.name,
@@ -478,7 +459,7 @@ program
         ...(connectUrl ? { connectUrl } : {}),
     };
     const joinKey = Buffer.from(JSON.stringify(keyPayload)).toString('base64url');
-    const command = dockerRunSnippet(resolveImage(o.image), joinKey, o.mesh);
+    const command = dockerRunSnippet(resolveImage(o.image), joinKey, o.address);
     const cloudInit = o.installDocker
         ? enrollmentCloudInit(await dockerBootstrap(), command)
         : undefined;
@@ -758,7 +739,14 @@ program
         const directory = await fs.mkdtemp(path.join(os.tmpdir(), 'tug-local-build-'));
         try {
             const form = new FormData();
-            const localImages = await prepareLocalImages(compose, process.cwd(), directory);
+            const source = Object.values(compose.services).some((service) => service.build)
+                ? await createLocalBuildSnapshot(process.cwd(), directory, [
+                    cfg.file,
+                    cfg.localFile,
+                    ...(cfg.credentialFile ? [cfg.credentialFile] : []),
+                ])
+                : process.cwd();
+            const localImages = await prepareLocalImages(compose, source, directory);
             for (const { field } of localImages)
                 form.append(field, await openAsBlob(path.join(directory, `${field}.tar.gz`)), `${field}.tar.gz`);
             form.append('payload', JSON.stringify({ project, version, compose, localImages }));
@@ -792,7 +780,11 @@ program
 });
 program
     .command('status')
-    .action(async () => console.log(JSON.stringify(await request('GET', '/api/v1/status'), null, 2)));
+    .option('--human', 'show a readable summary instead of JSON')
+    .action(async (o) => {
+    const status = await request('GET', '/api/v1/status');
+    console.log(o.human ? formatStatus(status) : JSON.stringify(status, null, 2));
+});
 program
     .command('events')
     .description('list recent events with the credential that caused each control action; defaults to the resolved project')
@@ -984,7 +976,6 @@ program.hook('preAction', async (_root, command) => {
     const options = command.opts();
     for (const [key, min, max] of [
         ['port', 1, 65535],
-        ['wgPort', 1, 65535],
         ['timeout', 1, 86400],
         ['ttl', 1, 31536000],
         ['uses', 1, 1000000],
@@ -1032,7 +1023,9 @@ program.hook('preAction', async (_root, command) => {
             : undefined;
     applyConfigDefaults(command, options, {
         ...resolvedConfig.commandDefaults,
-        ...(command.name().startsWith('node-') ? nodeSettings(resolvedConfig, nodeName) : {}),
+        ...(command.name().startsWith('node-') || command.name() === 'control-install'
+            ? nodeSettings(resolvedConfig, nodeName)
+            : {}),
     });
 });
 for (const command of program.commands) {

package/dist/container-spec.d.ts

@@ -1,4 +1,5 @@
 import type { CreateContainerBody } from './docker-api.ts';
+import type { VolumeInspect } from './docker-api.ts';
 import type { DesiredState, ServiceEndpoint } from './protocol.ts';
 import type { PortBind } from './compose.ts';
 export declare const LABEL_PROJECT = "tug.project";
@@ -7,10 +8,14 @@ export declare const LABEL_JOB = "tug.job";
 export declare const LABEL_SERVICE = "tug.service";
 export declare const LABEL_REVISION = "tug.revision";
 export declare const LABEL_HASH = "tug.config-hash";
+/** Never treat a Docker name alone as proof of ownership; validate its labels before reuse. */
+export declare function assertVolumeOwnership(volume: VolumeInspect, project: string, name: string): void;
 /** The project network every container of the project joins; service names are its aliases. */
 export declare const networkName: (project: string) => string;
 /** Docker volume name for a Compose volume; `external` volumes keep their own name. */
 export declare const volumeName: (project: string, volume: string) => string;
+/** Scratch volumes occupy a separate namespace from project-managed volumes. */
+export declare const scratchVolumeName: (project: string, restore: string) => string;
 export declare const containerName: (project: string, service: string, hash: string) => string;
 export interface VolumeSpec {
     /** Docker volume name. */

package/dist/container-spec.js

@@ -9,10 +9,17 @@ export const LABEL_JOB = 'tug.job';
 export const LABEL_SERVICE = 'tug.service';
 export const LABEL_REVISION = 'tug.revision';
 export const LABEL_HASH = 'tug.config-hash';
+/** Never treat a Docker name alone as proof of ownership; validate its labels before reuse. */
+export function assertVolumeOwnership(volume, project, name) {
+    if (volume.Labels?.[LABEL_PROJECT] !== project || volume.Labels?.['tug.volume'] !== name)
+        throw new Error(`volume ${volume.Name} is not owned by project ${project} as volume ${name}`);
+}
 /** The project network every container of the project joins; service names are its aliases. */
 export const networkName = (project) => `tug_${project}`;
 /** Docker volume name for a Compose volume; `external` volumes keep their own name. */
-export const volumeName = (project, volume) => `tug_${project}_${volume}`;
+export const volumeName = (project, volume) => `tug_v${project.length}_${project}_${volume}`;
+/** Scratch volumes occupy a separate namespace from project-managed volumes. */
+export const scratchVolumeName = (project, restore) => `tug_r${project.length}_${project}_${restore}`;
 export const containerName = (project, service, hash) => `tug-${project}-${service}-${hash.slice(0, 8)}`;
 const SECOND_NS = 1_000_000_000;
 const UNITS = {
@@ -113,10 +120,12 @@ function volumeSpecs(desired, node, used) {
     for (const key of [...used].sort()) {
         const def = desired.compose.volumes?.[key] || {};
         const xe = def['x-tug'] || {};
+        const customLabels = { ...(def.labels || {}) };
+        delete customLabels['tug.restore'];
         const labels = {
+            ...customLabels,
             [LABEL_PROJECT]: desired.project,
             'tug.volume': key,
-            ...(def.labels || {}),
         };
         if (def.external) {
             out.push({

package/dist/control-credential.d.ts

@@ -2,6 +2,8 @@ export interface IssueArgs {
     name: string;
     role: string;
     replace: boolean;
+    /** The control URL to write into the credential; defaults to `TUG_CONTROL_URL`. */
+    controlUrl?: string;
 }
 export declare function parseIssueArgs(argv: string[]): IssueArgs;
 /**

package/dist/control-credential.js

@@ -25,15 +25,15 @@ export function parseIssueArgs(argv) {
  */
 export async function issueHostCredential(args) {
     const dataDir = process.env.TUG_DATA_DIR || './data';
-    const advertiseUrl = process.env.TUG_ADVERTISE_URL;
-    if (!advertiseUrl)
-        throw new Error('TUG_ADVERTISE_URL is required');
+    const controlUrl = args.controlUrl ?? process.env.TUG_CONTROL_URL;
+    if (!controlUrl)
+        throw new Error('TUG_CONTROL_URL is required');
     const db = await openDb(path.join(dataDir, 'tug.db'));
     try {
         const fresh = !db.get('SELECT 1 FROM operator_credentials') && !db.get('SELECT 1 FROM nodes');
         const pki = await Pki.load(path.join(dataDir, 'pki'), fresh);
         const request = parseCredentialRequest({ name: args.name, role: args.role });
-        const created = await createCredential(db, pki, new URL(advertiseUrl).origin, request, 'host', {
+        const created = await createCredential(db, pki, new URL(controlUrl).origin, request, 'host', {
             replace: args.replace,
         });
         if (args.replace)

package/dist/control.d.ts

@@ -27,7 +27,7 @@ export declare function createApp(options?: {
     openDatabase?: typeof openDb;
     /** Minimum time between event prunes triggered by agent reports; default one hour. */ eventPruneIntervalMs?: number;
     /** Override the live open/agent startup timeout in milliseconds. */ liveStartTimeoutMs?: number;
-    /** Credential-free HTTPS origin clients use to reach control; defaults to `TUG_ADVERTISE_URL`. */ advertiseUrl?: string;
+    /** Credential-free HTTPS origin clients connect to by default; defaults to `TUG_CONTROL_URL`. */ controlUrl?: string;
     /**
      * Replaces certificate-based identity resolution. Only for in-process tests that skip TLS; production never sets it.
      * It returns the principal URI and key hash a connection would have presented.