@esuyo/coding-container 1.0.2 → 1.0.3

package/README.md

@@ -1,20 +1,26 @@
 # Esuyo coding-container
 
-> Spin up a ready-to-code SSH container on your k3s cluster in one command.
+Spin up a ready-to-code SSH container on your Kubernetes cluster in one command.
 
-`coding-container` gives every project its own consistent coding environment. One command deploys a container with Ubuntu 26.04, Node.js 22, [opencode](https://opencode.ai), [pi](https://pi.dev), [herdr](https://herdr.dev), turbo, Playwright, and common dev tools (plus pnpm/yarn via corepack and a Postgres client) to your k3s cluster. You SSH in and land in `/workspace` — a folder backed by your NAS, so your work survives restarts and stays separate per project.
+`coding-container` gives every project its own consistent coding environment on Kubernetes.
+One command deploys an SSH-accessible container per project, you land in `/workspace`, backed by your NAS so work survives restarts.
+The default image is just a starting point (Ubuntu, Node.js, and common dev tools); the Dockerfile is yours to customize with any language or toolchain, plus optional sidecars for databases and queues.
+
+For private, internal Kubernetes clusters only. Do not expose to the public web. Every project opens NodePorts on all cluster nodes (SSH plus optional web/sidecar ports) and serves Ingress hosts without authentication or TLS by default. Only run this on a trusted internal network (homelab, LAN, or VPN-gated cluster) behind a firewall. See [Architecture](./docs/architecture.md#security-notes) for details.
 
 ## Features
 
 - One command to deploy a ready-to-code container (`create`), SSH in (`ssh`), and tear down (`delete`)
-- Persistent per-project workspace on your NAS — files survive restarts
+- Kubernetes-native: renders Deployment, Service, Ingress, ConfigMap, and Secret manifests and applies them with `kubectl`
+- Persistent per-project workspace on your NAS, so files survive restarts
 - Generates a dedicated SSH key; VS Code Remote-SSH ready
 - Optional browser access to dev servers and sidecars for databases and queues
-- Shared team image with versioning, or a custom image per project
+- Shared team image with versioning, or a custom image per project. Bring your own Dockerfile for any language or toolchain
 
 ## Prerequisites
 
-- Node.js >= 18, Docker, `kubectl` pointed at your k3s cluster
+- A private, internal Kubernetes cluster (any CNCF-conformant distribution) with `kubectl` access. Do not use on a publicly exposed cluster
+- Node.js >= 18, Docker, `kubectl` on `PATH`
 - `docker login` to your container registry
 - OpenSSH (`ssh`, `ssh-keygen`)
 - Your NAS reachable from the cluster nodes
@@ -58,38 +64,39 @@ See [Configuration](./docs/configuration.md) for layering, multiple projects, an
 
 ```sh
 coding-container create   # deploy this project
-coding-container ssh      # connect — you land in /workspace
+coding-container ssh      # connect, you land in /workspace
 coding-container delete   # remove cluster resources (files stay safe on the NAS)
 ```
 
-Working in another folder? `cd` there and run `create` — a minimal `config.yaml` is scaffolded automatically. Each project gets its own container and workspace.
+Working in another folder? `cd` there and run `create`: a minimal `config.yaml` is scaffolded automatically. Each project gets its own container and workspace.
 
-For everything else — web URLs, databases, image versions, all commands and flags — see [CLI reference](./docs/cli-reference.md) and the guides below.
+For everything else (web URLs, databases, image versions, all commands and flags), see [CLI reference](./docs/cli-reference.md) and the guides below.
 
 ## Troubleshooting
 
 - **Missing registry or NAS settings?** Run `coding-container setup`.
 - **Push auth error?** Run `docker login <your-registry>` first.
-- **Pod stuck?** Usually NFS or image pull — see [Troubleshooting](./docs/troubleshooting.md).
+- **Pod stuck?** Usually NFS or image pull. See [Troubleshooting](./docs/troubleshooting.md).
 
 ## License
 
-MIT — see [LICENSE](./LICENSE).
+MIT. See [LICENSE](./LICENSE).
 
 ## Developer Documentation
 
-- [Configuration](./docs/configuration.md) — Config layering, multiple projects, NAS volumes
-- [Shared global image](./docs/global-image.md) — Team image versions, publishing, rollback, cleanup
-- [Web access](./docs/web-access.md) — Browser access to dev servers via Traefik
-- [Sidecars](./docs/sidecars.md) — Databases, queues, and other pod companions
-- [CLI reference](./docs/cli-reference.md) — All commands and flags
-- [SSH and VS Code](./docs/ssh-and-vscode.md) — Key rotation and Remote-SSH setup
-- [Troubleshooting](./docs/troubleshooting.md) — Common failures and fixes
-- [Architecture](./docs/architecture.md) — Tech stack and system design
-- [Project Structure](./docs/project-structure.md) — Folder layout
-- [Development Guide](./docs/development.md) — Local setup for contributors
-- [App config & setup files](./docs/config-files.md) — Persisting tool configs via /workspace
-- [Plan: Additional NFS volumes](./docs/build/additional-volumes.md) — Design history for extra volumes
-- [Plan: Public prebuilt images](./docs/build/public-images.md) — Design history for public images
+- [Configuration](./docs/configuration.md): config layering, multiple projects, NAS volumes
+- [Shared global image](./docs/global-image.md): team image versions, publishing, rollback, cleanup
+- [Web access](./docs/web-access.md): browser access to dev servers via Traefik
+- [Sidecars](./docs/sidecars.md): databases, queues, and other pod companions
+- [CLI reference](./docs/cli-reference.md): all commands and flags
+- [SSH and VS Code](./docs/ssh-and-vscode.md): key rotation and Remote-SSH setup
+- [SSH image paste](./docs/ssh-image-paste.md): clipboard images into opencode over SSH
+- [Troubleshooting](./docs/troubleshooting.md): common failures and fixes
+- [Architecture](./docs/architecture.md): tech stack and system design
+- [Project Structure](./docs/project-structure.md): folder layout
+- [Development Guide](./docs/development.md): local setup for contributors
+- [App config & setup files](./docs/config-files.md): persisting tool configs via /workspace
+- [Plan: Additional NFS volumes](./docs/build/additional-volumes.md): design history for extra volumes
+- [Plan: Public prebuilt images](./docs/build/public-images.md): design history for public images
 
 ---

package/config.yaml

@@ -9,14 +9,15 @@ project: my-project
 k8s:
   nodePort: 30022
 
-# Expose container ports to the browser through Traefik: one Ingress host per
-# port, each routing to that port on this project's service. The hosts must
-# resolve (DNS) to your Traefik LoadBalancer IP. An optional nodePort
-# (30000-32767) additionally reaches the port on every cluster node at
-# http://<node-ip>:<nodePort>/ (unique across ssh, web.ports, sidecars).
+# Expose container ports to the browser through Traefik: one Ingress rule per
+# host ('hosts' list, or a single 'host'), each routing to that port on this
+# project's service. The hosts must resolve (DNS) to your Traefik LoadBalancer
+# IP. An optional nodePort (30000-32767) additionally reaches the port on every
+# cluster node at http://<node-ip>:<nodePort>/ (unique across ssh, web.ports,
+# sidecars).
 # web:
 #   ports:
-#     - { port: 3000, host: my-web.example.com, nodePort: 30080 }
+#     - { port: 3000, hosts: [my-web.example.com, www.example.com], nodePort: 30080 }
 #     - { port: 8080, host: my-api.example.com, name: api }
 
 # Extra NAS folders mounted into the container alongside /workspace. Each

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esuyo/coding-container",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "CLI to build, publish and deploy SSH-accessible coding containers on k3s",
   "type": "module",
   "bin": {

package/src/commands/build.js

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import { dockerExec, run } from "../utils/exec.js";
 import { imageRef } from "../config.js";
 
@@ -7,6 +8,18 @@ import { imageRef } from "../config.js";
  * global image).
  */
 export async function buildImage(cfg) {
+  if (!cfg.image.dockerfilePath || !fs.existsSync(cfg.image.dockerfilePath)) {
+    throw new Error(
+      `config: dockerfile not found: ${cfg.image.dockerfilePath ?? "(unset)"}. ` +
+        `Run 'coding-container setup' to provision one, or fix image.dockerfile in your config.`
+    );
+  }
+  if (!cfg.image.contextPath || !fs.existsSync(cfg.image.contextPath)) {
+    throw new Error(
+      `config: build context not found: ${cfg.image.contextPath ?? "(unset)"}. ` +
+        `Fix image.context in your config.`
+    );
+  }
   const ref = imageRef(cfg);
   const args = ["build", "-t", ref, "-f", cfg.image.dockerfilePath];
   for (const [key, value] of Object.entries(cfg.image.buildArgs || {})) {

package/src/commands/delete.js

@@ -1,5 +1,5 @@
 import { run } from "../utils/exec.js";
-import { removeHostEntry, sshAlias, sshConfigPath } from "../utils/ssh-config.js";
+import { removeHostEntry, removeLegacyKnownHostsFile, sshAlias, sshConfigPath } from "../utils/ssh-config.js";
 
 export async function deleteProject(cfg, { keepSecrets = false } = {}) {
   const ns = cfg.k8s.namespace;
@@ -21,4 +21,5 @@ export async function deleteProject(cfg, { keepSecrets = false } = {}) {
   } catch (err) {
     console.warn(`Warning: could not update SSH config: ${err.message}`);
   }
+  removeLegacyKnownHostsFile(cfg.ssh.keyDirPath, cfg.project);
 }

package/src/commands/deploy.js

@@ -4,7 +4,7 @@ import { ensureKeyPair, readPublicKey } from "../utils/keys.js";
 import { ensurePullSecret } from "../utils/registry.js";
 import { fullManifest, webPorts, sidecarNodePorts as sidecarNodePortsList } from "../utils/manifest.js";
 import { imageRef } from "../config.js";
-import { addHostEntry, sshAlias, sshConfigPath } from "../utils/ssh-config.js";
+import { addHostEntry, ephemeralKnownHostsFile, removeLegacyKnownHostsFile, sshAlias, sshConfigPath } from "../utils/ssh-config.js";
 import { findNodePortOwner } from "../utils/project.js";
 import { kubectlExec, resolveDeployTag, SYSTEM_CM_NAME } from "../utils/system-config.js";
 
@@ -97,7 +97,9 @@ export async function deploy(cfg, { wait = true } = {}) {
   if (web.length) {
     console.log("Web (Traefik Ingress):");
     for (const p of web) {
-      console.log(`  http://${p.host}/  (container port ${p.port})`);
+      for (const host of p.hosts) {
+        console.log(`  http://${host}/  (container port ${p.port})`);
+      }
     }
     const webNodePorts = web.filter((p) => p.nodePort !== undefined);
     if (webNodePorts.length) {
@@ -117,6 +119,8 @@ export async function deploy(cfg, { wait = true } = {}) {
   }
 
   // Register an SSH alias for the container (VS Code Remote-SSH / ssh).
+  // Host keys are ephemeral, so the alias points at the OS null device and
+  // any legacy per-project known_hosts file is removed.
   if (nodeIp) {
     try {
       const alias = sshAlias(cfg.project);
@@ -126,8 +130,11 @@ export async function deploy(cfg, { wait = true } = {}) {
         port: cfg.k8s.nodePort,
         user: cfg.ssh.user,
         identityFile: path.join(cfg.ssh.keyDirPath, cfg.ssh.keyName),
-        knownHostsFile: path.join(cfg.ssh.keyDirPath, `${cfg.project}-known_hosts`),
+        knownHostsFile: ephemeralKnownHostsFile(),
       });
+      if (removeLegacyKnownHostsFile(cfg.ssh.keyDirPath, cfg.project)) {
+        console.log(`Removed stale known_hosts for "${cfg.project}"`);
+      }
       console.log(`SSH alias "${alias}" written to ${sshConfigPath()} (connect: ssh ${alias})`);
     } catch (err) {
       console.warn(`Warning: could not update SSH config: ${err.message}`);

package/src/commands/list.js

@@ -0,0 +1,252 @@
+import {
+  addHostEntry,
+  ephemeralKnownHostsFile,
+  listHostEntries,
+  sshConfigPath,
+} from "../utils/ssh-config.js";
+import { exec } from "../utils/exec.js";
+import { kubectlExec } from "../utils/system-config.js";
+
+/**
+ * Ordering for the `list` table: by host, then port, then alias.
+ * IPv4 hosts compare octet-by-octet so 10.0.0.7 sorts before 10.0.0.19;
+ * anything else falls back to a string comparison. Missing values sort last.
+ */
+function compareIpv4(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 4; i++) {
+    if (pa[i] !== pb[i]) return pa[i] - pb[i];
+  }
+  return 0;
+}
+
+const IPV4 = /^\d{1,3}(\.\d{1,3}){3}$/;
+
+function compareHost(a, b) {
+  if (a === undefined && b === undefined) return 0;
+  if (a === undefined) return 1;
+  if (b === undefined) return -1;
+  if (IPV4.test(a) && IPV4.test(b)) {
+    const diff = compareIpv4(a, b);
+    if (diff !== 0) return diff;
+  } else {
+    const diff = a.localeCompare(b);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+function comparePort(a, b) {
+  if (a === undefined && b === undefined) return 0;
+  if (a === undefined) return 1;
+  if (b === undefined) return -1;
+  const na = Number(a);
+  const nb = Number(b);
+  if (Number.isInteger(na) && Number.isInteger(nb) && na !== nb) return na - nb;
+  if (a !== b) return String(a).localeCompare(String(b));
+  return 0;
+}
+
+function compareByHostPort(a, b) {
+  return compareHost(a.hostName, b.hostName) || comparePort(a.port, b.port) || a.alias.localeCompare(b.alias);
+}
+
+/**
+ * List the SSH connections the CLI manages (the `coding-<project>` aliases
+ * `deploy`/`create` write to ~/.ssh/config), ordered by host then port.
+ * Read-only: never touches the cluster, the config.yaml layers, or the SSH
+ * config file itself.
+ */
+export function listSsh({ file } = {}) {
+  const sshConfig = file ?? sshConfigPath();
+  const entries = listHostEntries(sshConfig).sort(compareByHostPort);
+  if (entries.length === 0) {
+    console.log(`No coding-container SSH connections found in ${sshConfig}.`);
+    console.log("Deploy a project to register one: coding-container create");
+    return;
+  }
+  const rows = entries.map((e) => ({
+    alias: e.alias,
+    host: e.hostName ?? "-",
+    port: e.port ?? "-",
+    user: e.user ?? "-",
+    identityFile: e.identityFile ?? "-",
+  }));
+  const widths = {
+    alias: Math.max("ALIAS".length, ...rows.map((r) => r.alias.length)),
+    host: Math.max("HOST".length, ...rows.map((r) => r.host.length)),
+    port: Math.max("PORT".length, ...rows.map((r) => r.port.length)),
+    user: Math.max("USER".length, ...rows.map((r) => r.user.length)),
+  };
+  const pad = (s, w) => s.padEnd(w, " ");
+  console.log(
+    `${pad("ALIAS", widths.alias)}  ${pad("HOST", widths.host)}  ${pad("PORT", widths.port)}  ${pad("USER", widths.user)}  IDENTITYFILE`
+  );
+  for (const r of rows) {
+    console.log(
+      `${pad(r.alias, widths.alias)}  ${pad(r.host, widths.host)}  ${pad(r.port, widths.port)}  ${pad(r.user, widths.user)}  ${r.identityFile}`
+    );
+  }
+  console.log(`\n${entries.length} connection(s) from ${sshConfig} (connect: ssh <alias>)`);
+}
+
+/**
+ * Pick the IP of a healthy cluster node. A NodePort service is reachable
+ * through *any* node, so when the cluster grows (or a node is replaced and
+ * its IP changes) the stored HostName just needs to point at a node that is
+ * currently Ready — it does not need to be the node the pod runs on.
+ */
+function getReadyNodeIp() {
+  const { cmd, args, opts } = kubectlExec();
+  let out;
+  try {
+    out = exec(cmd, [...args, "get", "nodes", "-o", "json"], opts);
+  } catch (err) {
+    throw new Error(`cannot list cluster nodes:\n${err.message}`);
+  }
+  let nodes;
+  try {
+    nodes = JSON.parse(out);
+  } catch (err) {
+    throw new Error(`cannot parse 'kubectl get nodes' output: ${err.message}`);
+  }
+  const items = nodes.items ?? [];
+  const addressOf = (node) => {
+    const addrs = node.status?.addresses ?? [];
+    return (
+      addrs.find((a) => a.type === "InternalIP")?.address ??
+      addrs.find((a) => a.type === "ExternalIP")?.address
+    );
+  };
+  const ready = items.filter((n) =>
+    (n.status?.conditions ?? []).some((c) => c.type === "Ready" && c.status === "True")
+  );
+  // No Ready conditions at all (e.g. a stubbed/apiserver-less response):
+  // fall back to any node that has an address.
+  const candidates = ready.length ? ready : items;
+  for (const node of candidates) {
+    const ip = addressOf(node);
+    if (ip) return ip;
+  }
+  throw new Error("no cluster node with an InternalIP/ExternalIP address found");
+}
+
+/**
+ * All services in the cluster, indexed by service name. An alias
+ * `coding-<project>` maps to the service `<project>` (in whatever namespace
+ * the project was deployed to), so the index is searched across namespaces.
+ */
+function indexServicesByName() {
+  const { cmd, args, opts } = kubectlExec();
+  let out;
+  try {
+    out = exec(cmd, [...args, "get", "svc", "-A", "-o", "json"], opts);
+  } catch (err) {
+    throw new Error(`cannot list cluster services:\n${err.message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(out);
+  } catch (err) {
+    throw new Error(`cannot parse 'kubectl get svc' output: ${err.message}`);
+  }
+  const byName = new Map();
+  for (const svc of parsed.items ?? []) {
+    const name = svc.metadata?.name;
+    if (!name) continue;
+    const sshPort = (svc.spec?.ports ?? []).find((p) => p.name === "ssh");
+    const record = {
+      namespace: svc.metadata?.namespace ?? "",
+      nodePort: sshPort?.nodePort,
+    };
+    if (!byName.has(name)) byName.set(name, []);
+    byName.get(name).push(record);
+  }
+  return byName;
+}
+
+/**
+ * Re-point every managed SSH alias at a currently-Ready node and resync its
+ * Port from the live Service's ssh nodePort.
+ *
+ * Why this exists: `deploy` captures one node's IP at deploy time. On a
+ * single-node cluster that never changes, but once the cluster grows (or a
+ * node is replaced) the stored IP can go stale — the pod moving nodes is
+ * harmless by itself (NodePort is reachable via any node), a dead/stale node
+ * IP is what breaks `ssh coding-<project>` and VS Code Remote-SSH. Refresh
+ *ing the aliases fixes that without redeploying.
+ *
+ * Stale entries (no matching service — e.g. after `delete` on another
+ * machine) and ambiguous ones (same service name in several namespaces) are
+ * left untouched with a warning. Nothing outside the managed block is modified.
+ */
+export function listUpdateSsh({ file, dryRun = false } = {}) {
+  const sshConfig = file ?? sshConfigPath();
+  const entries = listHostEntries(sshConfig);
+  if (entries.length === 0) {
+    console.log(`No coding-container SSH connections found in ${sshConfig}.`);
+    console.log("Deploy a project to register one: coding-container create");
+    return;
+  }
+  const nodeIp = getReadyNodeIp();
+  const services = indexServicesByName();
+  let updated = 0;
+  let current = 0;
+  for (const entry of entries) {
+    const project = entry.alias.replace(/^coding-/, "");
+    const matches = services.get(project) ?? [];
+    if (matches.length === 0) {
+      console.warn(
+        `warning: no service "${project}" found in any namespace — leaving "${entry.alias}" untouched (stale entry? run 'coding-container delete' to remove it)`
+      );
+      continue;
+    }
+    if (matches.length > 1) {
+      const where = matches.map((m) => `"${m.namespace}"`).join(", ");
+      console.warn(
+        `warning: service "${project}" exists in several namespaces (${where}) — leaving "${entry.alias}" untouched (edit ~/.ssh/config manually)`
+      );
+      continue;
+    }
+    const [{ namespace, nodePort }] = matches;
+    const wantPort = nodePort !== undefined && nodePort !== null ? String(nodePort) : entry.port;
+    if (!entry.identityFile) {
+      console.warn(`warning: "${entry.alias}" has no IdentityFile — leaving it untouched`);
+      continue;
+    }
+    if (entry.hostName === nodeIp && entry.port === wantPort) {
+      console.log(`"${entry.alias}": already current (${nodeIp}:${entry.port}, service "${project}" in "${namespace}")`);
+      current++;
+      continue;
+    }
+    const what =
+      entry.hostName !== nodeIp && entry.port !== wantPort
+        ? `host ${entry.hostName ?? "-"} -> ${nodeIp}, port ${entry.port ?? "-"} -> ${wantPort}`
+        : entry.hostName !== nodeIp
+          ? `host ${entry.hostName ?? "-"} -> ${nodeIp}`
+          : `port ${entry.port ?? "-"} -> ${wantPort}`;
+    if (dryRun) {
+      console.log(`"${entry.alias}": would update ${what} (service "${project}" in "${namespace}")`);
+      continue;
+    }
+    addHostEntry(
+      {
+        alias: entry.alias,
+        hostName: nodeIp,
+        port: wantPort,
+        user: entry.user ?? "root",
+        identityFile: entry.identityFile,
+        knownHostsFile: entry.knownHostsFile ?? ephemeralKnownHostsFile(),
+      },
+      sshConfig
+    );
+    console.log(`"${entry.alias}": updated ${what} (service "${project}" in "${namespace}")`);
+    updated++;
+  }
+  if (dryRun) {
+    console.log(`\nDry run: no changes written to ${sshConfig}.`);
+  } else {
+    console.log(`\n${updated} updated, ${current} already current (${entries.length} total) in ${sshConfig}.`);
+  }
+}

package/src/commands/setup.js

@@ -17,7 +17,7 @@ function yamlValue(v) {
   return JSON.stringify(v);
 }
 
-function renderTemplate(dir, values) {
+function renderTemplate(values) {
   return `# coding-container global configuration (created by 'coding-container setup')
 #
 # Shared by every project. Layering, lowest to highest priority:
@@ -26,7 +26,7 @@ function renderTemplate(dir, values) {
 # Relative paths in this file resolve against this file's directory.
 # The Dockerfile and the SSH key pair live next to this file:
 #   Dockerfile - the image build (copied here from the repo on first run)
-#   keys/      - the shared SSH key pair (per-project known_hosts alongside)
+#   keys/      - the shared SSH key pair (host keys are ephemeral, never stored)
 
 image:
   registry: ${yamlValue(values.registry)}
@@ -37,8 +37,10 @@ image:
   #   coding-container system get                 (show current/previous/maxEver)
   # Set tag in a project config to pin that project to one global version.
   # Single image build shared by all projects (Dockerfile copied next to this file).
-  dockerfile: ${path.join(dir, "Dockerfile")}
-  context: ${dir}
+  # Relative paths resolve against this file's directory, so this config
+  # survives renames/moves of the config folder.
+  dockerfile: Dockerfile
+  context: .
   buildArgs:
     BASE_IMAGE: ubuntu:26.04
     NODE_VERSION: "22"
@@ -175,7 +177,7 @@ export async function setup(opts = {}) {
     console.log(`kept:    ${cfgFile} (already exists, left untouched)`);
   } else {
     const values = await captureEnvironment(opts);
-    fs.writeFileSync(cfgFile, renderTemplate(dir, values));
+    fs.writeFileSync(cfgFile, renderTemplate(values));
     console.log(`created: ${cfgFile}`);
   }
 

package/src/commands/ssh.js

@@ -1,7 +1,7 @@
 import net from "node:net";
-import path from "node:path";
 import { exec, run, start } from "../utils/exec.js";
 import { ensureKeyPair } from "../utils/keys.js";
+import { ephemeralKnownHostsFile, removeLegacyKnownHostsFile } from "../utils/ssh-config.js";
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
@@ -34,9 +34,10 @@ async function waitForReady(child, ms = 15000) {
 }
 
 /**
- * Per-project known_hosts file so ephemeral pod host keys (regenerated on
- * every image build) never pollute the user's global known_hosts, and a
- * changed key never blocks the connection.
+ * Pod host keys are ephemeral (regenerated on every image build), so host
+ * keys are never persisted (UserKnownHostsFile -> OS null device). A stored
+ * key would go stale after a rebuild and VS Code Remote-SSH would refuse
+ * forwarding with "Port forwarding is disabled".
  */
 function sshCommonOptions(cfg, port, privateKey) {
   return [
@@ -47,7 +48,7 @@ function sshCommonOptions(cfg, port, privateKey) {
     "-o",
     "StrictHostKeyChecking=no",
     "-o",
-    `UserKnownHostsFile=${path.join(cfg.ssh.keyDirPath, `${cfg.project}-known_hosts`)}`,
+    `UserKnownHostsFile=${ephemeralKnownHostsFile()}`,
   ];
 }
 
@@ -63,6 +64,10 @@ async function sshDirect(cfg, privateKey) {
 
 export async function ssh(cfg, { direct = false } = {}) {
   const { private: privateKey } = ensureKeyPair(cfg.ssh.keyDirPath, cfg.ssh.keyName);
+  // One-time cleanup of the pre-null-device file so a stale key left over
+  // from before the switch can't break VS Code / Zed aliases still
+  // pointing at it until the next deploy rewrites them.
+  removeLegacyKnownHostsFile(cfg.ssh.keyDirPath, cfg.project);
 
   if (direct) {
     await sshDirect(cfg, privateKey);

package/src/commands/validate.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { imageRef } from "../config.js";
-import { fullManifest, secretEnvEntries } from "../utils/manifest.js";
+import { fullManifest, secretEnvEntries, webPorts } from "../utils/manifest.js";
 import { readPublicKey } from "../utils/keys.js";
 import { getSystemConfig, SYSTEM_CM_NAME } from "../utils/system-config.js";
 
@@ -77,8 +77,10 @@ export function validate(cfg, { manifest = false } = {}) {
   if (sidecars.length) {
     console.log(`  sidecars:  ${sidecars.map((s) => s.name).join(", ")}`);
   }
-  for (const p of cfg.web?.ports || []) {
-    console.log(`  web:       container port ${p.port} -> http://${p.host}/`);
+  for (const p of webPorts(cfg)) {
+    for (const host of p.hosts) {
+      console.log(`  web:       container port ${p.port} -> http://${host}/`);
+    }
   }
   for (const v of cfg.nfs.volumes || []) {
     console.log(`  volume:    ${v.subPath} -> ${v.mountPath}${v.readOnly ? " (read-only)" : ""}`);

package/src/config.js

@@ -101,19 +101,20 @@ export const DEFAULTS = {
   },
   web: {
     // Container ports to expose to the browser (dev servers, etc.). Each
-    // entry becomes a Traefik Ingress rule: its host routes to that container
-    // port on the project's service. DNS resolution of the hosts is up to you.
+    // entry becomes one Traefik Ingress rule per host: 'host' and/or 'hosts'
+    // (each a single host or a list) route to that container port on the
+    // project's service. DNS resolution of the hosts is up to you.
     // An optional 'nodePort' (30000-32767, unique across ssh, web.ports, and
     // sidecars) additionally exposes the port on every cluster node, for
     // clients that can't use the Ingress hosts.
     //   web:
     //     ports:
-    //       - { port: 3000, host: my-web.example.com, nodePort: 30080 }
+    //       - { port: 3000, hosts: [my-web.example.com, www.example.com], nodePort: 30080 }
     //       - { port: 8080, host: my-api.example.com, name: api }
     ports: [],
   },
   ingress: {
-    // Ingress class that routes the web.ports rules (k3s ships Traefik).
+    // Ingress class that routes the web.ports rules (Traefik, bundled with many Kubernetes distributions).
     className: "traefik",
   },
   container: {
@@ -222,7 +223,7 @@ export function loadConfig(configPath, overrides = {}) {
   }
 
   // Default key location: keys/ inside the global config dir (shared key
-  // pair for all projects; per-project known_hosts files live alongside).
+  // pair for all projects; host keys are ephemeral and never stored).
   if (!cfg.ssh.keyDirPath) cfg.ssh.keyDirPath = path.join(gDir, "keys");
   // `${VAR}` expansion (local shell -> config) is scoped to env-ish fields
   // only, so hosts/paths/ports can never surprise-expand. Missing variables
@@ -249,9 +250,11 @@ function validate(cfg) {
   if (!cfg.image.name) {
     throw new Error("config: image.name is required");
   }
-  if (!fs.existsSync(cfg.image.dockerfilePath)) {
-    throw new Error(`config: dockerfile not found: ${cfg.image.dockerfilePath}`);
-  }
+  // NOTE: the Dockerfile is intentionally NOT checked here. Only the build
+  // path (buildImage, used by `build`, custom-mode `create` and
+  // `system create`) needs it; `deploy`/`validate`/`ssh`/etc. in global mode
+  // run fine without one, so requiring it here would break deploys over a
+  // stale or missing Dockerfile.
   if (!cfg.nfs.server) {
     throw new Error(
       "config: nfs.server is not set. Run 'coding-container setup' " +
@@ -506,7 +509,7 @@ function validate(cfg) {
   }
   if (cfg.web?.ports !== undefined) {
     if (!Array.isArray(cfg.web.ports)) {
-      throw new Error("config: web.ports must be a list of {port, host} entries");
+      throw new Error("config: web.ports must be a list of {port, host|hosts} entries");
     }
     const seenPorts = new Set();
     const seenHosts = new Set();
@@ -514,25 +517,38 @@ function validate(cfg) {
       const port = entry && entry.port;
       if (!entry || typeof entry !== "object" || !Number.isInteger(port) || port < 1 || port > 65535) {
         throw new Error(
-          `config: web.ports entry must be an object with a 'port' (1-65535) and a 'host': ${JSON.stringify(entry)}`
+          `config: web.ports entry must be an object with a 'port' (1-65535) and a 'host' or 'hosts': ${JSON.stringify(entry)}`
         );
       }
       if (seenPorts.has(port)) {
         throw new Error(`config: web.ports lists port ${port} more than once`);
       }
       seenPorts.add(port);
-      if (
-        typeof entry.host !== "string" ||
-        !/^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$/.test(entry.host)
-      ) {
+      const hosts = [];
+      for (const value of [entry.host, entry.hosts]) {
+        if (value === undefined) continue;
+        if (Array.isArray(value)) hosts.push(...value);
+        else hosts.push(value);
+      }
+      if (hosts.length === 0) {
         throw new Error(
-          `config: web.ports entry for port ${port} has an invalid host (lowercase a-z/0-9/-/.): ${JSON.stringify(entry.host)}`
+          `config: web.ports entry for port ${port} needs a 'host' or a non-empty 'hosts' list`
         );
       }
-      if (seenHosts.has(entry.host)) {
-        throw new Error(`config: web.ports entries share the host "${entry.host}"`);
+      for (const host of hosts) {
+        if (
+          typeof host !== "string" ||
+          !/^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$/.test(host)
+        ) {
+          throw new Error(
+            `config: web.ports entry for port ${port} has an invalid host (lowercase a-z/0-9/-/.): ${JSON.stringify(host)}`
+          );
+        }
+        if (seenHosts.has(host)) {
+          throw new Error(`config: web.ports entries share the host "${host}"`);
+        }
+        seenHosts.add(host);
       }
-      seenHosts.add(entry.host);
       if (
         entry.name !== undefined &&
         (!/^[a-z]([-a-z0-9]*[a-z0-9])?$/.test(entry.name) || entry.name.length > 15)

package/src/index.js

@@ -10,6 +10,7 @@ import { push } from "./commands/push.js";
 import { deploy } from "./commands/deploy.js";
 import { create } from "./commands/create.js";
 import { ssh } from "./commands/ssh.js";
+import { listSsh, listUpdateSsh } from "./commands/list.js";
 import { gc } from "./commands/gc.js";
 import { deleteProject } from "./commands/delete.js";
 import { validate } from "./commands/validate.js";
@@ -32,7 +33,7 @@ const { version } = require("../package.json");
 
 program
   .name("coding-container")
-  .description("Build, publish and deploy SSH-accessible coding containers on k3s")
+  .description("Build, publish and deploy SSH-accessible coding containers on Kubernetes")
   .version(version)
   // Positional options: flags before the subcommand are global, flags after
   // belong to the subcommand. Required so `system create --tag vX.Y.Z` is
@@ -118,7 +119,7 @@ program
 
 program
   .command("deploy")
-  .description("deploy the image to the k3s cluster")
+  .description("deploy the image to the Kubernetes cluster")
   .option("--no-wait", "do not wait for the rollout to finish")
   .action(async (opts) => {
     const cfg = cfgFrom();
@@ -134,6 +135,23 @@ program
     await ssh(cfg, { direct: opts.direct });
   });
 
+const list = program
+  .command("list")
+  .description("list the SSH connections registered by coding-container (aliases in ~/.ssh/config)")
+  .action(() => {
+    listSsh();
+  });
+
+list
+  .command("update")
+  .description(
+    "refresh the SSH aliases from the live cluster (Ready node IP + service nodePorts; fixes stale entries after nodes change)"
+  )
+  .option("--dry-run", "show what would change without writing anything")
+  .action(async (opts) => {
+    await listUpdateSsh({ dryRun: opts.dryRun });
+  });
+
 program
   .command("delete")
   .alias("destroy")

package/src/utils/manifest.js

@@ -78,17 +78,27 @@ export function secretManifest(cfg, { redact = false } = {}) {
 }
 
 /**
- * Normalized web.ports entries: {name, port, host, nodePort?}. Names default
- * to web-<port>; nodePort (30000-32767) is an optional service-level knob
- * that also exposes the port on every cluster node.
+ * Normalized web.ports entries: {name, port, hosts, nodePort?}. 'hosts' is
+ * the entry's 'host' plus its 'hosts' value (each a single host or a list),
+ * deduplicated; the Ingress renders one rule per host. Names default to
+ * web-<port>; nodePort (30000-32767) is an optional service-level knob that
+ * also exposes the port on every cluster node.
  */
 export function webPorts(cfg) {
-  return (cfg.web?.ports || []).map((entry) => ({
-    name: entry.name || `web-${entry.port}`,
-    port: entry.port,
-    host: entry.host,
-    ...(entry.nodePort !== undefined ? { nodePort: entry.nodePort } : {}),
-  }));
+  return (cfg.web?.ports || []).map((entry) => {
+    const hosts = [];
+    for (const value of [entry.host, entry.hosts]) {
+      if (value === undefined) continue;
+      if (Array.isArray(value)) hosts.push(...value);
+      else hosts.push(value);
+    }
+    return {
+      name: entry.name || `web-${entry.port}`,
+      port: entry.port,
+      hosts: [...new Set(hosts)],
+      ...(entry.nodePort !== undefined ? { nodePort: entry.nodePort } : {}),
+    };
+  });
 }
 
 /**
@@ -273,9 +283,9 @@ export function serviceManifest(cfg) {
 }
 
 /**
- * Ingress with one rule per web port: the entry's host routes to that
- * container port on the project's service. Only rendered when web.ports is
- * non-empty.
+ * Ingress with one rule per web host: every host in a web port entry routes
+ * to that entry's container port on the project's service. Only rendered when
+ * web.ports is non-empty.
  */
 export function ingressManifest(cfg) {
   return {
@@ -288,18 +298,20 @@ export function ingressManifest(cfg) {
     },
     spec: {
       ingressClassName: cfg.ingress.className,
-      rules: webPorts(cfg).map((p) => ({
-        host: p.host,
-        http: {
-          paths: [
-            {
-              path: "/",
-              pathType: "Prefix",
-              backend: { service: { name: cfg.project, port: { number: p.port } } },
-            },
-          ],
-        },
-      })),
+      rules: webPorts(cfg).flatMap((p) =>
+        p.hosts.map((host) => ({
+          host,
+          http: {
+            paths: [
+              {
+                path: "/",
+                pathType: "Prefix",
+                backend: { service: { name: cfg.project, port: { number: p.port } } },
+              },
+            ],
+          },
+        }))
+      ),
     },
   };
 }

package/src/utils/project.js

@@ -95,11 +95,11 @@ project: ${project}
 k8s:
   nodePort: ${nodePort}
 
-# Expose container ports to the browser through Traefik (one Ingress host
-# per port). DNS for the hosts must resolve to your Traefik LoadBalancer.
+# Expose container ports to the browser through Traefik (one Ingress rule
+# per host). DNS for the hosts must resolve to your Traefik LoadBalancer.
 # web:
 #   ports:
-#     - { port: 3000, host: my-web.example.com }
+#     - { port: 3000, hosts: [my-web.example.com, www.example.com] }
 `
   );
   return { configPath, created: true, project, nodePort };

package/src/utils/ssh-config.js

@@ -18,6 +18,40 @@ export function sshAlias(project) {
   return `coding-${project}`;
 }
 
+/**
+ * Pod host keys are ephemeral (regenerated on every image build), so there
+ * is no point in persisting them. Pointing UserKnownHostsFile at the OS null
+ * device means a rebuilt image can never leave a stale key behind to break
+ * clients that need forwarding (VS Code Remote-SSH disables forwarding after
+ * a host-key change even with StrictHostKeyChecking=no).
+ */
+export function ephemeralKnownHostsFile() {
+  return process.platform === "win32" ? "NUL" : "/dev/null";
+}
+
+/**
+ * Pre-null-device location of a project's host keys. Kept only so commands
+ * can clean up the legacy file once.
+ */
+export function legacyKnownHostsFile(keyDirPath, project) {
+  return path.join(keyDirPath, `${project}-known_hosts`);
+}
+
+/**
+ * Delete the legacy per-project known_hosts file if it exists.
+ * Returns true when a file was removed.
+ */
+export function removeLegacyKnownHostsFile(keyDirPath, project) {
+  const file = legacyKnownHostsFile(keyDirPath, project);
+  try {
+    if (!fs.existsSync(file)) return false;
+    fs.rmSync(file, { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function readManaged(file) {
   if (!fs.existsSync(file)) return { before: "", entries: {}, after: "" };
   const lines = fs.readFileSync(file, "utf8").split(/\r?\n/);
@@ -81,3 +115,36 @@ export function removeHostEntry(alias, file = sshConfigPath()) {
   writeManaged(file, before, entries, after);
   return true;
 }
+
+/**
+ * Parse one managed Host block (array of raw lines, first is `Host <alias>`)
+ * into a structured entry. Unknown keys are ignored; missing keys stay undefined.
+ */
+function parseHostBlock(alias, lines) {
+  const entry = { alias };
+  for (const line of lines.slice(1)) {
+    const m = line.trim().match(/^(\S+)\s+(.*\S)\s*$/);
+    if (!m) continue;
+    const key = m[1].toLowerCase();
+    const value = m[2];
+    if (key === "hostname") entry.hostName = value;
+    else if (key === "port") entry.port = value;
+    else if (key === "user") entry.user = value;
+    else if (key === "identityfile") entry.identityFile = value;
+    else if (key === "userknownhostsfile") entry.knownHostsFile = value;
+    else if (key === "stricthostkeychecking") entry.strictHostKeyChecking = value;
+  }
+  return entry;
+}
+
+/**
+ * List the container host entries in the managed section, sorted by alias.
+ * Returns [] when the ssh config (or the managed block) is missing.
+ * Each entry is { alias, hostName?, port?, user?, identityFile?, ... }.
+ */
+export function listHostEntries(file = sshConfigPath()) {
+  const { entries } = readManaged(file);
+  return Object.entries(entries)
+    .map(([alias, lines]) => parseHostBlock(alias, lines))
+    .sort((a, b) => a.alias.localeCompare(b.alias));
+}