@wpelevator/tug 0.9.0 → 0.10.0

package/README.md

@@ -10,14 +10,15 @@ Deploy Docker Compose applications to one or more ordinary Linux VPSes through a
 - Nodes join over SSH (`node-install`) or enroll themselves with a single `docker run` after `node-prepare-enrollment`, each with its own certificate and an immutable node ID. Agents only dial out, so nodes behind NAT work.
 - Agents pull desired state from control, reconcile containers through the Docker Engine API, run TCP/HTTP/Docker health checks and report status. An outbound WebSocket wakes them as soon as control queues work and carries live `exec`, followed logs, `ps` and `inspect` sessions, with long-poll and periodic-poll fallbacks for ordinary work.
 - `x-tug` placement of services and volumes on nodes, with immutable desired-state records per deployment.
-- Build application images on control from uploaded source, or locally with `deploy --build-local`. Agents download saved images directly from control. Published images are pinned to registry digests at deployment creation.
+- Build application images on control from uploaded source, or locally with `deploy --build-local`. Both use a filtered source snapshot that excludes known Tug credentials; operators must still exclude other secrets. Agents download saved images directly from control. Published images are pinned to registry digests at deployment creation.
 - Secrets encrypted at rest, released only to the nodes whose services reference them, with targeted service recreation when only a secret changes.
 - Deployment convergence, per-project operation locks, cancellation, rollback, per-service rollout events and log fetching through the agents.
 - Opt-in zero-downtime rolling rollouts for ingress-fronted services (`x-tug.rollout`) and automatic rollback of failed deployments (`x-tug.rollback: auto`). See [Compose extensions](docs/compose.md#rolling-rollouts).
 - Private published images use encrypted project credentials for digest resolution and Engine API pulls.
-- Optional WireGuard mesh between nodes, health-aware cross-node service names (hosts-file entries injected into containers) and a managed Caddy ingress with automatic HTTPS, each opt-in. See [Networking](docs/networking.md).
-- Private-by-default published ports: generated Compose binds them to the overlay IP, loopback or the node address, never every interface unless you write `0.0.0.0`. See [Networking](docs/networking.md#published-ports-private-by-default).
+- Health-aware cross-node service names (hosts-file entries injected into containers), on by default with a `TUG_SERVICE_NAMES=false` opt-out, and an optional managed Caddy ingress with automatic HTTPS. Both use each node's private `address` on your existing network. See [Networking](docs/networking.md).
+- Private-by-default published ports: agent-generated container definitions bind them to the node address or loopback, never every interface unless you write `0.0.0.0`. Tug does not encrypt node-to-node workload traffic; your network owns reachability, firewalling and encryption. See [Networking](docs/networking.md#published-ports-private-by-default).
 - Workload backups of service commands and volumes with restic, a separate control-plane backup and restore, and `tug doctor` diagnostics for certificate expiry, node connectivity and clock skew.
+- `tug status --human` summarizes deployments, node reports and failures; the default JSON output remains available for automation.
 
 ## How it fits together
 
@@ -38,17 +39,19 @@ Deploy Docker Compose applications to one or more ordinary Linux VPSes through a
        |                       |
 +------+------------+   +------+------------------+
 | Node app1         |   | Node app2 (ingress node)|
-|   Agent           |<->|   Agent                 |
+|   Agent           |   |   Agent                 |
 |   Docker Engine   |   |   Docker Engine         |
 |   services        |   |   services              |
 |                   |   |   managed Caddy ingress |
 +-------------------+   +-------------------------+
-        <-> optional WireGuard mesh between nodes
+        \_________________________/
+          workload traffic between node addresses
+          over the operator's private network
 
   SSH is used only by the CLI to install the control plane and nodes.
 ```
 
-Operators and CI talk to the control API. The control plane stores desired state and builds images; each agent dials out to fetch the work for its node, applies it through the Docker Engine API and reports health back, so nodes behind NAT need no inbound ports. SSH is used only to install the control plane and its nodes. The optional WireGuard mesh and Caddy ingress are described in [Networking](docs/networking.md), and every flow in detail in [Architecture](docs/architecture.md).
+Operators and CI talk to the control API. The control plane stores desired state and builds images; each agent dials out to fetch the work for its node, applies it through the Docker Engine API and reports health back, so the control channel works through NAT without inbound ports. SSH is used only to install the control plane and its nodes. Cross-node service names and Caddy ingress use each node's `address` over the operator's private network; Tug provides no overlay or encryption for that workload traffic. See [Networking](docs/networking.md), and [Architecture](docs/architecture.md) for every flow in detail.
 
 ## Quick start
 
@@ -56,14 +59,16 @@ Install the CLI (Node >= 22.18), or run it without installing through `npx @wpel
 
 ```bash
 npm install -g @wpelevator/tug
-tug control-install root@203.0.113.5 --advertise-url https://203.0.113.5:8443 --install-docker
+tug control-install root@203.0.113.5 --install-docker
 tug init tug-root.credential.json
-tug node-install root@198.51.100.7 --name app1 --install-docker
+tug node-install root@198.51.100.7 --name app1 --address 10.0.0.7 --install-docker
 tug deploy -f docker-compose.yml
 ```
 
 The CLI installs the matching `ghcr.io/wpelevator/tug:<version>` image on your hosts. Control serves mutual TLS directly on its port (`8443`): every operator, CI job and node authenticates with a certificate from a private CA created at install, and clients verify a name generated from that CA, so the address can be a bare IP and can change later. Do not terminate TLS in front of it.
 
+A `controlUrl` in `tug.yml` is the one name for where control is: `control-install` advertises it, and every other command connects to it. Pass `--control-url` (or set `TUG_CONTROL_URL`) to override it for one invocation. See [CLI configuration](docs/cli.md#config-file) for precedence and per-node defaults.
+
 The full walkthrough, including nodes you cannot SSH to (`tug node-prepare-enrollment`), CI credentials (`tug credential-create`), moving the control plane and recovery, is in [Getting started](docs/getting-started.md).
 
 ## Documentation
@@ -72,11 +77,11 @@ The full walkthrough, including nodes you cannot SSH to (`tug node-prepare-enrol
 - [Terminology](docs/terminology.md): core concepts, the naming review (which recommendations are implemented), industry comparisons and the remaining proposed interface improvements.
 - [Architecture](docs/architecture.md): components, reconciliation, workflow diagrams, secrets and runtime paths.
 - [Compose extensions](docs/compose.md): `x-tug` placement, health checks, volumes and limitations.
-- [Control plane](docs/control-plane.md): install, mutual TLS and the private CA, image delivery, control-plane backup and restore.
+- [Control plane](docs/control-plane.md): install, mutual TLS and the private CA, image delivery, control-plane backup and recovery on another host.
 - [Backups](docs/backups.md): scheduled workload backups with `x-tug.backup` (restic), restore, recipes for common databases, and a restore drill. See also the [WordPress example](examples/wordpress/README.md).
 - [Access control](docs/access-control.md): certificate identity classes, scoped operator credentials, roles, audit trail and a GitHub Actions deploy example.
 - [Security](docs/security.md): deployment trust boundaries, security audit findings and validation limits.
-- [Networking](docs/networking.md): WireGuard mesh, cross-node service names, ingress and TLS, firewall notes.
+- [Networking](docs/networking.md): bring-your-own private networking, cross-node service names, ingress and TLS, firewall notes.
 - [Nodes](docs/nodes.md): node names and IDs, SSH install, self-service enrollment, certificate renewal and recovery, registration and status.
 - [CLI reference](docs/cli.md): every `tug` command and option.
 - [Configuration](docs/configuration.md): CLI, control and agent environment variables.
@@ -86,6 +91,7 @@ The full walkthrough, including nodes you cannot SSH to (`tug node-prepare-enrol
 - [Releases](docs/releases.md): changesets, npm and Docker image publishing.
 - [Standalone binary](docs/standalone-binary.md): proposed Bun-compiled CLI binaries and Homebrew distribution, with the mTLS dependency findings.
 - [Roadmap](docs/roadmap.md): goals, principles, the reference WordPress topology and planned milestones.
+- [Docker Swarm comparison](docs/swarm-comparison.md): overlapping capabilities, workflow advantages, scheduling and networking limits, failure behavior and workload fit.
 
 ## Development
 

package/dist/agent.d.ts

@@ -6,7 +6,7 @@ import type { ContainerSummary, DockerApi } from './docker-api.ts';
 import type { AgentLiveCommand, AgentLiveFrame } from './protocol.ts';
 import type { LiveEngineOptions } from './live.ts';
 import { parseDuration } from './util.ts';
-import type { HostRunner, HttpClient } from './runners.ts';
+import type { HttpClient } from './runners.ts';
 import type { Command, CommandResult, DesiredState, HealthCheck, ProjectStatus, ImageArtifact, PortBinding, ServiceEndpoint } from './protocol.ts';
 export interface AgentContext {
     docker: DockerApi;
@@ -17,10 +17,6 @@ export interface AgentContext {
     controlUrl: string;
     /** The node credential presented to control; absent only in tests with a fake `http`. */
     credential?: Credential;
-    /** Runs `wg` / `ip` for the mesh. */
-    host?: HostRunner;
-    /** Manage the WireGuard mesh (generate a key, report it, reconcile `wg0`). */
-    mesh?: boolean;
     caddyImage?: string;
     /** Host port range (`LOW-HIGH`) for rolling-rollout revisions; default 20000-20999. */
     rolloutPorts?: string;
@@ -96,8 +92,10 @@ export declare function resolveBindAddress(address: string | null, lookup?: (hos
     address: string;
 }>): Promise<string>;
 export declare function reconcile(desiredState: DesiredState, ctx?: AgentContext, endpoints?: Record<string, ServiceEndpoint[]>, ports?: PortBinding, held?: string[]): Promise<ProjectStatus>;
-/** Reports this node's WireGuard public key when control has not seen the current one yet. */
-export declare function reportWgKey(ctx: AgentContext): Promise<void>;
+/** Docker `extra_hosts` values must be IPs, so resolve hostname node addresses on this agent. */
+export declare function endpointAddressesForAgent(endpoints?: Record<string, ServiceEndpoint[]>, localServices?: Set<string>, lookup?: (host: string) => Promise<{
+    address: string;
+}>): Promise<Record<string, ServiceEndpoint[]>>;
 export declare function pollOnce(ctx?: AgentContext): Promise<ProjectStatus[]>;
 /** Loads the persisted identity, or enrolls with a join key. Without either the agent refuses to start. */
 export declare function loadOrEnroll(): Promise<AgentDocument>;

package/dist/agent.js

@@ -13,7 +13,7 @@ import { agentIdentityCsr, createTransport, describeMissingIdentity, installIden
 import { clientTlsOptions, parseCredential } from "./pki.js";
 import { createHash } from 'node:crypto';
 import { addressBoundServices, isRolling, serviceSecretVersions } from "./compose.js";
-import { LABEL_PROJECT, LABEL_SERVICE, containerSpecs, networkName, volumeName, } from "./container-spec.js";
+import { LABEL_PROJECT, LABEL_SERVICE, assertVolumeOwnership, containerSpecs, networkName, volumeName, } from "./container-spec.js";
 import { API_VERSION, DockerEngine, isNotFound } from "./docker-api.js";
 import { JobRunner } from "./agent-jobs.js";
 import { LIVE_MAX_FRAME_BYTES, LIVE_START_TIMEOUT_MS } from "./protocol.js";
@@ -21,17 +21,13 @@ import { LiveOperationEngine } from "./live.js";
 import { activeRollingStates, clearRolloutState, ensureProjectResources, loadRolloutState, projectContainers, reconcileRecreate, reconcileRolling, sweepOrphans, } from "./reconciler.js";
 import { ensureDir, errMessage, isPublicAddress, now, parseDuration } from "./util.js";
 import { openAgentDb } from "./db.js";
-import { createHostRunner } from "./runners.js";
 import { CADDY_CONTAINER, reconcileIngress, removeIngress } from "./ingress.js";
-import { WG_INTERFACE, ensureWgKeys, readReportedKey, reconcileMesh, rotateWgKeys, writeReportedKey, } from "./mesh.js";
 // Connect-only override (for example an SSH tunnel); the certificate is still verified against the credential's public URL.
 const CONTROL_URL_OVERRIDE = process.env.TUG_CONTROL_URL;
 let NODE_NAME = process.env.TUG_NODE_NAME || process.env.HOSTNAME || 'node1';
 const STATE_DIR = process.env.TUG_STATE_DIR || '/var/lib/tug';
 const APPLY = process.env.TUG_APPLY !== 'false';
 const INTERVAL = Number(process.env.TUG_POLL_INTERVAL_MS || 5000);
-// Opt-in WireGuard mesh: needs `wg`/`ip` in the agent image, host networking and NET_ADMIN.
-const MESH = process.env.TUG_MESH === 'true';
 let activeDocument;
 export function defaultContext(doc = activeDocument) {
     if (!doc)
@@ -45,8 +41,6 @@ export function defaultContext(doc = activeDocument) {
         apply: APPLY,
         controlUrl: transport.base,
         credential: doc,
-        host: createHostRunner(),
-        mesh: MESH,
         caddyImage: process.env.TUG_CADDY_IMAGE,
         rolloutPorts: process.env.TUG_ROLLOUT_PORTS,
     };
@@ -591,7 +585,7 @@ async function publicPortsCheck(ctx) {
                 name: 'ports.public',
                 ok: true,
                 stdout: stdout.slice(-4000),
-                warning: `${listeners.length} published port${listeners.length === 1 ? ' of Tug projects listens' : 's of Tug projects listen'} on a public address; bind them to 127.0.0.1, the overlay IP or a private address unless that is intended`,
+                warning: `${listeners.length} published port${listeners.length === 1 ? ' of Tug projects listens' : 's of Tug projects listen'} on a public address; bind them to 127.0.0.1 or a private node address unless that is intended`,
             }
             : {
                 name: 'ports.public',
@@ -633,10 +627,6 @@ export async function executeCommand(command, ctx = defaultContext()) {
             }
         }
         const extra = [];
-        if (ctx.mesh && ctx.host) {
-            const host = ctx.host;
-            extra.push(['wireguard.version', () => host('wg', ['--version'])], ['wireguard.interface', () => host('wg', ['show', WG_INTERFACE])]);
-        }
         if (await fs.stat(path.join(ctx.stateDir, 'ingress')).then(() => true, () => false)) {
             extra.push([
                 'ingress.caddy',
@@ -700,28 +690,21 @@ export async function executeCommand(command, ctx = defaultContext()) {
     if (command.type === 'volume.delete') {
         const { project, volume } = payload;
         // Volumes are never removed by reconciliation; this explicit command is the only way one goes away.
-        await ctx.docker.removeVolume(volumeName(project, volume)).catch((e) => {
-            if (!isNotFound(e))
-                throw e;
-        });
+        const name = volumeName(project, volume);
+        const existing = await ctx.docker.inspectVolume(name);
+        if (existing)
+            assertVolumeOwnership(existing, project, volume);
+        if (existing)
+            await ctx.docker.removeVolume(name).catch((e) => {
+                if (!isNotFound(e))
+                    throw e;
+            });
         return {
             commandId: command.id,
             state: 'succeeded',
             result: { project, volume, deleted: true },
         };
     }
-    if (command.type === 'wg.rotate-key') {
-        if (!ctx.mesh)
-            throw new Error('the WireGuard mesh is not enabled on this agent (TUG_MESH=true)');
-        const { publicKey } = await rotateWgKeys(ctx.stateDir);
-        await api(ctx, '/agent/v1/wireguard/key', {
-            method: 'POST',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({ publicKey }),
-        });
-        await writeReportedKey(ctx.stateDir, publicKey);
-        return { commandId: command.id, state: 'succeeded', result: { publicKey } };
-    }
     return {
         commandId: command.id,
         state: 'failed',
@@ -1051,7 +1034,7 @@ async function warnPublicPorts(ctx, desiredState, serviceNames, bind) {
         ? addressBoundServices(desiredState.compose, serviceNames, bind.loopback)
         : [];
     const message = exposed.length
-        ? `published ports of ${exposed.join(', ')} listen on public address ${bind.address}; enable the mesh, give the node a private address, or write the host IP in ports to make the exposure explicit`
+        ? `published ports of ${exposed.join(', ')} listen on public address ${bind.address}; give the node a private address, or write the host IP in ports to make the exposure explicit`
         : '';
     if ((publicPortWarnings.get(key) ?? '') === message)
         return;
@@ -1070,44 +1053,44 @@ async function warnPublicPorts(ctx, desiredState, serviceNames, bind) {
         }),
     }).catch(() => { });
 }
-/** Reports this node's WireGuard public key when control has not seen the current one yet. */
-export async function reportWgKey(ctx) {
-    const { publicKey } = await ensureWgKeys(ctx.stateDir);
-    if ((await readReportedKey(ctx.stateDir)) === publicKey)
-        return;
-    await api(ctx, '/agent/v1/wireguard/key', {
-        method: 'POST',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({ publicKey }),
-    });
-    await writeReportedKey(ctx.stateDir, publicKey);
-}
-let lastNetworkError = '';
-async function networkStep(label, fn) {
-    try {
-        await fn();
-        lastNetworkError = '';
-    }
-    catch (e) {
-        const message = `${label}: ${errMessage(e)}`;
-        if (message !== lastNetworkError)
-            console.error(message);
-        lastNetworkError = message;
-    }
+/** Docker `extra_hosts` values must be IPs, so resolve hostname node addresses on this agent. */
+export async function endpointAddressesForAgent(endpoints = {}, localServices = new Set(), lookup = (host) => dns.lookup(host)) {
+    const cache = new Map();
+    const resolve = (address) => {
+        if (net.isIP(address))
+            return Promise.resolve(address);
+        let resolved = cache.get(address);
+        if (!resolved) {
+            resolved = lookup(address).then(({ address: ip }) => ip, (error) => {
+                throw new Error(`cannot resolve node address ${address} for cross-node service names: ${errMessage(error)}`, { cause: error });
+            });
+            cache.set(address, resolved);
+        }
+        return resolved;
+    };
+    return Object.fromEntries(await Promise.all(Object.entries(endpoints)
+        .filter(([service]) => !localServices.has(service))
+        .map(async ([service, list]) => [
+        service,
+        (await Promise.all(list.map(async (ep) => {
+            try {
+                return { ...ep, address: await resolve(ep.address) };
+            }
+            catch (error) {
+                console.error(errMessage(error));
+                return null;
+            }
+        }))).filter((ep) => ep !== null),
+    ])));
 }
 export async function pollOnce(ctx = defaultContext()) {
-    if (ctx.mesh)
-        await networkStep('wireguard key report failed', () => reportWgKey(ctx));
     const work = await api(ctx, '/agent/v1/work');
-    // The mesh comes up first so cross-node service endpoints are routable when containers start.
-    if (ctx.mesh && work.network) {
-        const network = work.network;
-        await networkStep('wireguard reconcile failed', () => reconcileMesh(ctx.host ?? createHostRunner(), ctx.stateDir, network));
-    }
     const projects = [];
     for (const desired of work.desiredStates || (work.desiredState ? [work.desiredState] : [])) {
         try {
-            projects.push(await reconcile(desired, ctx, work.serviceEndpoints?.[desired.project], work.ports, work.holds?.[desired.project]));
+            projects.push(await reconcile(desired, ctx, await endpointAddressesForAgent(work.serviceEndpoints?.[desired.project], new Set(Object.entries(desired.services)
+                .filter(([, spec]) => spec.placement?.nodes?.includes(ctx.nodeName))
+                .map(([name]) => name))), work.ports, work.holds?.[desired.project]));
         }
         catch (e) {
             projects.push({
@@ -1198,12 +1181,9 @@ async function enroll(joinKey) {
     const transport = createTransport(decoded.credential, CONTROL_URL_OVERRIDE || decoded.connectUrl);
     console.log(`enrolling with ${decoded.credential.url} as ${decoded.name}`);
     const csr = await agentIdentityCsr(STATE_DIR);
-    const wgPublicKey = MESH ? (await ensureWgKeys(STATE_DIR)).publicKey : undefined;
     const body = {
         csr,
         address: process.env.TUG_NODE_ADDRESS,
-        publicAddress: process.env.TUG_NODE_PUBLIC_ADDRESS,
-        wgPublicKey,
     };
     try {
         const res = await transport.http(`${transport.base}/agent/v1/enroll`, {
@@ -1214,8 +1194,6 @@ async function enroll(joinKey) {
         if (!res.ok)
             throw new Error(`enroll failed: ${res.status} ${await res.text()}`);
         const doc = await installIdentity(STATE_DIR, (await res.json()));
-        if (wgPublicKey)
-            await writeReportedKey(STATE_DIR, wgPublicKey);
         console.log(`enrolled as node ${doc.nodeName}`);
         return doc;
     }

package/dist/backup-job.js

@@ -1,6 +1,6 @@
 import { Transform } from 'node:stream';
 import { redactSecrets } from "./backup-destination.js";
-import { LABEL_JOB, LABEL_PROJECT, LABEL_SERVICE } from "./container-spec.js";
+import { LABEL_JOB, LABEL_PROJECT, LABEL_SERVICE, assertVolumeOwnership, volumeName, } from "./container-spec.js";
 /** Docker volume holding restic's cache across jobs, so repeated runs do not re-read the repository index. */
 export const RESTIC_CACHE_VOLUME = 'tug_restic_cache';
 const TAIL_BYTES = 4096;
@@ -148,14 +148,26 @@ export async function runBackupJob(payload, commandId, ctx, kind = 'backup.run')
             if (scratch) {
                 if (!dockerVolume)
                     throw new JobError('a scratch restore needs a scratch volume name');
-                if (!(await docker.inspectVolume(dockerVolume)))
+                let existing = await docker.inspectVolume(dockerVolume);
+                if (!existing) {
                     await docker.createVolume(dockerVolume, {
                         labels: { 'tug.project': payload.project, 'tug.restore': payload.runId },
                     });
+                    existing = await docker.inspectVolume(dockerVolume);
+                }
+                if (existing?.Labels?.[LABEL_PROJECT] !== payload.project ||
+                    existing.Labels?.['tug.restore'] !== payload.runId)
+                    throw new JobError(`scratch volume ${dockerVolume} is not owned by this restore`);
+            }
+            else {
+                if (dockerVolume !== volumeName(payload.project, payload.volume.name))
+                    throw new JobError('volume name does not match the project and target');
+                const existing = await docker.inspectVolume(dockerVolume);
+                if (!existing)
+                    // Docker would silently create an empty volume for a missing name and the backup would succeed with nothing in it.
+                    throw new JobError(`volume ${dockerVolume} does not exist on this node; a volume is created when a service that uses it is placed here`);
+                assertVolumeOwnership(existing, payload.project, payload.volume.name);
             }
-            else if (!(await docker.inspectVolume(dockerVolume)))
-                // Docker would silently create an empty volume for a missing name and the backup would succeed with nothing in it.
-                throw new JobError(`volume ${dockerVolume} does not exist on this node; a volume is created when a service that uses it is placed here`);
             binds.push(`${dockerVolume}:/data${kind === 'backup.restore' ? '' : ':ro'}`);
         }
         const restic = await helper('restic', {

package/dist/backup-restore.js

@@ -1,5 +1,5 @@
 import { id } from "./util.js";
-import { volumeName } from "./container-spec.js";
+import { scratchVolumeName } from "./container-spec.js";
 const MINUTE = 60_000;
 const LOCK_TTL_MS = 15 * MINUTE;
 const HOLD_TIMEOUT_MS = 5 * MINUTE;
@@ -77,6 +77,8 @@ export function createRestoreService(deps) {
     }
     /** Validates a request and describes what a restore would do; nothing is changed. */
     function plan(request) {
+        // The most recent deployment may have moved the target since the last scheduler tick.
+        backups.sync();
         const desired = deployed(request.project);
         if (!desired)
             return { error: `project ${request.project} has no successful deployment`, status: 409 };
@@ -115,9 +117,7 @@ export function createRestoreService(deps) {
             snapshotId: snapshot.snapshotId,
             snapshotTime: snapshot.time,
             mode,
-            ...(mode === 'scratch'
-                ? { scratchVolume: volumeName(request.project, `restore-${id('r').slice(-6)}`) }
-                : {}),
+            ...(mode === 'scratch' ? { scratchVolume: scratchVolumeName(request.project, id('r')) } : {}),
             writers,
             safetyBackup: mode === 'in-place' && request.safetyBackup !== false,
         };

package/dist/backup-scheduler.js

@@ -397,6 +397,8 @@ export function createBackupService(deps) {
     }
     /** Queues the `backup.restore` job for a target on its node. */
     function queueRestore(project, target, restore, runId) {
+        // Placement can change after planning; never queue a restore using a stale schedule.
+        sync();
         const schedule = db.get('SELECT * FROM backup_schedules WHERE project_id=? AND target=? AND enabled=1', project, target);
         const current = deployed(project)[0];
         if (!schedule || !current)

package/dist/cli-build.d.ts

@@ -11,5 +11,7 @@ export interface LocalBuildDependencies {
 /** Credential exclusions are mandatory and cannot be re-included by source ignore rules. The tracked config names are excluded at the context root only, so an app's own nested `tug.json` is kept. */
 export declare function sourceArchiveFilter(entry: string, configPaths: string[], ignores: string[]): boolean;
 export declare function createSourceArchive(contextDir: string, archive: string, configFiles: string[]): Promise<void>;
+/** Build from the same filtered, validated source snapshot used for remote builds. */
+export declare function createLocalBuildSnapshot(contextDir: string, directory: string, configFiles: string[]): Promise<string>;
 /** Build only application build services; callers own temporary files and upload transport. */
 export declare function prepareLocalImages(compose: ComposeFile, contextDir: string, directory: string, dependencies?: LocalBuildDependencies): Promise<LocalImageUpload[]>;

package/dist/cli-build.js

@@ -2,7 +2,7 @@ import path from 'node:path';
 import fs from 'node:fs/promises';
 import { randomUUID } from 'node:crypto';
 import * as tar from 'tar';
-import { buildImage, run } from "./build.js";
+import { buildImage, run, unpackContext } from "./build.js";
 import { saveImageArchive } from "./artifacts.js";
 import { CONFIG_NAMES } from "./cli-config.js";
 /** At any depth: the git directory and every file that can hold a token (the untracked config overlays). */
@@ -122,6 +122,19 @@ export async function createSourceArchive(contextDir, archive, configFiles) {
         filter: (entry) => sourceArchiveFilter(entry, configPaths, ignores),
     }, ['.']);
 }
+/** Build from the same filtered, validated source snapshot used for remote builds. */
+export async function createLocalBuildSnapshot(contextDir, directory, configFiles) {
+    const archive = path.join(directory, 'source.tgz');
+    const snapshot = path.join(directory, 'source');
+    try {
+        await createSourceArchive(contextDir, archive, configFiles);
+        await unpackContext(archive, snapshot);
+        return snapshot;
+    }
+    finally {
+        await fs.rm(archive, { force: true });
+    }
+}
 /** Build only application build services; callers own temporary files and upload transport. */
 export async function prepareLocalImages(compose, contextDir, directory, dependencies = {
     build: buildImage,

package/dist/cli-config.d.ts

@@ -1,5 +1,5 @@
 import type { Credential } from './pki.ts';
-export type SettingType = 'string' | 'boolean' | 'port' | 'list' | 'path';
+export type SettingType = 'string' | 'boolean' | 'list' | 'path';
 export interface Setting {
     type: SettingType;
     /** The flag or positional argument the key stands for; the key is the camelCase of the long flag. */
@@ -28,6 +28,9 @@ export interface ResolvedCliConfig {
     localFile: string;
     /** Where connections go: the credential's public URL unless overridden (an override changes the connect target only). */
     controlUrl: string;
+    /** Shared config address for installation, before connection-only flags, environment and credential defaults. */
+    /** The control URL the operator asked for (flag, environment or config), without credential or default fallbacks. */
+    requestedControlUrl?: string;
     credential?: Credential;
     credentialFile?: string;
     project: string;

package/dist/cli-config.js

@@ -8,7 +8,18 @@ import { errMessage } from "./util.js";
 export const COMMAND_SETTINGS = {
     file: { type: 'path', flag: '--file', commands: ['deploy'] },
     buildLocal: { type: 'boolean', flag: '--build-local', commands: ['deploy'] },
-    wait: { type: 'boolean', flag: '--no-wait', commands: ['deploy', 'rollback'] },
+    wait: {
+        type: 'boolean',
+        flag: '--no-wait',
+        commands: [
+            'deploy',
+            'rollback',
+            'backup-run',
+            'node-install',
+            'node-replace-identity',
+            'node-repair-identity',
+        ],
+    },
 };
 /** Per-node connection data (`nodes.<name>`); `nodeDefaults` takes the subset that is not node-specific. */
 export const NODE_SETTINGS = {
@@ -17,32 +28,28 @@ export const NODE_SETTINGS = {
         flag: '<ssh-target>',
         commands: ['node-install', 'node-replace-identity', 'node-repair-identity'],
     },
-    address: { type: 'string', flag: '--address', commands: ['node-install', 'node-register'] },
-    publicAddress: {
+    address: {
         type: 'string',
-        flag: '--public-address',
-        commands: ['node-install', 'node-register'],
+        flag: '--address',
+        commands: [
+            'node-install',
+            'node-replace-identity',
+            'node-repair-identity',
+            'node-register',
+            'node-prepare-enrollment',
+        ],
     },
     label: {
         type: 'list',
         flag: '--label',
-        commands: ['node-install', 'node-register', 'node-prepare-enrollment'],
-    },
-    mesh: {
-        type: 'boolean',
-        flag: '--mesh',
         commands: [
             'node-install',
             'node-replace-identity',
             'node-repair-identity',
+            'node-register',
             'node-prepare-enrollment',
         ],
     },
-    wgPort: {
-        type: 'port',
-        flag: '--wg-port',
-        commands: ['node-install', 'node-replace-identity', 'node-repair-identity'],
-    },
     installDocker: {
         type: 'boolean',
         flag: '--install-docker',
@@ -51,6 +58,7 @@ export const NODE_SETTINGS = {
             'node-replace-identity',
             'node-repair-identity',
             'node-prepare-enrollment',
+            'control-install',
         ],
     },
     image: {
@@ -61,6 +69,7 @@ export const NODE_SETTINGS = {
             'node-replace-identity',
             'node-repair-identity',
             'node-prepare-enrollment',
+            'control-install',
         ],
     },
     agentControlUrl: {
@@ -74,7 +83,7 @@ export const NODE_SETTINGS = {
         ],
     },
 };
-const NODE_SPECIFIC_KEYS = ['ssh', 'address', 'publicAddress'];
+const NODE_SPECIFIC_KEYS = ['ssh', 'address'];
 const SETTINGS = { ...COMMAND_SETTINGS, ...NODE_SETTINGS };
 /** Default file names, in lookup order; more than one present is an error. */
 export const CONFIG_NAMES = ['tug.yml', 'tug.yaml', 'tug.json', '.tug.json'];
@@ -118,16 +127,14 @@ export async function resolveCliConfig(options, env, cwd, creating = false) {
             if (!creating)
                 throw new Error(`cannot use credential ${credentialFile ?? 'from TUG_CREDENTIAL'}: ${errMessage(e)}`, { cause: e });
         }
-    const controlUrl = options.controlUrl ||
-        env.TUG_CONTROL_URL ||
-        config.controlUrl ||
-        credential?.url ||
-        'https://localhost:8443';
+    const requestedControlUrl = options.controlUrl || env.TUG_CONTROL_URL || config.controlUrl;
+    const controlUrl = requestedControlUrl || credential?.url || 'https://localhost:8443';
     return {
         file,
         fileExists: Boolean(base),
         localFile,
         controlUrl: normalizeControlUrl(controlUrl),
+        requestedControlUrl: requestedControlUrl ? normalizeControlUrl(requestedControlUrl) : undefined,
         credential,
         credentialFile,
         project: options.project || env.TUG_PROJECT || config.project || 'site',
@@ -214,8 +221,6 @@ function settingValue(setting, value, where, dir) {
             if (typeof value !== 'boolean')
                 throw new Error(`${where} must be true or false`);
             return value;
-        case 'port':
-            return String(integerOption(String(value), where, 1, 65535));
         case 'list':
             return (Array.isArray(value) ? value : [value]).map((item, index) => text(item, Array.isArray(value) ? `${where}[${index}]` : where));
     }

package/dist/cli-install.d.ts

@@ -1,17 +1,20 @@
 /** 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 declare const HOST_NETWORK_FLAG = "--network host";
-export declare const MESH_RUN_FLAGS = "--network host --cap-add NET_ADMIN";
 /** Docker platform for the architecture a host reports with `uname -m`. */
 export declare function dockerPlatform(uname: string): string;
 /** Build for the host the image will run on, not the machine that builds it (an arm64 laptop and an amd64 VPS differ). */
 export declare function localImageBuildArgs(imageTag: string, uname: string): string[];
 export declare function shellQuote(value: unknown): string;
-export declare function dockerRunSnippet(image: string, joinKey: string, mesh?: boolean): string;
+export declare function dockerRunSnippet(image: string, joinKey: string, address?: string): string;
 /** The bootstrap runs in its own shell so its idempotent early exit cannot skip enrollment. */
 export declare function enrollmentCloudInit(bootstrap: string, command: string): string;
 /** Name of the container `control-install` creates (Compose project `tug-control`, service `control`). */
 export declare const CONTROL_CONTAINER = "tug-control-control-1";
 /** A TCP port is free, or is held by the control container this install would replace, so installing again upgrades in place. */
 export declare function controlPortCheck(port: number): string;
-/** An occupied mesh port is reusable only when the installed Tug agent owns the live key. */
-export declare function meshPortCheck(port: number): string;
+/**
+ * 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 declare function defaultControlUrl(sshTarget: string, port: number | string): string;