@esuyo/coding-container 1.0.4 → 1.0.6

package/README.md

@@ -1,21 +1,26 @@
-# Esuyo coding-container
+![coding-container — Standardized, isolated coding environments.](./docs/intro-image.jpg)
 
-Spin up a ready-to-code SSH container on your Kubernetes cluster in one command.
+# coding-container
 
-`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.
+> Ready-to-code containers on your Kubernetes cluster — per project, over SSH, with workspaces that survive restarts.
+
+`coding-container` gives every project its own consistent coding environment on Kubernetes. One deploy puts an SSH-accessible container per project at your fingertips: 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.
+
+Work your way: the terminal workflow, a browser admin UI (dashboard, project editor, terminal in the browser, job history), or the installable desktop app that wraps the same UI. All three share one project registry, so a project created in one place shows up in the others.
 
 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`)
-- Kubernetes-native: renders Deployment, Service, Ingress, ConfigMap, and Secret manifests and applies them with `kubectl`
+- One deploy for a ready-to-code container, SSH in, and tear down when done
+- Kubernetes-native: Deployment, Service, Ingress, ConfigMap, and Secret manifests applied with `kubectl`
 - Persistent per-project workspace on your NAS, so files survive restarts
-- Generates a dedicated SSH key; VS Code Remote-SSH ready
+- 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. Bring your own Dockerfile for any language or toolchain
+- Browser admin UI: dashboard with live workload status, project editor with validation, terminal in the browser, image publishing, and a job log for every operation
+- Desktop app (Windows / macOS / Linux): the same UI in an installable window with encrypted sign-in and automatic updates
+- Shared project registry, so the terminal, browser, and desktop views stay in sync
 
 ## Prerequisites
 
@@ -24,9 +29,12 @@ For private, internal Kubernetes clusters only. Do not expose to the public web.
 - `docker login` to your container registry
 - OpenSSH (`ssh`, `ssh-keygen`)
 - Your NAS reachable from the cluster nodes
+- For the browser UI / desktop app: a sign-in (email + password) configured in the checkout `.env` file
 
 ## Installation
 
+Terminal workflow:
+
 ```sh
 npm install -g @esuyo/coding-container
 coding-container --help
@@ -48,6 +56,18 @@ One-time setup (creates your global config and SSH key, never overwrites):
 coding-container setup
 ```
 
+Browser UI (from source):
+
+```sh
+npm --prefix web/client install   # first time only
+copy .env.example .env            # Windows (cp on macOS/Linux) — then set ADMIN_EMAIL + ADMIN_PASSWORD
+node web/dev.js                   # pages on :3400, API on the .env PORT
+```
+
+Production build: `npm --prefix web/client run build`, then `node web/server/server.js` serves the pages and the API on one port. See [Web GUI](./docs/gui.md).
+
+Desktop app: download an installer from the releases page, or build one from source (`npm --prefix web/client run build`, `npm --prefix electron install`, `npm --prefix electron run dist:win`). See [Desktop](./docs/desktop.md).
+
 ## Configuration
 
 Two small YAML files drive everything: a global config for your environment (`~/.config/coding-container/config.yaml`) and a per-project `config.yaml` for what differs per project.
@@ -58,17 +78,25 @@ k8s:
   nodePort: 30022
 ```
 
-See [Configuration](./docs/configuration.md) for layering, multiple projects, and NAS folders.
+Each checkout also carries its own identity in a `.env` file (copied from `.env.example`): separate config folders, connection-alias prefixes, and namespaces for isolated dev/prod instances, plus the browser UI sign-in and port.
+
+See [Configuration](./docs/configuration.md) for layering, multiple projects, the shared registry, and NAS folders.
 
 ## Quick Start
 
+Terminal workflow:
+
 ```sh
 coding-container create   # deploy this project
 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. Registered projects can be addressed from anywhere (`coding-container -p <name> deploy`).
+
+Browser UI: open the pages, sign in, and use the Dashboard for live status, Projects to add/edit/deploy (including a terminal per project), Images and System for the shared image, and Jobs for the log of every operation.
+
+Desktop app: sign in once on first launch — the dashboard opens automatically from then on, with the sign-in kept in the OS keychain.
 
 For everything else (web URLs, databases, image versions, all commands and flags), see [CLI reference](./docs/cli-reference.md) and the guides below.
 
@@ -77,6 +105,8 @@ For everything else (web URLs, databases, image versions, all commands and flags
 - **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).
+- **Can't sign in to the browser UI?** Set `ADMIN_EMAIL` + `ADMIN_PASSWORD` in `.env` and restart the server.
+- **Pages show "GUI not built"?** Run `npm --prefix web/client run build` first.
 
 ## License
 
@@ -84,19 +114,20 @@ 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
-- [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
-
----
+- [Web GUI](./docs/gui.md) — Pages, jobs, and server settings
+- [Desktop app](./docs/desktop.md) — Installable Electron shell
+- [Build & Deployment](./docs/build-and-deployment.md) — npm releases, GUI bundle, installers
+- [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

@@ -8,6 +8,9 @@ project: my-project
 
 k8s:
   nodePort: 30022
+  # Pin the pod to one named cluster node (kubectl get nodes). Empty/unset ->
+  # the scheduler picks a node.
+  # nodeName: worker-02
 
 # 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esuyo/coding-container",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "CLI to build, publish and deploy SSH-accessible coding containers on k3s",
   "type": "module",
   "bin": {
@@ -9,8 +9,14 @@
   "main": "src/index.js",
   "scripts": {
     "start": "node src/index.js",
-    "dev": "node src/index.js",
-    "test": "node --test"
+    "dev": "node web/dev.js",
+    "dev:kill": "node web/kill-dev.js",
+    "dev:cli": "node src/index.js",
+    "dev:server": "node web/server/server.js",
+    "dev:client": "npm --prefix web/client run dev",
+    "build:gui": "npm --prefix web/client run build",
+    "start:gui": "node web/server/server.js",
+    "test": "node --test test/*.test.* web/server/*.test.mjs web/client/src/**/*.test.mjs"
   },
   "engines": {
     "node": ">=18"
@@ -34,6 +40,7 @@
   ],
   "dependencies": {
     "commander": "^12.1.0",
-    "js-yaml": "^4.1.0"
+    "js-yaml": "^4.1.0",
+    "ssh2": "^1.17.0"
   }
 }

package/src/commands/deploy.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { exec, run, runWithInput } from "../utils/exec.js";
+import { resolveSshNodeIp } from "../utils/node-ip.js";
 import { ensureKeyPair, readPublicKey } from "../utils/keys.js";
 import { ensurePullSecret } from "../utils/registry.js";
 import { fullManifest, webPorts, sidecarNodePorts as sidecarNodePortsList } from "../utils/manifest.js";
@@ -79,16 +80,12 @@ export async function deploy(cfg, { wait = true } = {}) {
   }
   console.log(`Deployed ${cfg.project} in ${cfg.k8s.namespace}`);
 
-  // Node IP for the NodePort hints below and the SSH alias.
+  // Node IP for the NodePort hints below and the SSH alias: the node the
+  // pod actually runs on (when Ready), else the first Ready node. A NotReady
+  // node never serves NodePorts, so items[0] is not a valid default.
   let nodeIp;
   try {
-    nodeIp = exec(kubectl, [
-      ...kargs,
-      "get",
-      "nodes",
-      "-o",
-      "jsonpath={.items[0].status.addresses[?(@.type==\"InternalIP\")].address}",
-    ], kopts);
+    nodeIp = resolveSshNodeIp(cfg);
   } catch {
     /* handled below */
   }

package/src/commands/list.js

@@ -3,6 +3,7 @@ import {
   ephemeralKnownHostsFile,
   listHostEntries,
   sshConfigPath,
+  sshProjectFromAlias,
 } from "../utils/ssh-config.js";
 import { exec } from "../utils/exec.js";
 import { kubectlExec } from "../utils/system-config.js";
@@ -194,7 +195,11 @@ export function listUpdateSsh({ file, dryRun = false } = {}) {
   let updated = 0;
   let current = 0;
   for (const entry of entries) {
-    const project = entry.alias.replace(/^coding-/, "");
+    const project = sshProjectFromAlias(entry.alias);
+    if (project === null) {
+      console.log(`"${entry.alias}": belongs to another copy (different SSH prefix) — leaving it untouched`);
+      continue;
+    }
     const matches = services.get(project) ?? [];
     if (matches.length === 0) {
       console.warn(

package/src/commands/projects.js

@@ -0,0 +1,81 @@
+import fs from "node:fs";
+import {
+  computeProjectSlugs,
+  defaultProjectsFile,
+  readProjects,
+} from "../utils/projects.js";
+
+/**
+ * `projects list`: tabular view of the shared registry
+ * (<globalConfigDir()>/projects.json unless PROJECTS_FILE overrides it).
+ * Every value in SLUG/NAME/ID can be passed to `-p, --project` to run any
+ * config-dependent command against that project, e.g.
+ * `coding-container --project esuyo-mapping deploy`.
+ */
+export function listProjects({ projectsFile, json = false } = {}) {
+  const file = projectsFile ?? defaultProjectsFile();
+  const projects = readProjects(file);
+  const entries = computeProjectSlugs(projects);
+
+  if (json) {
+    console.log(
+      JSON.stringify(
+        entries.map(({ project, slug }) => {
+          const configPath = String(project?.configPath ?? "");
+          let exists = false;
+          try {
+            exists = configPath ? fs.existsSync(configPath) : false;
+          } catch {
+            exists = false;
+          }
+          return {
+            slug,
+            name: project?.name ?? "",
+            id: project?.id ?? "",
+            configPath,
+            exists,
+          };
+        }),
+        null,
+        2
+      )
+    );
+    return;
+  }
+
+  if (entries.length === 0) {
+    console.log(`No projects registered in ${file}.`);
+    return;
+  }
+
+  const rows = entries.map(({ project, slug }) => {
+    const configPath = String(project?.configPath ?? "-");
+    let display = configPath;
+    try {
+      if (configPath !== "-" && !fs.existsSync(configPath)) display = `${configPath} (missing)`;
+    } catch {
+      /* keep raw path */
+    }
+    return {
+      slug,
+      name: String(project?.name ?? "-"),
+      id: String(project?.id ?? "-"),
+      config: display,
+    };
+  });
+  const widths = {
+    slug: Math.max("SLUG".length, ...rows.map((r) => r.slug.length)),
+    name: Math.max("NAME".length, ...rows.map((r) => r.name.length)),
+    id: Math.max("ID".length, ...rows.map((r) => r.id.length)),
+  };
+  const pad = (s, w) => s.padEnd(w, " ");
+  console.log(
+    `${pad("SLUG", widths.slug)}  ${pad("NAME", widths.name)}  ${pad("ID", widths.id)}  CONFIG`
+  );
+  for (const r of rows) {
+    console.log(`${pad(r.slug, widths.slug)}  ${pad(r.name, widths.name)}  ${pad(r.id, widths.id)}  ${r.config}`);
+  }
+  console.log(
+    `\n${entries.length} project(s) from ${file} (run: coding-container --project <slug|name|id> <command>)`
+  );
+}

package/src/commands/ssh.js

@@ -1,5 +1,6 @@
 import net from "node:net";
-import { exec, run, start } from "../utils/exec.js";
+import { run, start } from "../utils/exec.js";
+import { resolveSshNodeIp } from "../utils/node-ip.js";
 import { ensureKeyPair } from "../utils/keys.js";
 import { ephemeralKnownHostsFile, removeLegacyKnownHostsFile } from "../utils/ssh-config.js";
 
@@ -53,12 +54,13 @@ function sshCommonOptions(cfg, port, privateKey) {
 }
 
 async function sshDirect(cfg, privateKey) {
-  const nodeIp = exec("kubectl", [
-    "get",
-    "nodes",
-    "-o",
-    "jsonpath={.items[0].status.addresses[?(@.type==\"InternalIP\")].address}",
-  ]);
+  // Same resolution as deploy: the pod's own (Ready) node, else the first
+  // Ready node. Never items[0] blindly — a NotReady node drops NodePort
+  // traffic even though the Service looks fine.
+  const nodeIp = resolveSshNodeIp(cfg);
+  if (!nodeIp) {
+    throw new Error("could not resolve a Ready cluster node for --direct (is any node Ready?)");
+  }
   await run("ssh", [...sshCommonOptions(cfg, cfg.k8s.nodePort, privateKey), `${cfg.ssh.user}@${nodeIp}`]);
 }
 

package/src/commands/system.js

@@ -1,6 +1,6 @@
 import { exec } from "../utils/exec.js";
 import { listTags } from "../utils/registry-api.js";
-import { isSemver, compareSemver, semverSortAsc } from "../utils/semver.js";
+import { isSemver, compareSemver, semverSortAsc, bumpPatch } from "../utils/semver.js";
 import {
   getSystemConfig,
   patchSystemConfig,
@@ -126,9 +126,13 @@ export async function systemList(cfg) {
  */
 export async function systemCreate(cfg, { tag } = {}) {
   requireGlobalMode(cfg);
-  requireSemverTag(tag);
   const ns = cfg.k8s.namespace;
   const sys = getSystemConfig(ns);
+  if (!tag) {
+    tag = bumpPatch(sys.maxEver);
+    console.log(`No --tag given, auto-bumped to ${tag} (patch +1 over maxEver ${sys.maxEver})`);
+  }
+  requireSemverTag(tag);
   if (compareSemver(tag, sys.maxEver) <= 0) {
     throw new Error(
       `tag ${tag} is not greater than maxEver ${sys.maxEver} — global tags are immutable and ` +

package/src/commands/validate.js

@@ -68,7 +68,10 @@ export function validate(cfg, { manifest = false } = {}) {
         : `${cfg.image.registry}/${cfg.image.name}:<no tag — run 'coding-container system init' or set image.tag>`
     }`
   );
-  console.log(`  cluster:   namespace ${cfg.k8s.namespace}, ${cfg.k8s.serviceType} port ${cfg.k8s.nodePort}`);
+  console.log(
+    `  cluster:   namespace ${cfg.k8s.namespace}, ${cfg.k8s.serviceType} port ${cfg.k8s.nodePort}` +
+      (cfg.k8s.nodeName ? `, node ${cfg.k8s.nodeName}` : "")
+  );
   const secretKeys = secretEnvEntries(cfg).map(([name]) => name);
   if (secretKeys.length) {
     console.log(`  secrets:   ${secretKeys.join(", ")} (via Secret ${cfg.project}-env, values never shown)`);

package/src/config.js

@@ -4,12 +4,16 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import yaml from "js-yaml";
 import { expandEnvMap } from "./utils/envsubst.js";
+import { configDirLeaf, defaultNamespace } from "./utils/instance.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 export const PROJECT_ROOT = path.resolve(__dirname, "..");
 
 /**
- * Global config directory: $XDG_CONFIG_HOME/coding-container or ~/.config/coding-container.
+ * Global config directory: $XDG_CONFIG_HOME/<leaf> or ~/.config/<leaf>.
+ * Leaf defaults to "coding-container" (CODING_CONFIG_LEAF in
+ * PROJECT_FOLDER/.env or the environment overrides it), so repeated
+ * checkouts (dev vs prod) get separate config.yaml/Dockerfile/keys folders.
  * Holds the shared settings (config.yaml) and, by default, the SSH key
  * material (keys/).
  */
@@ -17,7 +21,7 @@ export function globalConfigDir() {
   const base = process.env.XDG_CONFIG_HOME
     ? path.resolve(process.env.XDG_CONFIG_HOME)
     : path.join(os.homedir(), ".config");
-  return path.join(base, "coding-container");
+  return path.join(base, configDirLeaf());
 }
 
 export function globalConfigPath() {
@@ -50,6 +54,12 @@ export const DEFAULTS = {
     replicas: 1,
     serviceType: "NodePort",
     nodePort: 30022,
+    // Exact cluster node the pod is pinned to (k8s podSpec.nodeName).
+    // Unset (empty) -> the scheduler picks a node. Set it to force placement,
+    // e.g. a node with the NAS mount or a GPU:
+    //   k8s:
+    //     nodeName: worker-02
+    nodeName: "",
     imagePullSecret: "",
     resources: {
       requests: { cpu: "100m", memory: "128Mi" },
@@ -184,7 +194,7 @@ export function resolveDefaultConfigPath(explicit) {
  *   1. hardcoded DEFAULTS
   *   2. global config  (~/.config/coding-container/config.yaml, if present)
  *   3. local project config (configPath)
- *   4. CLI overrides (e.g. -p/--project, --tag)
+  *   4. CLI overrides (e.g. --project-name, --tag)
  *
  * The cluster is a layer too, but it is read by the deploy/system commands,
  * not here: in global mode the image tag floats on the coding-system
@@ -196,18 +206,26 @@ export function resolveDefaultConfigPath(explicit) {
  *
  * @param {string} configPath path to the local project yaml file
  * @param {object} overrides flat-ish overrides applied on top (e.g. from CLI flags)
+ * @param {object} opts optional knobs; `opts.globalConfigPath` swaps which
+ *   file backs the global layer (used to validate an unsaved global draft
+ *   without touching the real file on disk).
  */
-export function loadConfig(configPath, overrides = {}) {
+export function loadConfig(configPath, overrides = {}, opts = {}) {
   const resolved = path.resolve(configPath);
   if (!fs.existsSync(resolved)) {
     throw new Error(`Config file not found: ${resolved}`);
   }
   const localDir = path.dirname(resolved);
-  const gDir = globalConfigDir();
+  const gPath = opts.globalConfigPath ? path.resolve(opts.globalConfigPath) : globalConfigPath();
+  const gDir = path.dirname(gPath);
 
-  let cfg = withPaths(DEFAULTS, localDir);
-  if (fs.existsSync(globalConfigPath())) {
-    cfg = deepMerge(cfg, withPaths(readYaml(globalConfigPath()), gDir));
+  // Instance default namespace (CODING_NAMESPACE): base layer only, so the
+  // global/project configs still override it per project.
+  const baseDefaults = structuredClone(DEFAULTS);
+  baseDefaults.k8s.namespace = defaultNamespace();
+  let cfg = withPaths(baseDefaults, localDir);
+  if (fs.existsSync(gPath)) {
+    cfg = deepMerge(cfg, withPaths(readYaml(gPath), gDir));
   }
   const local = readYaml(resolved);
   cfg = deepMerge(cfg, withPaths(local, localDir));
@@ -369,6 +387,17 @@ function validate(cfg) {
   if (st !== "NodePort" && st !== "LoadBalancer") {
     throw new Error("config: k8s.serviceType must be NodePort or LoadBalancer");
   }
+  if (cfg.k8s.nodeName !== undefined && cfg.k8s.nodeName !== "") {
+    if (
+      typeof cfg.k8s.nodeName !== "string" ||
+      cfg.k8s.nodeName.length > 253 ||
+      !/^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$/.test(cfg.k8s.nodeName)
+    ) {
+      throw new Error(
+        `config: k8s.nodeName must be a valid node name (lowercase a-z/0-9/-/. , max 253 chars): ${JSON.stringify(cfg.k8s.nodeName)}`
+      );
+    }
+  }
   for (const field of ["env", "secretEnv"]) {
     const map = cfg.k8s[field];
     if (map == null) continue;

package/src/index.js

@@ -25,6 +25,13 @@ import {
 import { ensureKeyPair } from "./utils/keys.js";
 import { ensureProjectConfig } from "./utils/project.js";
 import { resolveDeployTag } from "./utils/system-config.js";
+import {
+  defaultProjectsFile,
+  readProjects,
+  resolveProjectRefOrThrow,
+  resolveStoredConfigPath,
+} from "./utils/projects.js";
+import { listProjects } from "./commands/projects.js";
 
 const program = new Command();
 
@@ -40,15 +47,43 @@ program
   // not swallowed by the global --tag.
   .enablePositionalOptions()
   .option("-c, --config <file>", "path to config yaml (default: ./config.yaml if present, else the repo's)")
-  .option("-p, --project <name>", "override the project name")
+  .option("-p, --project <slug|name|id>", "select a project from the shared registry (see 'projects list')")
+  .option("--project-name <name>", "override the project name")
   .option("--tag <tag>", "override the image tag");
 
+/**
+ * Which local config file to load: an explicit -c wins, else a -p/--project
+ * registry entry (same store the GUI uses), else ./config.yaml or the repo's.
+ * -c and -p together are an error, never a guess.
+ */
+function resolveSelectedConfigPath(globalOpts) {
+  if (globalOpts.config && globalOpts.project) {
+    throw new Error("Use either -c/--config or -p/--project, not both.");
+  }
+  if (globalOpts.project) {
+    const projectsFile = defaultProjectsFile();
+    const projects = readProjects(projectsFile);
+    const { project } = resolveProjectRefOrThrow(projects, globalOpts.project, projectsFile);
+    const configPath = resolveStoredConfigPath(project.configPath);
+    if (!configPath) {
+      throw new Error(`Project "${globalOpts.project}" has no configPath in ${projectsFile}.`);
+    }
+    if (!fs.existsSync(configPath)) {
+      throw new Error(
+        `Project "${globalOpts.project}" config not found: ${configPath}\nRun "coding-container projects list" to see all projects.`
+      );
+    }
+    return configPath;
+  }
+  return resolveDefaultConfigPath(globalOpts.config);
+}
+
 function cfgFrom(ctx) {
   const globalOpts = program.opts();
   const overrides = {};
-  if (globalOpts.project) overrides.project = globalOpts.project;
+  if (globalOpts.projectName) overrides.project = globalOpts.projectName;
   if (globalOpts.tag) overrides.image = { tag: globalOpts.tag };
-  const cfg = loadConfig(resolveDefaultConfigPath(globalOpts.config), overrides);
+  const cfg = loadConfig(resolveSelectedConfigPath(globalOpts), overrides);
   // First-run nudge: shown once, on stderr, until the global config exists.
   if (process.argv[2] !== "setup" && !fs.existsSync(globalConfigPath())) {
     console.error(
@@ -78,14 +113,14 @@ program
   .option("--skip-push", "skip the docker push step")
   .action(async (opts) => {
     const globalOpts = program.opts();
-    // No explicit -c and no ./config.yaml: scaffold one (project name from
-    // the folder, first free NodePort) and proceed with it.
-    if (!globalOpts.config) {
+    // No explicit -c/-p and no ./config.yaml: scaffold one (project name from
+    // the folder or --project-name, first free NodePort) and proceed with it.
+    if (!globalOpts.config && !globalOpts.project) {
       const cwdConfig = path.resolve(process.cwd(), "config.yaml");
       if (!fs.existsSync(cwdConfig)) {
         const { created, project, nodePort } = ensureProjectConfig(
           process.cwd(),
-          globalOpts.project
+          globalOpts.projectName
         );
         if (created) {
           console.log(
@@ -152,6 +187,18 @@ list
     await listUpdateSsh({ dryRun: opts.dryRun });
   });
 
+const projects = program
+  .command("projects")
+  .description("work with the shared project registry (same store the GUI uses)");
+
+projects
+  .command("list")
+  .description("list registered projects (any SLUG, NAME or ID works with -p/--project)")
+  .option("--json", "print the registry as JSON (includes slugs and file-exists flags)")
+  .action((opts) => {
+    listProjects({ json: opts.json });
+  });
+
 program
   .command("delete")
   .alias("destroy")
@@ -264,10 +311,12 @@ system
   .description(
     "build + push a new global version and repoint current (the only writer of the global image)"
   )
-  .requiredOption("--tag <tag>", "new version (semver vX.Y.Z, must not exist and must be > maxEver)")
+  .option("--tag <tag>", "new version (semver vX.Y.Z, must not exist and must be > maxEver; default: maxEver patch +1)")
   .action(async (opts) => {
     const cfg = cfgFrom();
-    await systemCreate(cfg, { tag: opts.tag });
+    // Global --tag (before `system`) also works: `coding-container --tag vX.Y.Z system create`.
+    const tag = opts.tag ?? program.opts().tag;
+    await systemCreate(cfg, { tag });
   });
 
 system

package/src/utils/instance.js

@@ -0,0 +1,85 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// Checkout root (PROJECT_FOLDER): src/utils -> src -> root.
+export const INSTANCE_ROOT = path.resolve(__dirname, "..", "..");
+
+export const DEFAULT_CONFIG_LEAF = "coding-container";
+export const DEFAULT_SSH_PREFIX = "coding-";
+export const DEFAULT_NAMESPACE = "coding";
+
+let loaded = false;
+
+/**
+ * Minimal .env parser (no dependency): KEY=VALUE lines, optional `export`
+ * prefix, `#` comments, single/double-quoted values. Real environment wins:
+ * keys already in process.env are never overwritten. Loads once from
+ * PROJECT_FOLDER/.env (the checkout root), so each repeated folder carries
+ * its own dev/prod identity no matter where commands run from.
+ */
+export function loadInstanceEnv(root = INSTANCE_ROOT) {
+  if (loaded) return;
+  loaded = true;
+  let text;
+  try {
+    text = fs.readFileSync(path.join(root, ".env"), "utf8");
+  } catch {
+    return;
+  }
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const m = line.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
+    if (!m) continue;
+    const [, key, rest] = m;
+    if (key in process.env) continue;
+    process.env[key] = unquote(rest.trim());
+  }
+}
+
+// Test-only: allow re-loading after env swaps.
+export function resetInstanceEnvForTests() {
+  loaded = false;
+}
+
+function unquote(v) {
+  if (v.length >= 2 && ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'")))) {
+    const inner = v.slice(1, -1);
+    // Double-quoted: honor common escapes; single-quoted: literal.
+    return v.startsWith('"') ? inner.replace(/\\n/g, "\n").replace(/\\r/g, "\r").replace(/\\t/g, "\t").replace(/\\"/g, '"').replace(/\\\\/g, "\\") : inner;
+  }
+  const comment = v.search(/(^|\s)#/);
+  return (comment === -1 ? v : v.slice(0, comment).trim());
+}
+
+/** Global config dir leaf: CODING_CONFIG_LEAF, default "coding-container". */
+export function configDirLeaf() {
+  loadInstanceEnv();
+  const v = (process.env.CODING_CONFIG_LEAF ?? "").trim() || DEFAULT_CONFIG_LEAF;
+  if (!/^[A-Za-z0-9._-]+$/.test(v) || v === "." || v === "..") {
+    throw new Error(`config: CODING_CONFIG_LEAF must be a plain folder name (no slashes): ${JSON.stringify(v)}`);
+  }
+  return v;
+}
+
+/** SSH alias prefix: CODING_SSH_PREFIX, default "coding-". */
+export function sshPrefix() {
+  loadInstanceEnv();
+  const v = (process.env.CODING_SSH_PREFIX ?? "").trim() || DEFAULT_SSH_PREFIX;
+  if (!/^[a-z0-9-]+$/.test(v) || !v.endsWith("-") || v.length > 32) {
+    throw new Error(`config: CODING_SSH_PREFIX must be lowercase alnum/dashes ending in '-': ${JSON.stringify(v)}`);
+  }
+  return v;
+}
+
+/** Default k8s namespace: CODING_NAMESPACE, default "coding". Config files still override it. */
+export function defaultNamespace() {
+  loadInstanceEnv();
+  const v = (process.env.CODING_NAMESPACE ?? "").trim() || DEFAULT_NAMESPACE;
+  if (v.length > 63 || !/^[a-z0-9]([-a-z0-9]*[a-z0-9])?$/.test(v)) {
+    throw new Error(`config: CODING_NAMESPACE must be a valid k8s name (lowercase alphanum and '-'): ${v}`);
+  }
+  return v;
+}

package/src/utils/manifest.js

@@ -227,6 +227,9 @@ export function deploymentManifest(cfg, pullSecret = null) {
         },
         spec: {
           ...(pullSecret ? { imagePullSecrets: [{ name: pullSecret }] } : {}),
+          // Pin the pod to one named cluster node when k8s.nodeName is set.
+          // Empty/unset -> the scheduler picks a node as before.
+          ...(cfg.k8s?.nodeName ? { nodeName: cfg.k8s.nodeName } : {}),
           containers: [container, ...sidecarContainers(cfg)],
           volumes: [
             {

package/src/utils/node-ip.js

@@ -0,0 +1,74 @@
+import { exec } from "./exec.js";
+import { kubectlExec } from "./system-config.js";
+
+/**
+ * Parse `kubectl get nodes -o json` into [{ name, internalIP, ready }].
+ * Unknown/missing fields stay undefined/false (never throws on shape).
+ */
+export function parseNodesJson(jsonStr) {
+  const { items = [] } = JSON.parse(jsonStr);
+  return items.map((n) => {
+    const addresses = n.status?.addresses || [];
+    const internalIP = (addresses.find((a) => a.type === "InternalIP") || {}).address;
+    const readyCond = (n.status?.conditions || []).find((c) => c.type === "Ready");
+    return {
+      name: n.metadata?.name,
+      internalIP,
+      ready: readyCond?.status === "True",
+    };
+  });
+}
+
+/**
+ * Parse `kubectl get pods -o json` into [{ name, phase, hostIP, nodeName }].
+ */
+export function parsePodsJson(jsonStr) {
+  const { items = [] } = JSON.parse(jsonStr);
+  return items.map((p) => ({
+    name: p.metadata?.name,
+    phase: p.status?.phase,
+    hostIP: p.status?.hostIP,
+    nodeName: p.spec?.nodeName,
+  }));
+}
+
+/**
+ * Pick the SSH NodePort IP: the pod's own hostIP when that node is Ready,
+ * else the first Ready node with an InternalIP. Returns null when no Ready
+ * node exists (caller warns instead of writing a dead alias).
+ */
+export function pickNodeIp(nodes, podHostIP = null) {
+  const ready = nodes.filter((n) => n.ready && n.internalIP);
+  if (!ready.length) return null;
+  if (podHostIP && ready.some((n) => n.internalIP === podHostIP)) return podHostIP;
+  return ready[0].internalIP;
+}
+
+/**
+ * Resolve where the project actually runs: ask the cluster for this
+ * project's pods, then map the Running pod's hostIP onto the Ready nodes.
+ * Falls back to the first Ready node when the pod list is empty/pending;
+ * returns null when the cluster is unreachable or nothing is Ready (so
+ * deploy can warn and skip the SSH alias instead of writing a dead IP).
+ *
+ * Uses `-o json` (not jsonpath) so Windows script stubs don't hit shell
+ * quoting issues.
+ */
+export function resolveSshNodeIp(cfg) {
+  const { cmd, args, opts } = kubectlExec();
+  let podHostIP = null;
+  try {
+    const out = exec(cmd, [...args, "get", "pods", "-n", cfg.k8s.namespace, "-l", `app=${cfg.project}`, "-o", "json"], opts);
+    const pods = parsePodsJson(out);
+    const running = pods.find((p) => p.phase === "Running" && p.hostIP) || pods.find((p) => p.hostIP);
+    podHostIP = running?.hostIP ?? null;
+  } catch {
+    /* pods unreadable -> Ready-node fallback below */
+  }
+  try {
+    const out = exec(cmd, [...args, "get", "nodes", "-o", "json"], opts);
+    return pickNodeIp(parseNodesJson(out), podHostIP);
+  } catch {
+    return null;
+  }
+}

package/src/utils/projects.js

@@ -0,0 +1,218 @@
+import fs from "node:fs";
+import path from "node:path";
+import { PROJECT_ROOT, globalConfigDir } from "../config.js";
+
+/**
+ * Shared projects registry (the GUI datastore), reused by the CLI.
+ *
+ * Store shape: JSON array of { id, name, configPath } at
+ *   <globalConfigDir()>/projects.json
+ * unless PROJECTS_FILE overrides it (absolute, or relative to the repo root).
+ * Managed per-project configs live under <globalConfigDir()>/projects/<slug>/.
+ */
+
+/** Resolve an explicit PROJECTS_FILE value to an absolute path. */
+export function resolveProjectsFile(raw) {
+  const value = raw && String(raw).trim() ? String(raw).trim() : "";
+  if (!value) return path.join(globalConfigDir(), "projects.json");
+  return path.isAbsolute(value) ? value : path.join(PROJECT_ROOT, value);
+}
+
+/** Default registry path: PROJECTS_FILE env wins, else next to global config. */
+export function defaultProjectsFile() {
+  // Touch the global dir first so a PROJECTS_FILE set in the checkout's .env
+  // is loaded into process.env before reading it — matching the GUI server,
+  // which reads the same .env file directly.
+  globalConfigDir();
+  return resolveProjectsFile(process.env.PROJECTS_FILE ?? "");
+}
+
+export function readProjects(projectsFile) {
+  const file = projectsFile ?? defaultProjectsFile();
+  try {
+    if (!fs.existsSync(file)) return [];
+    const data = JSON.parse(fs.readFileSync(file, "utf8"));
+    return Array.isArray(data) ? data : [];
+  } catch {
+    return [];
+  }
+}
+
+export function writeProjects(projectsFile, projects) {
+  fs.mkdirSync(path.dirname(projectsFile), { recursive: true });
+  fs.writeFileSync(projectsFile, `${JSON.stringify(projects, null, 2)}\n`);
+}
+
+export function resolveStoredConfigPath(configPath) {
+  const raw = String(configPath ?? "").trim();
+  if (!raw) return null;
+  return path.isAbsolute(raw) ? raw : path.join(PROJECT_ROOT, raw);
+}
+
+/**
+ * Filesystem + k8s-safe slug from a display name (DNS-1123 label style).
+ * Mirrors deriveProjectName(): lowercase, non [a-z0-9-] -> "-", collapse,
+ * trim dashes, cap at 63 chars, fallback to "project".
+ */
+export function slugifyProjectName(name) {
+  let slug = String(name ?? "")
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  if (!slug) slug = "project";
+  if (slug.length > 63) slug = slug.slice(0, 63).replace(/-+$/g, "") || "project";
+  return slug;
+}
+
+/**
+ * Display slugs for every registry entry, in registry order. The slug tracks
+ * the current name; collisions get -2, -3, ... suffixes.
+ * Returns [{ project, slug }].
+ */
+export function computeProjectSlugs(projects) {
+  const used = new Set();
+  const out = [];
+  for (const project of projects ?? []) {
+    const base = slugifyProjectName(project?.name);
+    let slug = base;
+    let n = 1;
+    while (used.has(slug)) {
+      n += 1;
+      slug = `${base}-${n}`;
+    }
+    used.add(slug);
+    out.push({ project, slug });
+  }
+  return out;
+}
+
+/** Folder holding auto-managed per-project configs: <globalDir>/projects. */
+export function managedProjectsDir() {
+  return path.join(globalConfigDir(), "projects");
+}
+
+/** Default config file for an auto-managed project slug. */
+export function defaultProjectConfigPath(slug) {
+  return path.join(managedProjectsDir(), slug, "config.yaml");
+}
+
+/**
+ * True when configPath lives inside the managed projects dir (i.e. it was
+ * auto-assigned, not a user-supplied custom path). Such paths follow renames.
+ */
+export function isManagedConfigPath(configPath) {
+  const resolved = path.resolve(String(configPath ?? ""));
+  const base = path.resolve(managedProjectsDir());
+  const rel = path.relative(base, resolved);
+  return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+
+/**
+ * Unique managed config path for a base slug. Suffixes -2, -3, ... while the
+ * candidate is taken by another registry entry (excluding excludeId) or an
+ * existing file on disk (e.g. leftovers from a removed entry).
+ */
+export function uniqueManagedConfigPath(projects, baseSlug, excludeId = null) {
+  const takenPaths = new Set(
+    (projects ?? [])
+      .filter((p) => p.id !== excludeId)
+      .map((p) => path.resolve(String(p.configPath ?? "")))
+  );
+  let slug = baseSlug;
+  let n = 1;
+  while (true) {
+    const candidate = defaultProjectConfigPath(slug);
+    const resolved = path.resolve(candidate);
+    if (!takenPaths.has(resolved) && !fs.existsSync(candidate)) return { slug, configPath: candidate };
+    n += 1;
+    slug = `${baseSlug}-${n}`;
+  }
+}
+
+/**
+ * One-line summary used in "unknown project" errors.
+ * `entries` is the result of computeProjectSlugs().
+ */
+function availableProjectsHint(entries, projectsFile) {
+  if (!entries || entries.length === 0) {
+    return `No projects registered in ${projectsFile}.`;
+  }
+  const lines = entries.map(({ project, slug }) => `  ${slug} ("${project?.name ?? ""}")`);
+  return `Available projects (slug, name or id):\n${lines.join("\n")}`;
+}
+
+/**
+ * Match a user-supplied ref against the registry. Ref may be a display slug,
+ * a name, or an id (exact or unique prefix >= 4 chars).
+ * Returns { project, slug } or null when nothing matches.
+ * Throws on ambiguous names/prefixes.
+ */
+export function findProjectByRef(projects, ref) {
+  const needle = String(ref ?? "").trim();
+  if (!needle) return null;
+  const list = projects ?? [];
+  const entries = computeProjectSlugs(list);
+
+  const byId = list.find((p) => p?.id === needle);
+  if (byId) {
+    const slug = entries.find((e) => e.project === byId)?.slug ?? slugifyProjectName(byId.name);
+    return { project: byId, slug };
+  }
+
+  const lowered = needle.toLowerCase();
+  const slugHits = entries.filter((e) => e.slug.toLowerCase() === lowered);
+  if (slugHits.length === 1) return slugHits[0];
+  if (slugHits.length > 1) {
+    throw new Error(
+      `Ambiguous project "${needle}" matches several slugs: ${slugHits.map((e) => e.slug).join(", ")}`
+    );
+  }
+
+  const exactName = entries.filter((e) => String(e.project?.name ?? "") === needle);
+  if (exactName.length === 1) return exactName[0];
+  if (exactName.length > 1) {
+    throw new Error(
+      `Ambiguous project name "${needle}" matches ${exactName.length} projects; use the slug or id instead.`
+    );
+  }
+
+  const ciName = entries.filter(
+    (e) => String(e.project?.name ?? "").toLowerCase() === lowered
+  );
+  if (ciName.length === 1) return ciName[0];
+  if (ciName.length > 1) {
+    throw new Error(
+      `Ambiguous project name "${needle}" matches ${ciName.length} projects; use the slug or id instead.`
+    );
+  }
+
+  if (needle.length >= 4) {
+    const prefix = list.filter((p) => typeof p?.id === "string" && p.id.startsWith(needle));
+    if (prefix.length === 1) {
+      const project = prefix[0];
+      const slug = entries.find((e) => e.project === project)?.slug ?? slugifyProjectName(project.name);
+      return { project, slug };
+    }
+    if (prefix.length > 1) {
+      throw new Error(
+        `Ambiguous project id prefix "${needle}" matches ${prefix.length} projects; use the full id.`
+      );
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Like findProjectByRef, but throws a copy-paste friendly error naming the
+ * registry file and every available slug when nothing matches.
+ */
+export function resolveProjectRefOrThrow(projects, ref, projectsFile) {
+  const match = findProjectByRef(projects, ref);
+  if (match) return match;
+  const entries = computeProjectSlugs(projects ?? []);
+  throw new Error(
+    `Unknown project "${String(ref ?? "").trim()}".\n${availableProjectsHint(entries, projectsFile)}\nRun "coding-container projects list" to see all projects.`
+  );
+}

package/src/utils/registry-api.js

@@ -186,7 +186,7 @@ async function send(cfg, method, path, authHeader, extraHeaders = {}) {
  * Authorization header, and on 401 follow the WWW-Authenticate challenge
  * (Bearer token exchange or plain Basic) with the local docker credentials.
  */
-async function apiRequest(cfg, method, path, extraHeaders = {}) {
+async function apiRequest(cfg, method, path, extraHeaders = {}, scopeOverride = null) {
   let res = await send(cfg, method, path, state.authHeader, extraHeaders);
   if (res.status !== 401) return res;
 
@@ -214,7 +214,7 @@ async function apiRequest(cfg, method, path, extraHeaders = {}) {
     authHeader = basic;
   } else if (challenge.type === "bearer") {
     const repo = registryRepoName(cfg);
-    const scope = challenge.scope || `repository:${repo}:pull,push`;
+    const scope = scopeOverride || challenge.scope || `repository:${repo}:pull,push`;
     const key = `${challenge.realm}|${challenge.service || ""}|${scope}`;
     let token = state.tokens.get(key);
     if (!token) {
@@ -287,12 +287,67 @@ export async function listTags(cfg) {
 }
 
 /**
- * Delete one tag. Returns normally on success (2xx); throws otherwise.
+ * Delete one tag. Uses the standard Registry V2 / OCI flow:
+ *   GET /v2/<repo>/manifests/<tag> (with a manifest Accept header) to
+ *   resolve the Docker-Content-Digest, then
+ *   DELETE /v2/<repo>/manifests/<digest>.
+ * Gitea/Forgejo also accepts DELETE .../manifests/<tag> directly, so when
+ * the digest lookup fails we fall back to deleting by tag reference.
+ * Returns normally on success (2xx); throws otherwise.
  */
 export async function deleteTag(cfg, tag) {
   const repo = registryRepoName(cfg);
   const host = registryHost(cfg.image.registry);
-  const res = await apiRequest(cfg, "DELETE", `/v2/${repo}/tags/${encodeURIComponent(tag)}`);
+  const ref = encodeURIComponent(tag);
+  const deleteScope = `repository:${repo}:pull,push,delete`;
+  const manifestAccept = [
+    "application/vnd.docker.distribution.manifest.v2+json",
+    "application/vnd.docker.distribution.manifest.list.v2+json",
+    "application/vnd.oci.image.manifest.v1+json",
+    "application/vnd.oci.image.index.v1+json",
+  ].join(", ");
+
+  // Resolve the manifest digest for the tag. A 404 here means the tag is
+  // already gone.
+  const manifestRes = await apiRequest(
+    cfg,
+    "GET",
+    `/v2/${repo}/manifests/${ref}`,
+    { Accept: manifestAccept },
+    deleteScope
+  );
+  let digest = manifestRes.headers.get("docker-content-digest");
+  if (manifestRes.status === 404) {
+    throw new Error(`tag ${tag} not found (already deleted?)`);
+  }
+  if (!manifestRes.ok || !digest) {
+    // Registry did not return a digest (e.g. it rejects GET manifests by
+    // tag): try deleting the tag reference directly (Gitea supports
+    // DELETE .../manifests/<tag>).
+    const direct = await apiRequest(
+      cfg,
+      "DELETE",
+      `/v2/${repo}/manifests/${ref}`,
+      {},
+      deleteScope
+    );
+    if (direct.status === 404) {
+      throw new Error(`tag ${tag} not found (already deleted?)`);
+    }
+    if (direct.status === 405) {
+      throw new Error(
+        `registry ${host} does not support deleting tags through the registry API (405) — ` +
+          `e.g. AWS ECR requires the AWS BatchDeleteImage API instead`
+      );
+    }
+    if (!direct.ok) {
+      throw new Error(`deleting tag ${tag} failed with ${direct.status} ${direct.statusText}`.trim());
+    }
+    return;
+  }
+
+  digest = digest.trim();
+  const res = await apiRequest(cfg, "DELETE", `/v2/${repo}/manifests/${digest}`, {}, deleteScope);
   if (res.status === 404) {
     throw new Error(`tag ${tag} not found (already deleted?)`);
   }

package/src/utils/semver.js

@@ -19,6 +19,17 @@ export function compareSemver(a, b) {
   return 0;
 }
 
+/**
+ * Patch-bump a semver tag (vX.Y.Z -> vX.Y.Z+1). Assumes the input is semver.
+ */
+export function bumpPatch(tag) {
+  const m = typeof tag === "string" && tag.match(SEMVER_RE);
+  if (!m) {
+    throw new Error(`cannot bump patch: not a semver tag (vX.Y.Z), got: ${tag}`);
+  }
+  return `v${m[1]}.${m[2]}.${Number(m[3]) + 1}`;
+}
+
 /**
  * The semver tags of a list, sorted ascending (oldest first). Non-semver
  * tags (e.g. legacy timestamp tags) are excluded.

package/src/utils/ssh-config.js

@@ -11,11 +11,29 @@ export function sshConfigPath() {
   return path.join(os.homedir(), ".ssh", "config");
 }
 
+import { sshPrefix } from "./instance.js";
+
 /**
- * Alias convention for container hosts: coding-<project>.
+ * Alias convention for container hosts: <prefix><project> (default
+ * "coding-<project>"; CODING_SSH_PREFIX in PROJECT_FOLDER/.env overrides
+ * the prefix so dev/prod copies don't overwrite each other's aliases).
  */
 export function sshAlias(project) {
-  return `coding-${project}`;
+  return `${sshPrefix()}${project}`;
+}
+
+/**
+ * Inverse of sshAlias(): strip this instance's prefix. Returns null when the
+ * alias belongs to a sibling instance sharing the same managed block, so
+ * `list update` leaves other copies' aliases untouched (each copy manages
+ * only its own entries; the sibling's own runs update those).
+ */
+export function sshProjectFromAlias(alias) {
+  const prefix = sshPrefix();
+  if (alias.startsWith(prefix) && alias.length > prefix.length) {
+    return alias.slice(prefix.length);
+  }
+  return null;
 }
 
 /**
@@ -64,7 +82,9 @@ function readManaged(file) {
   const entries = {};
   let current = null;
   for (const line of lines.slice(bi + 1, ei)) {
-    const m = line.match(/^Host (coding-[a-z0-9-]+)\s*$/);
+    // Shared managed block: accept any Host alias inside the markers so
+    // sibling instances (different CODING_SSH_PREFIX) coexist.
+    const m = line.match(/^Host ([A-Za-z0-9._-]+)\s*$/);
     if (m) {
       current = m[1];
       entries[current] = [line];