@getmonoceros/workbench 1.6.11 → 1.7.0

package/dist/bin.js

@@ -251,25 +251,25 @@ function detectHelpRequest(argv, main2) {
   const separatorIdx = argv.indexOf("--");
   if (helpIdx === -1) return null;
   if (separatorIdx !== -1 && separatorIdx < helpIdx) return null;
-  const path13 = [];
+  const path15 = [];
   const tokens = argv.slice(
     0,
     separatorIdx === -1 ? argv.length : separatorIdx
   );
   let cursor = main2;
   const mainName = (main2.meta ?? {}).name ?? "monoceros";
-  path13.push(mainName);
+  path15.push(mainName);
   for (const tok of tokens) {
     if (tok.startsWith("-")) continue;
     const subs = cursor.subCommands ?? {};
     if (tok in subs) {
       cursor = subs[tok];
-      path13.push(tok);
+      path15.push(tok);
       continue;
     }
     break;
   }
-  return { path: path13, cmd: cursor };
+  return { path: path15, cmd: cursor };
 }
 async function maybeRenderHelp(argv, main2) {
   const hit = detectHelpRequest(argv, main2);
@@ -301,14 +301,14 @@ function getInnerArgs() {
 }
 
 // src/main.ts
-import { defineCommand as defineCommand25 } from "citty";
+import { defineCommand as defineCommand28 } from "citty";
 
 // src/commands/add-apt-packages.ts
 import { defineCommand } from "citty";
 import { consola as consola2 } from "consola";
 
 // src/modify/index.ts
-import { promises as fs3 } from "fs";
+import { promises as fs6 } from "fs";
 import { consola } from "consola";
 import { createPatch } from "diff";
 
@@ -392,6 +392,16 @@ var RepoEntrySchema = z.object({
   // parse time — see ADR 0006.
   provider: z.enum(PROVIDER_VALUES).optional()
 });
+var PortEntrySchema = z.union([
+  z.number().int().min(1, "Port must be \u2265 1.").max(65535, "Port must be \u2264 65535."),
+  z.object({
+    port: z.number().int().min(1, "Port must be \u2265 1.").max(65535, "Port must be \u2264 65535.")
+  })
+]);
+var RoutingSchema = z.object({
+  ports: z.array(PortEntrySchema).default([]),
+  vscodeAutoForward: z.boolean().optional()
+});
 var ExternalServicesSchema = z.object({
   postgres: z.string().regex(
     POSTGRES_URL_RE,
@@ -420,11 +430,15 @@ var SolutionConfigSchema = z.object({
   ).default([]),
   services: z.array(z.string().min(1)).default([]),
   repos: z.array(RepoEntrySchema).default([]),
+  routing: RoutingSchema.optional(),
   externalServices: ExternalServicesSchema.default({}),
   git: z.object({
     user: GitUserSchema.optional()
   }).optional()
 });
+function portNumber(entry2) {
+  return typeof entry2 === "number" ? entry2 : entry2.port;
+}
 function validateConfig(input) {
   const result = SolutionConfigSchema.safeParse(input);
   if (!result.success) {
@@ -553,6 +567,343 @@ function prettyPath(p) {
   return p;
 }
 
+// src/config/global.ts
+import { promises as fs2 } from "fs";
+import { z as z2 } from "zod";
+import { parseDocument as parseDocument2 } from "yaml";
+var SCHEMA_VERSION = 1;
+var MonocerosConfigSchema = z2.object({
+  schemaVersion: z2.literal(SCHEMA_VERSION),
+  // .nullish() (= .optional().nullable()) on defaults so the shipped
+  // sample yml — where `defaults:` is uncommented but every sub-block
+  // is commented out — parses cleanly. YAML produces `defaults: null`
+  // in that case; without .nullish() the schema would reject it and
+  // we'd be back to forcing builders to comment-juggle three lines.
+  defaults: z2.object({
+    // .nullish() (not just .optional()) so the sample yml can leave
+    // `git:` uncommented as a category marker — YAML produces
+    // `git: null` for an empty mapping, which zod's plain
+    // `.optional()` would reject.
+    git: z2.object({
+      user: GitUserSchema.optional()
+    }).nullish(),
+    // .nullish() for the same reason as `git` — the sample keeps
+    // `features:` uncommented as a category marker.
+    features: z2.record(
+      z2.string().regex(
+        REGEX.featureRef,
+        "Invalid feature ref. Expected an OCI-image-style ref like 'ghcr.io/getmonoceros/monoceros-features/<name>:<tag>'."
+      ),
+      z2.record(z2.string(), FeatureOptionValueSchema)
+    ).nullish()
+  }).nullish(),
+  // Machine-global routing settings — one Traefik per builder, so
+  // host-port and similar live here rather than in any container yml.
+  // See ADR 0007.
+  routing: z2.object({
+    hostPort: z2.number().int().min(1).max(65535).optional().describe(
+      "Host port the Traefik singleton binds. Default 80. Set this when 80 is held by another service on your machine \u2014 URLs then become http://<name>.localhost:<port>/."
+    )
+  }).nullish()
+});
+async function readMonocerosConfig(opts = {}) {
+  const home = opts.monocerosHome ?? monocerosHome();
+  const filePath = monocerosConfigPath(home);
+  let text;
+  try {
+    text = await fs2.readFile(filePath, "utf8");
+  } catch {
+    return void 0;
+  }
+  const doc = parseDocument2(text, { prettyErrors: true });
+  if (doc.errors.length > 0) {
+    throw new Error(
+      `yaml parse error in ${filePath}: ${doc.errors[0].message}`
+    );
+  }
+  const result = MonocerosConfigSchema.safeParse(doc.toJS());
+  if (!result.success) {
+    const issues = result.error.issues.map((issue) => {
+      const where = issue.path.length > 0 ? issue.path.join(".") : "(root)";
+      return `  - ${where}: ${issue.message}`;
+    }).join("\n");
+    throw new Error(
+      `Invalid ${filePath}:
+${issues}
+
+See ${filePath.replace(
+        /\.yml$/,
+        ".sample.yml"
+      )} for a valid example.`
+    );
+  }
+  return result.data;
+}
+var DEFAULT_PROXY_HOST_PORT = 80;
+function proxyHostPort(config) {
+  return config?.routing?.hostPort ?? DEFAULT_PROXY_HOST_PORT;
+}
+
+// src/proxy/index.ts
+import { spawn } from "child_process";
+import { promises as fs3 } from "fs";
+import path2 from "path";
+var PROXY_CONTAINER_NAME = "monoceros-proxy";
+var PROXY_NETWORK_NAME = "monoceros-proxy";
+var TRAEFIK_IMAGE = "traefik:v3.3";
+var defaultDockerExec = (args) => {
+  return new Promise((resolve, reject) => {
+    const child = spawn("docker", args, {
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", reject);
+    child.on(
+      "exit",
+      (code) => resolve({ stdout, stderr, exitCode: code ?? 0 })
+    );
+  });
+};
+var realDocker = defaultDockerExec;
+function proxyDynamicDir(home) {
+  return path2.join(home ?? monocerosHome(), "traefik", "dynamic");
+}
+async function ensureProxy(opts = {}) {
+  const docker = opts.docker ?? realDocker;
+  const dyn = proxyDynamicDir(opts.monocerosHome);
+  await fs3.mkdir(dyn, { recursive: true });
+  const netInspect = await docker(["network", "inspect", PROXY_NETWORK_NAME]);
+  if (netInspect.exitCode !== 0) {
+    const create = await docker(["network", "create", PROXY_NETWORK_NAME]);
+    if (create.exitCode !== 0) {
+      throw new Error(
+        `Could not create docker network ${PROXY_NETWORK_NAME}: ${create.stderr.trim() || `exit ${create.exitCode}`}`
+      );
+    }
+  }
+  const state = await docker([
+    "inspect",
+    "--format",
+    "{{.State.Running}}",
+    PROXY_CONTAINER_NAME
+  ]);
+  if (state.exitCode === 0) {
+    if (state.stdout.trim() === "true") return;
+    const start = await docker(["start", PROXY_CONTAINER_NAME]);
+    if (start.exitCode !== 0) {
+      throw new Error(
+        `Could not start existing ${PROXY_CONTAINER_NAME} container: ${start.stderr.trim() || `exit ${start.exitCode}`}`
+      );
+    }
+    return;
+  }
+  const hostPort = opts.hostPort ?? 80;
+  const run = await docker([
+    "run",
+    "-d",
+    "--name",
+    PROXY_CONTAINER_NAME,
+    "--network",
+    PROXY_NETWORK_NAME,
+    "-p",
+    `${hostPort}:80`,
+    "-v",
+    `${dyn}:/etc/traefik/dynamic:ro`,
+    "--label",
+    "monoceros.role=proxy",
+    TRAEFIK_IMAGE,
+    "--entrypoints.web.address=:80",
+    "--providers.file.directory=/etc/traefik/dynamic",
+    "--providers.file.watch=true",
+    "--providers.docker=false",
+    "--api.dashboard=false",
+    "--log.level=INFO"
+  ]);
+  if (run.exitCode !== 0) {
+    throw new Error(
+      `Could not start ${PROXY_CONTAINER_NAME}: ${run.stderr.trim() || `exit ${run.exitCode}`}`
+    );
+  }
+  opts.logger?.info(
+    `Started ${PROXY_CONTAINER_NAME} (Traefik on :${hostPort}).`
+  );
+}
+async function maybeStopProxy(opts = {}) {
+  const docker = opts.docker ?? realDocker;
+  const logger = opts.logger;
+  const inspect = await docker([
+    "network",
+    "inspect",
+    PROXY_NETWORK_NAME,
+    "--format",
+    "{{range $k, $v := .Containers}}{{$v.Name}}\n{{end}}"
+  ]);
+  if (inspect.exitCode !== 0) {
+    return;
+  }
+  const others = inspect.stdout.split("\n").map((n) => n.trim()).filter((n) => n.length > 0 && n !== PROXY_CONTAINER_NAME);
+  if (others.length > 0) return;
+  await docker(["rm", "-f", PROXY_CONTAINER_NAME]);
+  const netRm = await docker(["network", "rm", PROXY_NETWORK_NAME]);
+  if (netRm.exitCode !== 0) {
+    logger?.warn?.(
+      `Could not remove docker network ${PROXY_NETWORK_NAME}: ${netRm.stderr.trim() || `exit ${netRm.exitCode}`}`
+    );
+    return;
+  }
+  logger?.info(
+    `Stopped ${PROXY_CONTAINER_NAME} (no dev-containers with ports left).`
+  );
+}
+
+// src/proxy/dynamic.ts
+import { promises as fs4 } from "fs";
+import path3 from "path";
+async function writeDynamicConfig(name, ports, opts = {}) {
+  if (ports.length === 0) {
+    throw new Error(
+      `writeDynamicConfig requires at least one port. For empty port lists, call removeDynamicConfig(${JSON.stringify(name)}).`
+    );
+  }
+  const dir = proxyDynamicDir(opts.monocerosHome);
+  await fs4.mkdir(dir, { recursive: true });
+  const file = path3.join(dir, `${name}.yml`);
+  await fs4.writeFile(file, renderDynamicConfig(name, ports), "utf8");
+  return file;
+}
+async function removeDynamicConfig(name, opts = {}) {
+  const file = path3.join(proxyDynamicDir(opts.monocerosHome), `${name}.yml`);
+  await fs4.rm(file, { force: true });
+}
+function renderDynamicConfig(name, ports) {
+  const lines = [];
+  lines.push("# Generated by Monoceros \u2014 do not edit by hand.");
+  lines.push(`# Container: ${name}`);
+  lines.push(`# Ports: ${ports.join(", ")}`);
+  lines.push("# Traefik file-provider re-reads this on change (~100 ms);");
+  lines.push(
+    "# to change routing, edit container-configs/" + name + ".yml or use"
+  );
+  lines.push("# `monoceros add-port` / `monoceros remove-port`.");
+  lines.push("http:");
+  lines.push("  routers:");
+  ports.forEach((port, idx) => {
+    const router = `${name}-${port}`;
+    const hostExplicit = `${name}-${port}.localhost`;
+    const rule = idx === 0 ? `"Host(\`${name}.localhost\`) || Host(\`${hostExplicit}\`)"` : `"Host(\`${hostExplicit}\`)"`;
+    lines.push(`    ${router}:`);
+    lines.push(`      rule: ${rule}`);
+    lines.push(`      service: ${router}`);
+    lines.push("      entryPoints:");
+    lines.push("        - web");
+  });
+  lines.push("  services:");
+  for (const port of ports) {
+    const svc = `${name}-${port}`;
+    lines.push(`    ${svc}:`);
+    lines.push("      loadBalancer:");
+    lines.push("        servers:");
+    lines.push(`          - url: "http://${name}:${port}"`);
+  }
+  return lines.join("\n") + "\n";
+}
+function proxyUrlsFor(name, ports, hostPort = 80) {
+  const portSuffix = hostPort === 80 ? "" : `:${hostPort}`;
+  return ports.map((port, idx) => ({
+    port,
+    url: `http://${name}-${port}.localhost${portSuffix}`,
+    isDefault: idx === 0
+  }));
+}
+
+// src/proxy/port-check.ts
+import { createServer } from "net";
+var realPortProbe = (port) => {
+  return new Promise((resolve) => {
+    const server = createServer();
+    server.unref();
+    server.once("error", (err) => {
+      resolve({
+        ok: false,
+        code: err.code ?? "UNKNOWN",
+        message: err.message
+      });
+    });
+    server.once("listening", () => {
+      server.close(() => resolve({ ok: true }));
+    });
+    server.listen(port, "0.0.0.0");
+  });
+};
+async function preflightHostPort(hostPort, opts = {}) {
+  const docker = opts.docker ?? defaultDockerExec;
+  const inspect = await docker([
+    "inspect",
+    "--format",
+    "{{.State.Running}}",
+    PROXY_CONTAINER_NAME
+  ]);
+  if (inspect.exitCode === 0 && inspect.stdout.trim() === "true") {
+    return;
+  }
+  const probe = opts.portProbe ?? realPortProbe;
+  const result = await probe(hostPort);
+  if (result.ok) return;
+  throw new Error(
+    formatHostPortHeldError(hostPort, result.code, result.message)
+  );
+}
+function formatHostPortHeldError(hostPort, code, systemMessage) {
+  const isInUse = code === "EADDRINUSE";
+  const lines = [];
+  if (isInUse) {
+    lines.push(`Host port ${hostPort} is already in use by another process.`);
+    lines.push("");
+    lines.push(`Monoceros needs that port for its Traefik proxy (the thing`);
+    lines.push(`that routes <name>.localhost / <name>-<port>.localhost to`);
+    lines.push(`your dev-container). Two ways out:`);
+    lines.push("");
+    lines.push("  1) Recommended: free the port.");
+    lines.push("     Identify the process holding it:");
+    lines.push(`        sudo lsof -iTCP:${hostPort} -sTCP:LISTEN -n -P`);
+    lines.push(`        # or:   sudo ss -tlnp | grep ":${hostPort}\\b"`);
+    lines.push("     Then stop or reconfigure that service.");
+    lines.push("");
+    lines.push("  2) Move Monoceros off port 80. Edit (or create)");
+    lines.push("     ~/.monoceros/monoceros-config.yml and add:");
+    lines.push("");
+    lines.push("        schemaVersion: 1");
+    lines.push("        routing:");
+    lines.push("          hostPort: 8080      # any free port");
+    lines.push("");
+    lines.push("     URLs will become http://<name>.localhost:8080/.");
+    lines.push("");
+    lines.push(`Aborting \u2014 re-run after the conflict is resolved.`);
+  } else {
+    lines.push(`Cannot bind host port ${hostPort}: ${systemMessage}`);
+    lines.push("");
+    if (code === "EACCES") {
+      lines.push(`Port ${hostPort} is a privileged port (<1024) and your`);
+      lines.push(`current Docker setup can't bind it. For rootful Docker`);
+      lines.push(`(what Monoceros requires) this should normally work \u2014`);
+      lines.push(`check that the docker daemon is running as root.`);
+      lines.push("");
+    }
+    lines.push("You can also move Monoceros off this port by setting");
+    lines.push("`routing.hostPort` in ~/.monoceros/monoceros-config.yml.");
+    lines.push("");
+    lines.push(`Aborting \u2014 re-run after the issue is resolved.`);
+  }
+  return lines.join("\n");
+}
+
 // src/create/catalog.ts
 var DEFAULT_BASE_IMAGE = "ghcr.io/getmonoceros/monoceros-runtime:1";
 var override = process.env.MONOCEROS_BASE_IMAGE_OVERRIDE?.trim();
@@ -610,8 +961,8 @@ function knownServices() {
 }
 
 // src/create/scaffold.ts
-import { existsSync as existsSync2, readFileSync, promises as fs2 } from "fs";
-import path2 from "path";
+import { existsSync as existsSync2, readFileSync, promises as fs5 } from "fs";
+import path4 from "path";
 
 // src/util/ref.ts
 var FEATURE_NAME_CHARSET = "[a-z0-9._-]+";
@@ -732,6 +1083,7 @@ function normalizeOptions(opts) {
   const repos = opts.repos ? Array.from(
     new Map(opts.repos.map((r) => [`${r.url}
${r.path}`, r])).values()
   ) : void 0;
+  const ports = opts.ports ? [...new Set(opts.ports)] : void 0;
   return {
     name: opts.name,
     languages,
@@ -740,7 +1092,9 @@ function normalizeOptions(opts) {
     ...aptPackages.length > 0 ? { aptPackages } : {},
     ...features && Object.keys(features).length > 0 ? { features } : {},
     ...installUrls && installUrls.length > 0 ? { installUrls } : {},
-    ...repos && repos.length > 0 ? { repos } : {}
+    ...repos && repos.length > 0 ? { repos } : {},
+    ...ports && ports.length > 0 ? { ports } : {},
+    ...opts.vscodeAutoForward !== void 0 ? { vscodeAutoForward: opts.vscodeAutoForward } : {}
   };
 }
 function needsCompose(opts) {
@@ -779,7 +1133,7 @@ function resolveFeatures(opts) {
       if (match) {
         const name = match.name;
         const checkout = workbenchCheckoutRoot();
-        const localSourceDir = checkout ? path2.join(checkout, "images", "features", name) : null;
+        const localSourceDir = checkout ? path4.join(checkout, "images", "features", name) : null;
         if (localSourceDir && existsSync2(localSourceDir)) {
           const { paths, files } = readPersistentHomeEntries(localSourceDir);
           resolved.push({
@@ -804,7 +1158,7 @@ function resolveFeatures(opts) {
   return resolved;
 }
 function readPersistentHomeEntries(localSourceDir) {
-  const manifestPath = path2.join(localSourceDir, "devcontainer-feature.json");
+  const manifestPath = path4.join(localSourceDir, "devcontainer-feature.json");
   try {
     const text = readFileSync(manifestPath, "utf8");
     const parsed = JSON.parse(text);
@@ -866,6 +1220,16 @@ function buildDevcontainerJson(opts, dockerMode = "rootful") {
       );
     }
   }
+  const ports = opts.ports ?? [];
+  const customizationsField = ports.length > 0 ? {
+    customizations: {
+      vscode: {
+        settings: {
+          "remote.autoForwardPorts": opts.vscodeAutoForward ?? false
+        }
+      }
+    }
+  } : void 0;
   if (needsCompose(opts)) {
     return {
       name: opts.name,
@@ -874,34 +1238,49 @@ function buildDevcontainerJson(opts, dockerMode = "rootful") {
       ...opts.services.length > 0 ? { runServices: opts.services } : {},
       workspaceFolder: `/workspaces/${opts.name}`,
       remoteUser: "node",
-      forwardPorts: [3e3, 4e3],
+      forwardPorts: ports,
       postCreateCommand: ".devcontainer/post-create.sh",
-      ...featuresField ?? {}
+      ...featuresField ?? {},
+      ...customizationsField ?? {}
     };
   }
   const mounts = [...homeMounts];
   const mountsField = mounts.length > 0 ? { mounts } : {};
   const workspaceMountField = {};
+  const runArgs = ["--cap-add=NET_ADMIN"];
+  if (ports.length > 0) {
+    runArgs.push("--network=monoceros-proxy");
+    runArgs.push(`--network-alias=${opts.name}`);
+  }
   return {
     name: opts.name,
     image: BASE_IMAGE,
     remoteUser: "node",
     ...workspaceMountField,
     ...mountsField,
-    runArgs: ["--cap-add=NET_ADMIN"],
-    forwardPorts: [3e3, 4e3],
+    runArgs,
+    forwardPorts: ports,
     postCreateCommand: ".devcontainer/post-create.sh",
-    ...featuresField ?? {}
+    ...featuresField ?? {},
+    ...customizationsField ?? {}
   };
 }
 function buildComposeYaml(opts, dockerMode = "rootful") {
   void dockerMode;
+  const hasPorts = (opts.ports?.length ?? 0) > 0;
   const lines = ["services:"];
   lines.push("  workspace:");
   lines.push(`    image: ${BASE_IMAGE}`);
   lines.push("    command: 'sleep infinity'");
   lines.push("    cap_add:");
   lines.push("      - NET_ADMIN");
+  if (hasPorts) {
+    lines.push("    networks:");
+    lines.push("      default: {}");
+    lines.push("      monoceros-proxy:");
+    lines.push("        aliases:");
+    lines.push(`          - ${opts.name}`);
+  }
   lines.push("    volumes:");
   lines.push(`      - ..:/workspaces/${opts.name}:cached`);
   const resolvedFeatures = resolveFeatures(opts);
@@ -930,6 +1309,11 @@ function buildComposeYaml(opts, dockerMode = "rootful") {
       lines.push(`      - ../data/${def.id}:${def.dataMount}`);
     }
   }
+  if (hasPorts) {
+    lines.push("networks:");
+    lines.push("  monoceros-proxy:");
+    lines.push("    external: true");
+  }
   return lines.join("\n") + "\n";
 }
 function buildCodeWorkspaceJson(opts) {
@@ -1039,77 +1423,77 @@ function buildPostCreateScript(opts) {
   return lines.join("\n") + "\n";
 }
 async function writePostCreateScript(devcontainerDir, opts) {
-  const dest = path2.join(devcontainerDir, "post-create.sh");
-  await fs2.writeFile(dest, buildPostCreateScript(opts));
-  await fs2.chmod(dest, 493);
+  const dest = path4.join(devcontainerDir, "post-create.sh");
+  await fs5.writeFile(dest, buildPostCreateScript(opts));
+  await fs5.chmod(dest, 493);
 }
 async function writeScaffold(opts, targetDir, scaffoldOpts = {}) {
   const dockerMode = scaffoldOpts.dockerMode ?? "rootful";
-  const devcontainerDir = path2.join(targetDir, ".devcontainer");
-  const monocerosDir = path2.join(targetDir, ".monoceros");
-  const projectsDir = path2.join(targetDir, "projects");
-  const homeDir = path2.join(targetDir, "home");
-  const dataDir = path2.join(targetDir, "data");
-  await fs2.mkdir(devcontainerDir, { recursive: true });
-  await fs2.mkdir(monocerosDir, { recursive: true });
-  await fs2.mkdir(projectsDir, { recursive: true });
-  await fs2.mkdir(homeDir, { recursive: true });
+  const devcontainerDir = path4.join(targetDir, ".devcontainer");
+  const monocerosDir = path4.join(targetDir, ".monoceros");
+  const projectsDir = path4.join(targetDir, "projects");
+  const homeDir = path4.join(targetDir, "home");
+  const dataDir = path4.join(targetDir, "data");
+  await fs5.mkdir(devcontainerDir, { recursive: true });
+  await fs5.mkdir(monocerosDir, { recursive: true });
+  await fs5.mkdir(projectsDir, { recursive: true });
+  await fs5.mkdir(homeDir, { recursive: true });
   if (needsCompose(opts)) {
-    await fs2.mkdir(dataDir, { recursive: true });
+    await fs5.mkdir(dataDir, { recursive: true });
     for (const svcId of opts.services) {
       const def = SERVICE_CATALOG[svcId];
       if (def?.dataMount) {
-        await fs2.mkdir(path2.join(dataDir, def.id), { recursive: true });
+        await fs5.mkdir(path4.join(dataDir, def.id), { recursive: true });
       }
     }
   }
-  const containerGitignore = path2.join(targetDir, ".gitignore");
-  await fs2.writeFile(containerGitignore, "/home/\n/.monoceros/\n/data/\n");
-  const gitkeep = path2.join(projectsDir, ".gitkeep");
+  const containerGitignore = path4.join(targetDir, ".gitignore");
+  await fs5.writeFile(containerGitignore, "/home/\n/.monoceros/\n/data/\n");
+  const gitkeep = path4.join(projectsDir, ".gitkeep");
   if (!existsSync2(gitkeep)) {
-    await fs2.writeFile(gitkeep, "");
+    await fs5.writeFile(gitkeep, "");
   }
-  await fs2.writeFile(
-    path2.join(monocerosDir, ".gitignore"),
+  await fs5.writeFile(
+    path4.join(monocerosDir, ".gitignore"),
     "git-credentials*\ngitconfig\n"
   );
   const devcontainerJson = buildDevcontainerJson(opts, dockerMode);
-  await fs2.writeFile(
-    path2.join(devcontainerDir, "devcontainer.json"),
+  await fs5.writeFile(
+    path4.join(devcontainerDir, "devcontainer.json"),
     JSON.stringify(devcontainerJson, null, 2) + "\n"
   );
-  const featuresDir = path2.join(devcontainerDir, "features");
+  const featuresDir = path4.join(devcontainerDir, "features");
   if (existsSync2(featuresDir)) {
-    await fs2.rm(featuresDir, { recursive: true, force: true });
+    await fs5.rm(featuresDir, { recursive: true, force: true });
   }
   const resolvedFeatures = resolveFeatures(opts);
   for (const f of resolvedFeatures) {
     if (!f.localSourceDir || !f.localName) continue;
-    const dest = path2.join(featuresDir, f.localName);
-    await fs2.mkdir(dest, { recursive: true });
-    await fs2.cp(f.localSourceDir, dest, { recursive: true });
+    const dest = path4.join(featuresDir, f.localName);
+    await fs5.mkdir(dest, { recursive: true });
+    await fs5.cp(f.localSourceDir, dest, { recursive: true });
   }
   for (const f of resolvedFeatures) {
     for (const sub of f.persistentHomePaths) {
-      await fs2.mkdir(path2.join(homeDir, sub), { recursive: true });
+      await fs5.mkdir(path4.join(homeDir, sub), { recursive: true });
     }
     for (const entry2 of f.persistentHomeFiles) {
-      const filePath = path2.join(homeDir, entry2.path);
-      await fs2.mkdir(path2.dirname(filePath), { recursive: true });
+      const filePath = path4.join(homeDir, entry2.path);
+      await fs5.mkdir(path4.dirname(filePath), { recursive: true });
       if (!existsSync2(filePath)) {
-        await fs2.writeFile(filePath, entry2.initialContent);
+        await fs5.writeFile(filePath, entry2.initialContent);
       }
     }
   }
   await writePostCreateScript(devcontainerDir, opts);
-  const composePath = path2.join(devcontainerDir, "compose.yaml");
+  const composePath = path4.join(devcontainerDir, "compose.yaml");
   if (needsCompose(opts)) {
-    await fs2.writeFile(composePath, buildComposeYaml(opts, dockerMode));
+    await fs5.writeFile(composePath, buildComposeYaml(opts, dockerMode));
   } else if (existsSync2(composePath)) {
-    await fs2.rm(composePath);
+    await fs5.rm(composePath);
   }
-  await fs2.writeFile(
-    path2.join(targetDir, `${opts.name}.code-workspace`),
+  await fs5.writeFile(
+    path4.join(targetDir, `${opts.name}.code-workspace`),
     JSON.stringify(buildCodeWorkspaceJson(opts), null, 2) + "\n"
   );
 }
@@ -1154,6 +1538,82 @@ function addAptPackagesToDoc(doc, packages) {
   }
   return changed;
 }
+function portOfItem(item) {
+  const scalar = scalarValue(item);
+  if (typeof scalar === "number" && Number.isInteger(scalar)) {
+    return scalar;
+  }
+  if (isMap(item)) {
+    const p = item.get("port");
+    if (typeof p === "number" && Number.isInteger(p)) return p;
+  }
+  return null;
+}
+function ensureRoutingMap(doc) {
+  const existing = doc.get("routing", true);
+  if (existing && isMap(existing)) return existing;
+  const map = new YAMLMap();
+  doc.set("routing", map);
+  return map;
+}
+function setDefaultPortInDoc(doc, port) {
+  const routing = ensureRoutingMap(doc);
+  const existing = routing.get("ports", true);
+  let seq;
+  if (existing && isSeq(existing)) {
+    seq = existing;
+  } else {
+    seq = new YAMLSeq();
+    routing.set("ports", seq);
+  }
+  const currentIdx = seq.items.findIndex((i) => portOfItem(i) === port);
+  if (currentIdx === 0) return false;
+  if (currentIdx > 0) {
+    const [item] = seq.items.splice(currentIdx, 1);
+    seq.items.unshift(item);
+    return true;
+  }
+  seq.items.unshift(port);
+  return true;
+}
+function addPortsToDoc(doc, ports) {
+  const routing = ensureRoutingMap(doc);
+  const existing = routing.get("ports", true);
+  let seq;
+  if (existing && isSeq(existing)) {
+    seq = existing;
+  } else {
+    seq = new YAMLSeq();
+    routing.set("ports", seq);
+  }
+  let changed = false;
+  for (const port of ports) {
+    if (seq.items.some((i) => portOfItem(i) === port)) continue;
+    seq.add(port);
+    changed = true;
+  }
+  return changed;
+}
+function removePortsFromDoc(doc, ports) {
+  const routing = doc.get("routing", true);
+  if (!routing || !isMap(routing)) return false;
+  const seq = routing.get("ports", true);
+  if (!seq || !isSeq(seq)) return false;
+  const targets = new Set(ports);
+  let changed = false;
+  for (let i = seq.items.length - 1; i >= 0; i--) {
+    const p = portOfItem(seq.items[i]);
+    if (p !== null && targets.has(p)) {
+      seq.items.splice(i, 1);
+      changed = true;
+    }
+  }
+  if (changed) {
+    if (seq.items.length === 0) routing.delete("ports");
+    if (routing.items.length === 0) doc.delete("routing");
+  }
+  return changed;
+}
 function addInstallUrlToDoc(doc, url) {
   const seq = ensureSeq(doc, "installUrls");
   if (seq.items.some((i) => scalarValue(i) === url)) return false;
@@ -1274,8 +1734,8 @@ function removeRepoFromDoc(doc, urlOrPath) {
     if (!isMap(item)) return false;
     const url = item.get("url");
     if (url === urlOrPath) return true;
-    const path13 = item.get("path");
-    const effectivePath = typeof path13 === "string" ? path13 : typeof url === "string" ? deriveRepoName(url) : void 0;
+    const path15 = item.get("path");
+    const effectivePath = typeof path15 === "string" ? path15 : typeof url === "string" ? deriveRepoName(url) : void 0;
     return effectivePath === urlOrPath;
   });
   if (idx < 0) return false;
@@ -1325,7 +1785,7 @@ async function runAddRepo(input) {
       "Missing repo URL. Usage: monoceros add-repo <containername> <url>."
     );
   }
-  const path13 = (input.path ?? deriveRepoName(url)).trim();
+  const path15 = (input.path ?? deriveRepoName(url)).trim();
   const hasName = typeof input.gitName === "string" && input.gitName.trim().length > 0;
   const hasEmail = typeof input.gitEmail === "string" && input.gitEmail.trim().length > 0;
   if (hasName !== hasEmail) {
@@ -1354,7 +1814,7 @@ async function runAddRepo(input) {
   const providerToWrite = !canonical && explicitProvider ? explicitProvider : void 0;
   const entry2 = {
     url,
-    path: path13,
+    path: path15,
     ...hasName && hasEmail ? {
       gitUser: {
         name: input.gitName.trim(),
@@ -1386,6 +1846,45 @@ function runAddFromUrl(input) {
   }
   return mutate(input, (doc) => addInstallUrlToDoc(doc, url));
 }
+async function runAddPort(input) {
+  if (input.ports.length === 0) {
+    throw new Error(
+      "No ports given. Usage: monoceros add-port <containername> -- <port> [<port> \u2026]."
+    );
+  }
+  const ports = normalizePorts(input.ports);
+  if (input.asDefault && ports.length > 1) {
+    throw new Error(
+      `--default takes exactly one port. Got: ${ports.join(", ")}. Run add-port once with --default for the new default, then again (without --default) for the rest.`
+    );
+  }
+  const result = await mutate(input, (doc) => {
+    if (input.asDefault) {
+      return setDefaultPortInDoc(doc, ports[0]);
+    }
+    return addPortsToDoc(doc, ports);
+  });
+  if (result.status === "updated") {
+    await syncPortsToProxy(input);
+  }
+  return result;
+}
+function normalizePorts(raw) {
+  const result = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const item of raw) {
+    const n = typeof item === "number" ? item : Number(item);
+    if (!Number.isInteger(n) || n < 1 || n > 65535) {
+      throw new Error(
+        `Invalid port: ${JSON.stringify(item)}. Expected an integer between 1 and 65535.`
+      );
+    }
+    if (seen.has(n)) continue;
+    seen.add(n);
+    result.push(n);
+  }
+  return result;
+}
 function runAddFeature(input) {
   const ref = input.ref.trim();
   if (ref.length === 0) {
@@ -1427,6 +1926,19 @@ function runRemoveFromUrl(input) {
   }
   return mutate(input, (doc) => removeInstallUrlFromDoc(doc, url));
 }
+async function runRemovePort(input) {
+  if (input.ports.length === 0) {
+    throw new Error(
+      "No ports given. Usage: monoceros remove-port <containername> -- <port> [<port> \u2026]."
+    );
+  }
+  const ports = normalizePorts(input.ports);
+  const result = await mutate(input, (doc) => removePortsFromDoc(doc, ports));
+  if (result.status === "updated") {
+    await syncPortsToProxy(input);
+  }
+  return result;
+}
 function runRemoveRepo(input) {
   const target = input.target.trim();
   if (target.length === 0) {
@@ -1447,7 +1959,7 @@ async function mutate(opts, apply) {
   const logger = opts.logger ?? defaultLogger();
   let oldText;
   try {
-    oldText = await fs3.readFile(ymlPath, "utf8");
+    oldText = await fs6.readFile(ymlPath, "utf8");
   } catch {
     throw new Error(
       `No such config: ${ymlPath}. Run \`monoceros init <template> ${opts.name}\` first.`
@@ -1471,7 +1983,7 @@ async function mutate(opts, apply) {
       return { status: "aborted" };
     }
   }
-  await fs3.writeFile(ymlPath, newText, "utf8");
+  await fs6.writeFile(ymlPath, newText, "utf8");
   logger.success(`Updated ${ymlPath}.`);
   logger.info(
     `Run \`monoceros apply ${opts.name}\` to rebuild the dev-container and pick up the change.`
@@ -1492,6 +2004,61 @@ var defaultConfirm = async (message) => {
   });
   return result === true;
 };
+async function syncPortsToProxy(input) {
+  const home = input.monocerosHome ?? monocerosHome();
+  const ymlPath = containerConfigPath(input.name, home);
+  const logger = input.logger ?? defaultLogger();
+  let allPorts;
+  try {
+    const parsed = await readConfig(ymlPath);
+    allPorts = (parsed.config.routing?.ports ?? []).map(portNumber);
+  } catch (err) {
+    logger.warn(
+      `Could not re-read yml after edit to sync Traefik routes: ${err instanceof Error ? err.message : String(err)}. The yml is correct; \`monoceros apply ${input.name}\` will rebuild the routes.`
+    );
+    return;
+  }
+  let hostPort = 80;
+  try {
+    const globalConfig = await readMonocerosConfig({ monocerosHome: home });
+    hostPort = proxyHostPort(globalConfig);
+  } catch {
+  }
+  if (allPorts.length > 0) {
+    await preflightHostPort(hostPort, {
+      ...input.proxyDocker ? { docker: input.proxyDocker } : {}
+    });
+  }
+  try {
+    if (allPorts.length > 0) {
+      await writeDynamicConfig(input.name, allPorts, { monocerosHome: home });
+      await ensureProxy({
+        monocerosHome: home,
+        hostPort,
+        ...input.proxyDocker ? { docker: input.proxyDocker } : {},
+        logger: { info: (m) => logger.info(m), warn: (m) => logger.warn(m) }
+      });
+      const urls = proxyUrlsFor(input.name, allPorts, hostPort);
+      const lines = urls.map((u) => {
+        const tag = u.isDefault ? " (default)" : "";
+        return `  ${u.url}${tag}`;
+      });
+      logger.info(`Traefik routes refreshed:
+${lines.join("\n")}`);
+    } else {
+      await removeDynamicConfig(input.name, { monocerosHome: home });
+      await maybeStopProxy({
+        monocerosHome: home,
+        ...input.proxyDocker ? { docker: input.proxyDocker } : {},
+        logger: { info: (m) => logger.info(m), warn: (m) => logger.warn(m) }
+      });
+    }
+  } catch (err) {
+    logger.warn(
+      `Could not sync Traefik routes after yml edit: ${err instanceof Error ? err.message : String(err)}. The yml is correct; \`monoceros apply ${input.name}\` will rebuild the routes.`
+    );
+  }
+}
 
 // src/commands/add-apt-packages.ts
 var addAptPackagesCommand = defineCommand({
@@ -1785,14 +2352,14 @@ var addLanguageCommand = defineCommand5({
   }
 });
 
-// src/commands/add-service.ts
+// src/commands/add-port.ts
 import { defineCommand as defineCommand6 } from "citty";
 import { consola as consola7 } from "consola";
-var addServiceCommand = defineCommand6({
+var addPortCommand = defineCommand6({
   meta: {
-    name: "add-service",
+    name: "add-port",
     group: "edit",
-    description: "Add a compose service (postgres, mysql, redis, \u2026) to the container config. Idempotent, prints a diff before writing."
+    description: "Add one or more ports to the container config so they become reachable from the host via Traefik (`<container>.localhost` / `<container>-<port>.localhost`). Pass port numbers after `--` (e.g. `monoceros add-port sandbox -- 3000 5173 6006`). Idempotent. Persisted in the yml so later `monoceros apply` runs restore the routes. Pass `--default` together with a single port to make it the bare `<container>.localhost` route \u2014 the port is inserted at position 0 (or moved there if it already exists)."
   },
   args: {
     name: {
@@ -1800,24 +2367,32 @@ var addServiceCommand = defineCommand6({
       description: "Container name (yml in $MONOCEROS_HOME/container-configs/).",
       required: true
     },
-    service: {
-      type: "positional",
-      description: "Service identifier (postgres, mysql, redis).",
-      required: true
-    },
     yes: {
       type: "boolean",
       description: "Skip the interactive confirmation and apply the diff.",
       alias: ["y"],
       default: false
+    },
+    default: {
+      type: "boolean",
+      description: "Make the (single) port the new default route at `<container>.localhost`. Inserts the port at position 0 of `routing.ports`, or moves it there if it already exists. Errors when more than one port is passed.",
+      default: false
     }
   },
   async run({ args }) {
+    const tokens = [...getInnerArgs()];
+    if (tokens.length === 0) {
+      consola7.error(
+        "No ports given. Usage: `monoceros add-port <containername> [--yes] [--default] -- <port> [<port> \u2026]`."
+      );
+      process.exit(1);
+    }
     try {
-      const result = await runAddService({
+      const result = await runAddPort({
         name: args.name,
-        service: args.service,
-        yes: args.yes
+        ports: tokens.map(coerceToken),
+        yes: args.yes,
+        asDefault: args.default
       });
       process.exit(result.status === "aborted" ? 1 : 0);
     } catch (err) {
@@ -1826,76 +2401,63 @@ var addServiceCommand = defineCommand6({
     }
   }
 });
+function coerceToken(raw) {
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : raw;
+}
 
-// src/commands/apply.ts
+// src/commands/add-service.ts
 import { defineCommand as defineCommand7 } from "citty";
-
-// src/apply/index.ts
-import { existsSync as existsSync4, promises as fs8 } from "fs";
-import { consola as consola10 } from "consola";
-
-// src/config/global.ts
-import { promises as fs4 } from "fs";
-import { z as z2 } from "zod";
-import { parseDocument as parseDocument2 } from "yaml";
-var SCHEMA_VERSION = 1;
-var MonocerosConfigSchema = z2.object({
-  schemaVersion: z2.literal(SCHEMA_VERSION),
-  // .nullish() (= .optional().nullable()) on defaults so the shipped
-  // sample yml — where `defaults:` is uncommented but every sub-block
-  // is commented out — parses cleanly. YAML produces `defaults: null`
-  // in that case; without .nullish() the schema would reject it and
-  // we'd be back to forcing builders to comment-juggle three lines.
-  defaults: z2.object({
-    git: z2.object({
-      user: GitUserSchema.optional()
-    }).optional(),
-    features: z2.record(
-      z2.string().regex(
-        REGEX.featureRef,
-        "Invalid feature ref. Expected an OCI-image-style ref like 'ghcr.io/getmonoceros/monoceros-features/<name>:<tag>'."
-      ),
-      z2.record(z2.string(), FeatureOptionValueSchema)
-    ).optional()
-  }).nullish()
-});
-async function readMonocerosConfig(opts = {}) {
-  const home = opts.monocerosHome ?? monocerosHome();
-  const filePath = monocerosConfigPath(home);
-  let text;
-  try {
-    text = await fs4.readFile(filePath, "utf8");
-  } catch {
-    return void 0;
-  }
-  const doc = parseDocument2(text, { prettyErrors: true });
-  if (doc.errors.length > 0) {
-    throw new Error(
-      `yaml parse error in ${filePath}: ${doc.errors[0].message}`
-    );
-  }
-  const result = MonocerosConfigSchema.safeParse(doc.toJS());
-  if (!result.success) {
-    const issues = result.error.issues.map((issue) => {
-      const where = issue.path.length > 0 ? issue.path.join(".") : "(root)";
-      return `  - ${where}: ${issue.message}`;
-    }).join("\n");
-    throw new Error(
-      `Invalid ${filePath}:
-${issues}
-
-See ${filePath.replace(
-        /\.yml$/,
-        ".sample.yml"
-      )} for a valid example.`
-    );
+import { consola as consola8 } from "consola";
+var addServiceCommand = defineCommand7({
+  meta: {
+    name: "add-service",
+    group: "edit",
+    description: "Add a compose service (postgres, mysql, redis, \u2026) to the container config. Idempotent, prints a diff before writing."
+  },
+  args: {
+    name: {
+      type: "positional",
+      description: "Container name (yml in $MONOCEROS_HOME/container-configs/).",
+      required: true
+    },
+    service: {
+      type: "positional",
+      description: "Service identifier (postgres, mysql, redis).",
+      required: true
+    },
+    yes: {
+      type: "boolean",
+      description: "Skip the interactive confirmation and apply the diff.",
+      alias: ["y"],
+      default: false
+    }
+  },
+  async run({ args }) {
+    try {
+      const result = await runAddService({
+        name: args.name,
+        service: args.service,
+        yes: args.yes
+      });
+      process.exit(result.status === "aborted" ? 1 : 0);
+    } catch (err) {
+      consola8.error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
   }
-  return result.data;
-}
+});
+
+// src/commands/apply.ts
+import { defineCommand as defineCommand8 } from "citty";
+
+// src/apply/index.ts
+import { existsSync as existsSync4, promises as fs10 } from "fs";
+import { consola as consola11 } from "consola";
 
 // src/config/state.ts
-import { promises as fs5 } from "fs";
-import path3 from "path";
+import { promises as fs7 } from "fs";
+import path5 from "path";
 function buildStateFile(opts) {
   return {
     schemaVersion: CONFIG_SCHEMA_VERSION,
@@ -1905,20 +2467,20 @@ function buildStateFile(opts) {
   };
 }
 function stateFilePath(targetDir) {
-  return path3.join(targetDir, ".monoceros", "state.json");
+  return path5.join(targetDir, ".monoceros", "state.json");
 }
 async function readStateFile(targetDir) {
   try {
-    const content = await fs5.readFile(stateFilePath(targetDir), "utf8");
+    const content = await fs7.readFile(stateFilePath(targetDir), "utf8");
     return JSON.parse(content);
   } catch {
     return void 0;
   }
 }
 async function writeStateFile(targetDir, state) {
-  const monocerosDir = path3.join(targetDir, ".monoceros");
-  await fs5.mkdir(monocerosDir, { recursive: true });
-  await fs5.writeFile(
+  const monocerosDir = path5.join(targetDir, ".monoceros");
+  await fs7.mkdir(monocerosDir, { recursive: true });
+  await fs7.writeFile(
     stateFilePath(targetDir),
     JSON.stringify(state, null, 2) + "\n"
   );
@@ -1960,6 +2522,21 @@ function solutionConfigToCreateOptions(config, featureDefaults = {}) {
       ...r.provider ? { provider: r.provider } : {}
     }));
   }
+  const routingPorts = config.routing?.ports ?? [];
+  if (routingPorts.length > 0) {
+    const seen = /* @__PURE__ */ new Set();
+    const ports = [];
+    for (const entry2 of routingPorts) {
+      const n = portNumber(entry2);
+      if (seen.has(n)) continue;
+      seen.add(n);
+      ports.push(n);
+    }
+    result.ports = ports;
+  }
+  if (config.routing?.vscodeAutoForward !== void 0) {
+    result.vscodeAutoForward = config.routing.vscodeAutoForward;
+  }
   return result;
 }
 
@@ -1994,10 +2571,10 @@ var dim = stderrPalette.dim;
 var sectionLine = stderrPalette.sectionLine;
 
 // src/devcontainer/compose.ts
-import { spawn as spawn2 } from "child_process";
+import { spawn as spawn3 } from "child_process";
 import { existsSync as existsSync3 } from "fs";
-import path5 from "path";
-import { consola as consola8 } from "consola";
+import path7 from "path";
+import { consola as consola9 } from "consola";
 
 // src/util/mask-secrets.ts
 import { Transform } from "stream";
@@ -2056,10 +2633,10 @@ function createSecretMaskStream() {
 }
 
 // src/devcontainer/cli.ts
-import { spawn } from "child_process";
+import { spawn as spawn2 } from "child_process";
 import { readFileSync as readFileSync2 } from "fs";
 import { createRequire } from "module";
-import path4 from "path";
+import path6 from "path";
 var require_ = createRequire(import.meta.url);
 var cachedBinaryPath = null;
 function devcontainerCliPath() {
@@ -2070,14 +2647,14 @@ function devcontainerCliPath() {
   if (!binEntry) {
     throw new Error("Could not resolve @devcontainers/cli bin entry.");
   }
-  cachedBinaryPath = path4.resolve(path4.dirname(pkgJsonPath), binEntry);
+  cachedBinaryPath = path6.resolve(path6.dirname(pkgJsonPath), binEntry);
   return cachedBinaryPath;
 }
 var spawnDevcontainer = (args, cwd, options = {}) => {
   const binPath = devcontainerCliPath();
   return new Promise((resolve, reject) => {
     if (options.interactive) {
-      const child2 = spawn(process.execPath, [binPath, ...args], {
+      const child2 = spawn2(process.execPath, [binPath, ...args], {
         cwd,
         stdio: "inherit"
       });
@@ -2085,7 +2662,7 @@ var spawnDevcontainer = (args, cwd, options = {}) => {
       child2.on("exit", (code) => resolve(code ?? 0));
       return;
     }
-    const child = spawn(process.execPath, [binPath, ...args], {
+    const child = spawn2(process.execPath, [binPath, ...args], {
       cwd,
       stdio: ["ignore", "pipe", "pipe"]
     });
@@ -2119,7 +2696,7 @@ var spawnDevcontainer = (args, cwd, options = {}) => {
 // src/devcontainer/compose.ts
 var spawnDockerCompose = (args, cwd) => {
   return new Promise((resolve, reject) => {
-    const child = spawn2("docker", ["compose", ...args], {
+    const child = spawn3("docker", ["compose", ...args], {
       cwd,
       stdio: ["inherit", "pipe", "pipe"]
     });
@@ -2131,7 +2708,7 @@ var spawnDockerCompose = (args, cwd) => {
 };
 var spawnBash = (args, cwd) => {
   return new Promise((resolve, reject) => {
-    const child = spawn2("bash", args, {
+    const child = spawn3("bash", args, {
       cwd,
       stdio: ["inherit", "pipe", "pipe"]
     });
@@ -2142,15 +2719,15 @@ var spawnBash = (args, cwd) => {
   });
 };
 function composeProjectName(root) {
-  return `${path5.basename(root)}_devcontainer`;
+  return `${path7.basename(root)}_devcontainer`;
 }
 function resolveCompose(root) {
-  if (!existsSync3(path5.join(root, ".devcontainer"))) {
+  if (!existsSync3(path7.join(root, ".devcontainer"))) {
     throw new Error(
       `No .devcontainer/ at ${root}. Run \`monoceros apply <name>\` first.`
     );
   }
-  const composeFile = path5.join(root, ".devcontainer", "compose.yaml");
+  const composeFile = path7.join(root, ".devcontainer", "compose.yaml");
   if (!existsSync3(composeFile)) {
     throw new Error(
       `No compose.yaml at ${composeFile}. \`start\` / \`stop\` / \`status\` / \`logs\` require services configured via \`monoceros add-service <name> <svc>\`. Use \`monoceros shell <name>\` to enter the container directly.`
@@ -2166,7 +2743,7 @@ async function runComposeAction(buildSubArgs, opts) {
 }
 async function runStart(opts) {
   resolveCompose(opts.root);
-  const logger = opts.logger ?? { info: (msg) => consola8.info(msg) };
+  const logger = opts.logger ?? { info: (msg) => consola9.info(msg) };
   const spawnFn = opts.spawn ?? spawnDevcontainer;
   logger.info(`Bringing devcontainer up at ${opts.root}\u2026`);
   return spawnFn(
@@ -2241,12 +2818,12 @@ function runLogs(opts) {
 }
 
 // src/devcontainer/credentials.ts
-import { spawn as spawn3 } from "child_process";
-import { promises as fs6 } from "fs";
-import path6 from "path";
+import { spawn as spawn4 } from "child_process";
+import { promises as fs8 } from "fs";
+import path8 from "path";
 var realGitCredentialFill = (input) => {
   return new Promise((resolve, reject) => {
-    const child = spawn3("git", ["credential", "fill"], {
+    const child = spawn4("git", ["credential", "fill"], {
       stdio: ["pipe", "pipe", "inherit"],
       env: {
         ...process.env,
@@ -2414,8 +2991,8 @@ function formatCredentialLine(host, username, password) {
   return `https://${encUser}:${encPass}@${host}`;
 }
 async function collectGitCredentials(devContainerRoot, hosts, options = {}) {
-  const credsDir = path6.join(devContainerRoot, ".monoceros");
-  const credentialsPath = path6.join(credsDir, "git-credentials");
+  const credsDir = path8.join(devContainerRoot, ".monoceros");
+  const credentialsPath = path8.join(credsDir, "git-credentials");
   const spawnFn = options.spawn ?? realGitCredentialFill;
   const logger = options.logger ?? { info: () => {
   }, warn: () => {
@@ -2468,8 +3045,8 @@ host=${host}
     lines.push(formatCredentialLine(host, username, password));
     perHost.push({ host, provider, status: "ok", detail: "" });
   }
-  await fs6.mkdir(credsDir, { recursive: true });
-  await fs6.writeFile(
+  await fs8.mkdir(credsDir, { recursive: true });
+  await fs8.writeFile(
     credentialsPath,
     lines.join("\n") + (lines.length > 0 ? "\n" : ""),
     {
@@ -2528,10 +3105,10 @@ function formatUnknownProviderError(hosts) {
 }
 
 // src/devcontainer/repo-reachability.ts
-import { spawn as spawn4 } from "child_process";
+import { spawn as spawn5 } from "child_process";
 var realGitLsRemote = (url) => {
   return new Promise((resolve, reject) => {
-    const child = spawn4("git", ["ls-remote", "--heads", "--", url], {
+    const child = spawn5("git", ["ls-remote", "--heads", "--", url], {
       stdio: ["ignore", "pipe", "pipe"],
       env: {
         ...process.env,
@@ -2669,10 +3246,10 @@ function adviceForKind(kind) {
 }
 
 // src/devcontainer/docker-mode.ts
-import { spawn as spawn5 } from "child_process";
+import { spawn as spawn6 } from "child_process";
 var realDockerInfo = () => {
   return new Promise((resolve, reject) => {
-    const child = spawn5(
+    const child = spawn6(
       "docker",
       ["info", "--format", "{{json .SecurityOptions}}"],
       {
@@ -2711,28 +3288,34 @@ function formatRootlessNotSupportedError() {
     ``,
     `To fix, switch back to standard rootful Docker:`,
     ``,
-    cyan2(`  systemctl --user disable --now docker.service docker.socket`),
+    cyan2(
+      `  systemctl --user stop docker.service docker.socket 2>/dev/null || true`
+    ),
     cyan2(`  dockerd-rootless-setuptool.sh uninstall`),
-    cyan2(`  rm -rf ~/.local/share/docker`),
-    cyan2(`  unset DOCKER_HOST`),
+    cyan2(`  rootlesskit rm -rf ~/.local/share/docker`),
+    cyan2(`  unset DOCKER_HOST DOCKER_CONTEXT`),
     cyan2(`  sudo systemctl enable --now docker`),
     cyan2(`  sudo usermod -aG docker $USER`),
     ``,
-    `Verify with ${cyan2("docker info | grep -i rootless")} \u2014 it should`,
-    `produce no output. Then re-run.`,
+    `If you added DOCKER_HOST or DOCKER_CONTEXT to ~/.bashrc /`,
+    `~/.profile (the rootless setup may have suggested it), remove`,
+    `those lines too \u2014 the 'unset' above only affects your current`,
+    `shell. Otherwise new terminals keep pointing at the rootless`,
+    `socket and Monoceros's auto-recovery has nothing to fall back to.`,
     ``,
-    `Background: see ${cyan2("docs/docker-on-linux.md")} in the workbench repo.`
+    `Then re-run. Background: see ${cyan2("docs/docker-on-linux.md")} in`,
+    `the workbench repo.`
   ].join("\n");
 }
 
 // src/devcontainer/identity.ts
-import { spawn as spawn6 } from "child_process";
-import { promises as fs7 } from "fs";
-import path7 from "path";
-import { consola as consola9 } from "consola";
+import { spawn as spawn7 } from "child_process";
+import { promises as fs9 } from "fs";
+import path9 from "path";
+import { consola as consola10 } from "consola";
 var realGitConfigGet = (key) => {
   return new Promise((resolve, reject) => {
-    const child = spawn6("git", ["config", "--global", "--get", key], {
+    const child = spawn7("git", ["config", "--global", "--get", key], {
       stdio: ["ignore", "pipe", "inherit"]
     });
     let stdout = "";
@@ -2751,14 +3334,14 @@ var realIdentityPrompt = async (key) => {
     return void 0;
   }
   const label = key === "user.name" ? "Git user.name for this dev container (full name)" : "Git user.email for this dev container";
-  const value = await consola9.prompt(`${label}:`, { type: "text" });
+  const value = await consola10.prompt(`${label}:`, { type: "text" });
   if (typeof value !== "string") return void 0;
   const trimmed = value.trim();
   return trimmed.length > 0 ? trimmed : void 0;
 };
 async function collectGitIdentity(devContainerRoot, options = {}) {
-  const gitconfigDir = path7.join(devContainerRoot, ".monoceros");
-  const gitconfigPath = path7.join(gitconfigDir, "gitconfig");
+  const gitconfigDir = path9.join(devContainerRoot, ".monoceros");
+  const gitconfigPath = path9.join(gitconfigDir, "gitconfig");
   const spawnFn = options.spawn ?? realGitConfigGet;
   const promptFn = options.prompt ?? realIdentityPrompt;
   const logger = options.logger ?? { info: () => {
@@ -2784,8 +3367,8 @@ async function collectGitIdentity(devContainerRoot, options = {}) {
   const lines = ["[user]"];
   if (name !== void 0) lines.push(`	name = ${name}`);
   if (email !== void 0) lines.push(`	email = ${email}`);
-  await fs7.mkdir(gitconfigDir, { recursive: true });
-  await fs7.writeFile(gitconfigPath, lines.join("\n") + "\n");
+  await fs9.mkdir(gitconfigDir, { recursive: true });
+  await fs9.writeFile(gitconfigPath, lines.join("\n") + "\n");
   return {
     ...name !== void 0 ? { name } : {},
     ...email !== void 0 ? { email } : {},
@@ -2827,7 +3410,7 @@ async function readKeyFromHost(spawnFn, key, logger) {
 }
 async function readExistingGitconfig(filePath) {
   try {
-    const content = await fs7.readFile(filePath, "utf8");
+    const content = await fs9.readFile(filePath, "utf8");
     const result = {};
     const nameMatch = /^\s*name\s*=\s*(.+?)\s*$/m.exec(content);
     const emailMatch = /^\s*email\s*=\s*(.+?)\s*$/m.exec(content);
@@ -2843,9 +3426,9 @@ async function readExistingGitconfig(filePath) {
 async function runApply(opts) {
   const home = opts.monocerosHome ?? monocerosHome();
   const logger = opts.logger ?? {
-    info: (msg) => consola10.info(msg),
-    success: (msg) => consola10.success(msg),
-    warn: (msg) => consola10.warn(msg),
+    info: (msg) => consola11.info(msg),
+    success: (msg) => consola11.success(msg),
+    warn: (msg) => consola11.warn(msg),
     // Default section renderer: empty line, bold-underlined "▸ Label",
     // empty line. Mirrors install.sh's section visuals.
     section: (label) => process.stderr.write(`
@@ -2927,7 +3510,7 @@ ${sectionLine(label)}
   if (dockerMode === "rootless") {
     throw new Error(formatRootlessNotSupportedError());
   }
-  await fs8.mkdir(targetDir, { recursive: true });
+  await fs10.mkdir(targetDir, { recursive: true });
   await writeScaffold(createOpts, targetDir, { dockerMode });
   await writeStateFile(
     targetDir,
@@ -2948,6 +3531,30 @@ ${sectionLine(label)}
       'Pulling runtime image and building feature layers. First apply takes ~1\u20132 min (Docker downloads the multi-arch base); subsequent applies are cached and fast. devcontainer-cli may log a "No manifest found" line \u2014 harmless, the pull continues.'
     )
   );
+  const ports = createOpts.ports ?? [];
+  const hasPorts = ports.length > 0;
+  if (hasPorts) {
+    await preflightHostPort(proxyHostPort(globalConfig), {
+      ...opts.proxyDocker ? { docker: opts.proxyDocker } : {}
+    });
+  }
+  try {
+    if (hasPorts) {
+      await writeDynamicConfig(opts.name, ports, { monocerosHome: home });
+      await ensureProxy({
+        ...opts.proxyDocker ? { docker: opts.proxyDocker } : {},
+        monocerosHome: home,
+        hostPort: proxyHostPort(globalConfig),
+        logger
+      });
+    } else {
+      await removeDynamicConfig(opts.name, { monocerosHome: home });
+    }
+  } catch (err) {
+    logger.warn?.(
+      `Could not sync Traefik routes: ${err instanceof Error ? err.message : String(err)}. The container will start, but \`<name>.localhost\` routing may not work until the next \`monoceros apply\`.`
+    );
+  }
   const exitCode = await runContainerCycle(targetDir, {
     hasCompose: needsCompose(createOpts),
     ...opts.cleanupSpawn !== void 0 ? { cleanupSpawn: opts.cleanupSpawn } : {},
@@ -2962,7 +3569,7 @@ ${sectionLine(label)}
 }
 async function assertSafeTargetDir(targetDir, expectedOrigin) {
   if (!existsSync4(targetDir)) return;
-  const entries = await fs8.readdir(targetDir);
+  const entries = await fs10.readdir(targetDir);
   if (entries.length === 0) return;
   const state = await readStateFile(targetDir);
   if (state) {
@@ -3004,22 +3611,22 @@ function warnOnDeprecatedFeatureRefs(containerFeatures, globalConfig, logger) {
 }
 
 // src/version.ts
-var CLI_VERSION = true ? "1.6.11" : "dev";
+var CLI_VERSION = true ? "1.7.0" : "dev";
 
 // src/commands/_dispatch.ts
-import { consola as consola11 } from "consola";
+import { consola as consola12 } from "consola";
 async function dispatch(runner) {
   try {
     const exitCode = await runner();
     process.exit(exitCode);
   } catch (err) {
-    consola11.error(err instanceof Error ? err.message : String(err));
+    consola12.error(err instanceof Error ? err.message : String(err));
     process.exit(1);
   }
 }
 
 // src/commands/apply.ts
-var applyCommand = defineCommand7({
+var applyCommand = defineCommand8({
   meta: {
     name: "apply",
     group: "lifecycle",
@@ -3044,7 +3651,7 @@ var applyCommand = defineCommand7({
 });
 
 // src/commands/completion.ts
-import { defineCommand as defineCommand8 } from "citty";
+import { defineCommand as defineCommand9 } from "citty";
 var ALL_COMMANDS = [
   "init",
   "list-components",
@@ -3063,12 +3670,15 @@ var ALL_COMMANDS = [
   "add-feature",
   "add-from-url",
   "add-repo",
+  "add-port",
   "remove-service",
   "remove-language",
   "remove-apt-packages",
   "remove-feature",
   "remove-from-url",
   "remove-repo",
+  "remove-port",
+  "port",
   "completion"
 ];
 var COMMANDS_WITH_CONTAINER_ARG = [
@@ -3086,12 +3696,15 @@ var COMMANDS_WITH_CONTAINER_ARG = [
   "add-feature",
   "add-from-url",
   "add-repo",
+  "add-port",
   "remove-service",
   "remove-language",
   "remove-apt-packages",
   "remove-feature",
   "remove-from-url",
-  "remove-repo"
+  "remove-repo",
+  "remove-port",
+  "port"
 ];
 var SHELLS = ["bash", "zsh", "pwsh"];
 function renderCompletionScript(shell) {
@@ -3224,7 +3837,7 @@ function renderCompletionScript(shell) {
     ""
   ].join("\n");
 }
-var completionCommand = defineCommand8({
+var completionCommand = defineCommand9({
   meta: {
     name: "completion",
     group: "tooling",
@@ -3251,16 +3864,16 @@ var completionCommand = defineCommand8({
 });
 
 // src/commands/init.ts
-import { defineCommand as defineCommand9 } from "citty";
-import { consola as consola13 } from "consola";
+import { defineCommand as defineCommand10 } from "citty";
+import { consola as consola14 } from "consola";
 
 // src/init/index.ts
-import { existsSync as existsSync7, promises as fs10 } from "fs";
-import { consola as consola12 } from "consola";
+import { existsSync as existsSync7, promises as fs12 } from "fs";
+import { consola as consola13 } from "consola";
 
 // src/init/components.ts
-import { existsSync as existsSync5, promises as fs9 } from "fs";
-import path8 from "path";
+import { existsSync as existsSync5, promises as fs11 } from "fs";
+import path10 from "path";
 import { z as z3 } from "zod";
 import { parse as parseYaml } from "yaml";
 var CategorySchema = z3.enum(["language", "service", "feature"]);
@@ -3315,17 +3928,17 @@ async function loadComponentCatalog(rootDir = componentsDir()) {
   return out;
 }
 async function walk(baseDir, currentDir, out) {
-  const entries = await fs9.readdir(currentDir, { withFileTypes: true });
+  const entries = await fs11.readdir(currentDir, { withFileTypes: true });
   for (const entry2 of entries) {
-    const full = path8.join(currentDir, entry2.name);
+    const full = path10.join(currentDir, entry2.name);
     if (entry2.isDirectory()) {
       await walk(baseDir, full, out);
       continue;
     }
     if (!entry2.isFile() || !entry2.name.endsWith(".yml")) continue;
-    const relative = path8.relative(baseDir, full);
-    const name = relative.replace(/\.yml$/, "").split(path8.sep).join("/");
-    const text = await fs9.readFile(full, "utf8");
+    const relative = path10.relative(baseDir, full);
+    const name = relative.replace(/\.yml$/, "").split(path10.sep).join("/");
+    const text = await fs11.readFile(full, "utf8");
     let raw;
     try {
       raw = parseYaml(text);
@@ -3581,6 +4194,7 @@ function generateDocumentedYml(name, catalog, lookupManifest, repoUrls = []) {
     /* commented */
     repoUrls.length === 0
   );
+  renderRoutingBlock(lines);
   return ensureTrailingNewline(lines.join("\n"));
 }
 var COMMENT_WIDTH = 72;
@@ -3680,6 +4294,31 @@ function renderReposBlock(out, urls, commented) {
   }
   out.push("");
 }
+function renderRoutingBlock(out) {
+  out.push("# Routing \u2014 expose container ports to the host through the");
+  out.push("# shared Traefik singleton. Once any port is declared the");
+  out.push("# container joins the monoceros-proxy network and the proxy");
+  out.push("# routes <name>.localhost (default port) and");
+  out.push("# <name>-<port>.localhost (explicit). `monoceros add-port`");
+  out.push("# manages the list; the block appears on first add.");
+  out.push("#");
+  out.push("# routing:");
+  out.push("#   ports:                    # internal container ports");
+  out.push(
+    "#     - 3000                  # first entry doubles as <name>.localhost"
+  );
+  out.push("#     - 5173");
+  out.push(
+    "#   vscodeAutoForward: false  # default: false. Traefik is the single"
+  );
+  out.push(
+    "#                             # source of truth \u2014 set true only if you"
+  );
+  out.push(
+    "#                             # want VS Code's port panel as primary."
+  );
+  out.push("");
+}
 function deriveDefaultPath(url) {
   let last = url;
   const slash = url.lastIndexOf("/");
@@ -3734,10 +4373,10 @@ function ensureTrailingNewline(s) {
 
 // src/init/manifest.ts
 import { existsSync as existsSync6, readFileSync as readFileSync3 } from "fs";
-import path9 from "path";
+import path11 from "path";
 function resolveManifestPath(name, checkoutRoot) {
   if (checkoutRoot) {
-    const checkoutPath = path9.join(
+    const checkoutPath = path11.join(
       checkoutRoot,
       "images",
       "features",
@@ -3746,7 +4385,7 @@ function resolveManifestPath(name, checkoutRoot) {
     );
     if (existsSync6(checkoutPath)) return checkoutPath;
   }
-  const bundlePath = path9.join(
+  const bundlePath = path11.join(
     bundledFeaturesDir(),
     name,
     "devcontainer-feature.json"
@@ -3789,8 +4428,8 @@ async function runInit(opts) {
   const workbench = opts.workbenchRoot ?? workbenchRoot();
   const home = opts.monocerosHome ?? monocerosHome();
   const logger = opts.logger ?? {
-    success: (msg) => consola12.success(msg),
-    info: (msg) => consola12.info(msg)
+    success: (msg) => consola13.success(msg),
+    info: (msg) => consola13.info(msg)
   };
   if (!REGEX.solutionName.test(opts.name)) {
     throw new Error(
@@ -3851,8 +4490,8 @@ async function runInit(opts) {
     const components = resolveComponents(catalog, requested);
     text = generateComposedYml(opts.name, components, lookup, repos);
   }
-  await fs10.mkdir(containerConfigsDir(home), { recursive: true });
-  await fs10.writeFile(dest, text, "utf8");
+  await fs12.mkdir(containerConfigsDir(home), { recursive: true });
+  await fs12.writeFile(dest, text, "utf8");
   const documented = requested.length === 0;
   const displayPath = prettyPath(dest);
   if (documented) {
@@ -3871,7 +4510,7 @@ async function runInit(opts) {
 }
 
 // src/commands/init.ts
-var initCommand = defineCommand9({
+var initCommand = defineCommand10({
   meta: {
     name: "init",
     group: "lifecycle",
@@ -3904,7 +4543,7 @@ var initCommand = defineCommand9({
         ...withRepoList.length > 0 ? { withRepo: withRepoList } : {}
       });
     } catch (err) {
-      consola13.error(err instanceof Error ? err.message : String(err));
+      consola14.error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
   }
@@ -3948,8 +4587,8 @@ function collectWithList(withArg, rawArgs) {
 }
 
 // src/commands/list-components.ts
-import { defineCommand as defineCommand10 } from "citty";
-import { consola as consola14 } from "consola";
+import { defineCommand as defineCommand11 } from "citty";
+import { consola as consola15 } from "consola";
 var CATEGORY_LABELS = {
   language: "Languages",
   service: "Services",
@@ -3960,7 +4599,7 @@ var CATEGORY_ORDER = [
   "service",
   "feature"
 ];
-var listComponentsCommand = defineCommand10({
+var listComponentsCommand = defineCommand11({
   meta: {
     name: "list-components",
     group: "discovery",
@@ -3971,7 +4610,7 @@ var listComponentsCommand = defineCommand10({
     try {
       const catalog = await loadComponentCatalog();
       if (catalog.size === 0) {
-        consola14.warn(
+        consola15.warn(
           "No components found. The workbench checkout looks incomplete."
         );
         process.exit(0);
@@ -4022,15 +4661,15 @@ var listComponentsCommand = defineCommand10({
       }
       process.exit(0);
     } catch (err) {
-      consola14.error(err instanceof Error ? err.message : String(err));
+      consola15.error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
   }
 });
 
 // src/commands/logs.ts
-import { defineCommand as defineCommand11 } from "citty";
-var logsCommand = defineCommand11({
+import { defineCommand as defineCommand12 } from "citty";
+var logsCommand = defineCommand12({
   meta: {
     name: "logs",
     group: "run",
@@ -4064,10 +4703,87 @@ var logsCommand = defineCommand11({
   }
 });
 
+// src/commands/port.ts
+import { defineCommand as defineCommand13 } from "citty";
+import { consola as consola16 } from "consola";
+async function runPortListing(opts) {
+  const out = opts.out ?? process.stdout;
+  const info = opts.info ?? ((m) => consola16.info(m));
+  const parsed = await readConfig(
+    containerConfigPath(opts.name, opts.monocerosHome)
+  );
+  const portEntries = parsed.config.routing?.ports ?? [];
+  if (portEntries.length === 0) {
+    info(
+      `No ports declared in ${opts.name}.yml. Run \`monoceros add-port ${opts.name} -- <port>\` to expose one.`
+    );
+    return 0;
+  }
+  const ports = portEntries.map(portNumber);
+  const globalConfig = await readMonocerosConfig({
+    ...opts.monocerosHome ? { monocerosHome: opts.monocerosHome } : {}
+  });
+  const hostPort = proxyHostPort(globalConfig);
+  const urls = proxyUrlsFor(opts.name, ports, hostPort);
+  const isTty2 = out.isTTY ?? false;
+  const fmt = colorsFor(out);
+  const portSuffix = hostPort === 80 ? "" : `:${hostPort}`;
+  const rows = [];
+  rows.push({
+    port: urls[0].port,
+    url: `http://${opts.name}.localhost${portSuffix}`,
+    tag: "default"
+  });
+  for (const u of urls) {
+    rows.push({ port: u.port, url: u.url, tag: "" });
+  }
+  if (!isTty2) {
+    for (const r of rows) {
+      out.write(`${r.port}	${r.url}	${r.tag}
+`);
+    }
+    return 0;
+  }
+  const portWidth = Math.max(...rows.map((r) => String(r.port).length));
+  const urlWidth = Math.max(...rows.map((r) => r.url.length));
+  const gutter = 2;
+  for (const r of rows) {
+    const portStr = String(r.port).padStart(portWidth);
+    const urlPad = " ".repeat(urlWidth - r.url.length + gutter);
+    const tag = r.tag ? fmt.dim(`(${r.tag})`) : "";
+    out.write(`  ${fmt.cyan(portStr)}  \u2192  ${r.url}${urlPad}${tag}
+`);
+  }
+  return 0;
+}
+var portCommand = defineCommand13({
+  meta: {
+    name: "port",
+    group: "discovery",
+    description: "List the Traefik URLs for a container. Reads ports from `routing.ports` in the container yml and the host port from `routing.hostPort` in monoceros-config.yml (default 80). When piped, drops formatting and emits `port<TAB>url<TAB>tag` per line for grep/awk consumption."
+  },
+  args: {
+    name: {
+      type: "positional",
+      description: "Container name (yml in $MONOCEROS_HOME/container-configs/).",
+      required: true
+    }
+  },
+  async run({ args }) {
+    try {
+      const code = await runPortListing({ name: args.name });
+      process.exit(code);
+    } catch (err) {
+      consola16.error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  }
+});
+
 // src/commands/remove-apt-packages.ts
-import { defineCommand as defineCommand12 } from "citty";
-import { consola as consola15 } from "consola";
-var removeAptPackagesCommand = defineCommand12({
+import { defineCommand as defineCommand14 } from "citty";
+import { consola as consola17 } from "consola";
+var removeAptPackagesCommand = defineCommand14({
   meta: {
     name: "remove-apt-packages",
     group: "edit",
@@ -4089,7 +4805,7 @@ var removeAptPackagesCommand = defineCommand12({
   async run({ args }) {
     const packages = [...getInnerArgs()];
     if (packages.length === 0) {
-      consola15.error(
+      consola17.error(
         "No package names given. Usage: `monoceros remove-apt-packages <containername> [--yes] -- <pkg> [<pkg> \u2026]`."
       );
       process.exit(1);
@@ -4102,16 +4818,16 @@ var removeAptPackagesCommand = defineCommand12({
       });
       process.exit(result.status === "aborted" ? 1 : 0);
     } catch (err) {
-      consola15.error(err instanceof Error ? err.message : String(err));
+      consola17.error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
   }
 });
 
 // src/commands/remove-feature.ts
-import { defineCommand as defineCommand13 } from "citty";
-import { consola as consola16 } from "consola";
-var removeFeatureCommand = defineCommand13({
+import { defineCommand as defineCommand15 } from "citty";
+import { consola as consola18 } from "consola";
+var removeFeatureCommand = defineCommand15({
   meta: {
     name: "remove-feature",
     group: "edit",
@@ -4144,27 +4860,27 @@ var removeFeatureCommand = defineCommand13({
       });
       process.exit(result.status === "aborted" ? 1 : 0);
     } catch (err) {
-      consola16.error(err instanceof Error ? err.message : String(err));
+      consola18.error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
   }
 });
 
 // src/commands/remove.ts
-import { defineCommand as defineCommand14 } from "citty";
-import { consola as consola18 } from "consola";
+import { defineCommand as defineCommand16 } from "citty";
+import { consola as consola20 } from "consola";
 import { createInterface } from "readline/promises";
 
 // src/remove/index.ts
-import { existsSync as existsSync8, promises as fs11 } from "fs";
-import path10 from "path";
-import { consola as consola17 } from "consola";
+import { existsSync as existsSync8, promises as fs13 } from "fs";
+import path12 from "path";
+import { consola as consola19 } from "consola";
 async function runRemove(opts) {
   const home = opts.monocerosHome ?? monocerosHome();
   const logger = opts.logger ?? {
-    info: (msg) => consola17.info(msg),
-    success: (msg) => consola17.success(msg),
-    warn: (msg) => consola17.warn(msg)
+    info: (msg) => consola19.info(msg),
+    success: (msg) => consola19.success(msg),
+    warn: (msg) => consola19.warn(msg)
   };
   if (!REGEX.solutionName.test(opts.name)) {
     throw new Error(
@@ -4208,23 +4924,23 @@ async function runRemove(opts) {
   let backupPath = null;
   if (!opts.noBackup && (hasYml || hasContainer)) {
     const ts = (opts.now ?? /* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-    backupPath = path10.join(home, "container-backups", `${opts.name}-${ts}`);
-    await fs11.mkdir(backupPath, { recursive: true });
+    backupPath = path12.join(home, "container-backups", `${opts.name}-${ts}`);
+    await fs13.mkdir(backupPath, { recursive: true });
     if (hasYml) {
-      await fs11.copyFile(ymlPath, path10.join(backupPath, `${opts.name}.yml`));
+      await fs13.copyFile(ymlPath, path12.join(backupPath, `${opts.name}.yml`));
     }
     if (hasContainer) {
-      await fs11.cp(containerPath, path10.join(backupPath, "container"), {
+      await fs13.cp(containerPath, path12.join(backupPath, "container"), {
         recursive: true
       });
     }
     logger.info(`Backup written to ${prettyPath(backupPath)}.`);
   }
   if (hasYml) {
-    await fs11.rm(ymlPath, { force: true });
+    await fs13.rm(ymlPath, { force: true });
   }
   if (hasContainer) {
-    await fs11.rm(containerPath, { recursive: true, force: true });
+    await fs13.rm(containerPath, { recursive: true, force: true });
   }
   logger.success(
     `Removed '${opts.name}': docker objects gone, container-configs entry deleted, container directory deleted.`
@@ -4234,6 +4950,24 @@ async function runRemove(opts) {
       "No backup created (--no-backup). The host-side state is gone for good."
     );
   }
+  try {
+    await removeDynamicConfig(opts.name, { monocerosHome: home });
+  } catch (err) {
+    logger.warn?.(
+      `Could not remove Traefik dynamic config for ${opts.name}: ${err instanceof Error ? err.message : String(err)}. Ignored.`
+    );
+  }
+  try {
+    await maybeStopProxy({
+      ...opts.proxyDocker ? { docker: opts.proxyDocker } : {},
+      monocerosHome: home,
+      logger: { info: (msg) => logger.info(msg), warn: logger.warn }
+    });
+  } catch (err) {
+    logger.warn?.(
+      `Could not tear down the Traefik proxy: ${err instanceof Error ? err.message : String(err)}. Ignored.`
+    );
+  }
   return {
     configPath: hasYml ? ymlPath : null,
     containerPath: hasContainer ? containerPath : null,
@@ -4243,7 +4977,7 @@ async function runRemove(opts) {
 }
 
 // src/commands/remove.ts
-var removeCommand = defineCommand14({
+var removeCommand = defineCommand16({
   meta: {
     name: "remove",
     group: "lifecycle",
@@ -4280,7 +5014,7 @@ var removeCommand = defineCommand14({
       const skipPrompt = args.yes === true;
       if (!skipPrompt) {
         const warning = noBackup ? `About to remove '${args.name}' WITHOUT a backup. Docker objects, container-configs entry, and container directory will all be deleted.` : `About to remove '${args.name}'. A backup will be written to container-backups/ first, then docker objects, container-configs entry, and container directory will all be deleted.`;
-        consola18.warn(warning);
+        consola20.warn(warning);
         const rl = createInterface({
           input: process.stdin,
           output: process.stdout
@@ -4288,7 +5022,7 @@ var removeCommand = defineCommand14({
         const answer = await rl.question("Continue? [y/N] ");
         rl.close();
         if (!/^y(es)?$/i.test(answer.trim())) {
-          consola18.info("Aborted. Nothing changed.");
+          consola20.info("Aborted. Nothing changed.");
           process.exit(0);
         }
       }
@@ -4297,35 +5031,35 @@ var removeCommand = defineCommand14({
         ...noBackup ? { noBackup: true } : {}
       });
     } catch (err) {
-      consola18.error(err instanceof Error ? err.message : String(err));
+      consola20.error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
   }
 });
 
 // src/commands/restore.ts
-import { defineCommand as defineCommand15 } from "citty";
-import { consola as consola20 } from "consola";
+import { defineCommand as defineCommand17 } from "citty";
+import { consola as consola22 } from "consola";
 
 // src/restore/index.ts
-import { existsSync as existsSync9, promises as fs12 } from "fs";
-import path11 from "path";
-import { consola as consola19 } from "consola";
+import { existsSync as existsSync9, promises as fs14 } from "fs";
+import path13 from "path";
+import { consola as consola21 } from "consola";
 async function runRestore(opts) {
   const home = opts.monocerosHome ?? monocerosHome();
   const logger = opts.logger ?? {
-    info: (msg) => consola19.info(msg),
-    success: (msg) => consola19.success(msg)
+    info: (msg) => consola21.info(msg),
+    success: (msg) => consola21.success(msg)
   };
-  const backup = path11.resolve(opts.backupPath);
+  const backup = path13.resolve(opts.backupPath);
   if (!existsSync9(backup)) {
     throw new Error(`Backup not found: ${backup}.`);
   }
-  const stat = await fs12.stat(backup);
+  const stat = await fs14.stat(backup);
   if (!stat.isDirectory()) {
     throw new Error(`Backup path is not a directory: ${backup}.`);
   }
-  const entries = await fs12.readdir(backup);
+  const entries = await fs14.readdir(backup);
   const ymlFiles = entries.filter((f) => f.endsWith(".yml"));
   if (ymlFiles.length === 0) {
     throw new Error(
@@ -4339,7 +5073,7 @@ async function runRestore(opts) {
   }
   const ymlFile = ymlFiles[0];
   const name = ymlFile.replace(/\.yml$/, "");
-  const containerInBackup = path11.join(backup, "container");
+  const containerInBackup = path13.join(backup, "container");
   const hasContainer = existsSync9(containerInBackup);
   const destYml = containerConfigPath(name, home);
   const destContainer = containerDir(name, home);
@@ -4353,10 +5087,10 @@ async function runRestore(opts) {
       `Refusing to restore: ${destContainer} already exists. Remove the current container first (\`monoceros remove ${name}\`).`
     );
   }
-  await fs12.mkdir(containerConfigsDir(home), { recursive: true });
-  await fs12.copyFile(path11.join(backup, ymlFile), destYml);
+  await fs14.mkdir(containerConfigsDir(home), { recursive: true });
+  await fs14.copyFile(path13.join(backup, ymlFile), destYml);
   if (hasContainer) {
-    await fs12.cp(containerInBackup, destContainer, { recursive: true });
+    await fs14.cp(containerInBackup, destContainer, { recursive: true });
   }
   logger.success(`Restored '${name}' from ${prettyPath(backup)}.`);
   logger.info(
@@ -4370,7 +5104,7 @@ async function runRestore(opts) {
 }
 
 // src/commands/restore.ts
-var restoreCommand = defineCommand15({
+var restoreCommand = defineCommand17({
   meta: {
     name: "restore",
     group: "lifecycle",
@@ -4387,16 +5121,16 @@ var restoreCommand = defineCommand15({
     try {
       await runRestore({ backupPath: args["backup-path"] });
     } catch (err) {
-      consola20.error(err instanceof Error ? err.message : String(err));
+      consola22.error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
   }
 });
 
 // src/commands/remove-from-url.ts
-import { defineCommand as defineCommand16 } from "citty";
-import { consola as consola21 } from "consola";
-var removeFromUrlCommand = defineCommand16({
+import { defineCommand as defineCommand18 } from "citty";
+import { consola as consola23 } from "consola";
+var removeFromUrlCommand = defineCommand18({
   meta: {
     name: "remove-from-url",
     group: "edit",
@@ -4429,16 +5163,16 @@ var removeFromUrlCommand = defineCommand16({
       });
       process.exit(result.status === "aborted" ? 1 : 0);
     } catch (err) {
-      consola21.error(err instanceof Error ? err.message : String(err));
+      consola23.error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
   }
 });
 
 // src/commands/remove-language.ts
-import { defineCommand as defineCommand17 } from "citty";
-import { consola as consola22 } from "consola";
-var removeLanguageCommand = defineCommand17({
+import { defineCommand as defineCommand19 } from "citty";
+import { consola as consola24 } from "consola";
+var removeLanguageCommand = defineCommand19({
   meta: {
     name: "remove-language",
     group: "edit",
@@ -4471,16 +5205,64 @@ var removeLanguageCommand = defineCommand17({
       });
       process.exit(result.status === "aborted" ? 1 : 0);
     } catch (err) {
-      consola22.error(err instanceof Error ? err.message : String(err));
+      consola24.error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  }
+});
+
+// src/commands/remove-port.ts
+import { defineCommand as defineCommand20 } from "citty";
+import { consola as consola25 } from "consola";
+var removePortCommand = defineCommand20({
+  meta: {
+    name: "remove-port",
+    group: "edit",
+    description: "Remove one or more ports from the container config. Pass port numbers after `--` (e.g. `monoceros remove-port sandbox -- 3000 5173`). Idempotent \u2014 ports not present are skipped silently."
+  },
+  args: {
+    name: {
+      type: "positional",
+      description: "Container name (yml in $MONOCEROS_HOME/container-configs/).",
+      required: true
+    },
+    yes: {
+      type: "boolean",
+      description: "Skip the interactive confirmation and apply the diff.",
+      alias: ["y"],
+      default: false
+    }
+  },
+  async run({ args }) {
+    const tokens = [...getInnerArgs()];
+    if (tokens.length === 0) {
+      consola25.error(
+        "No ports given. Usage: `monoceros remove-port <containername> [--yes] -- <port> [<port> \u2026]`."
+      );
+      process.exit(1);
+    }
+    try {
+      const result = await runRemovePort({
+        name: args.name,
+        ports: tokens.map(coerceToken2),
+        yes: args.yes
+      });
+      process.exit(result.status === "aborted" ? 1 : 0);
+    } catch (err) {
+      consola25.error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
   }
 });
+function coerceToken2(raw) {
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : raw;
+}
 
 // src/commands/remove-repo.ts
-import { defineCommand as defineCommand18 } from "citty";
-import { consola as consola23 } from "consola";
-var removeRepoCommand = defineCommand18({
+import { defineCommand as defineCommand21 } from "citty";
+import { consola as consola26 } from "consola";
+var removeRepoCommand = defineCommand21({
   meta: {
     name: "remove-repo",
     group: "edit",
@@ -4513,16 +5295,16 @@ var removeRepoCommand = defineCommand18({
       });
       process.exit(result.status === "aborted" ? 1 : 0);
     } catch (err) {
-      consola23.error(err instanceof Error ? err.message : String(err));
+      consola26.error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
   }
 });
 
 // src/commands/remove-service.ts
-import { defineCommand as defineCommand19 } from "citty";
-import { consola as consola24 } from "consola";
-var removeServiceCommand = defineCommand19({
+import { defineCommand as defineCommand22 } from "citty";
+import { consola as consola27 } from "consola";
+var removeServiceCommand = defineCommand22({
   meta: {
     name: "remove-service",
     group: "edit",
@@ -4555,19 +5337,19 @@ var removeServiceCommand = defineCommand19({
       });
       process.exit(result.status === "aborted" ? 1 : 0);
     } catch (err) {
-      consola24.error(err instanceof Error ? err.message : String(err));
+      consola27.error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
   }
 });
 
 // src/commands/run.ts
-import { defineCommand as defineCommand20 } from "citty";
-import { consola as consola25 } from "consola";
+import { defineCommand as defineCommand23 } from "citty";
+import { consola as consola28 } from "consola";
 
 // src/devcontainer/shell.ts
 import { existsSync as existsSync10 } from "fs";
-import path12 from "path";
+import path14 from "path";
 async function runShell(opts) {
   assertContainerExists(opts.root);
   const spawnFn = opts.spawn ?? spawnDevcontainer;
@@ -4590,7 +5372,7 @@ async function runShell(opts) {
   );
 }
 function assertContainerExists(root) {
-  if (!existsSync10(path12.join(root, ".devcontainer"))) {
+  if (!existsSync10(path14.join(root, ".devcontainer"))) {
     throw new Error(
       `No .devcontainer/ at ${root}. Run \`monoceros apply <name>\` first.`
     );
@@ -4626,7 +5408,7 @@ async function runInContainer(opts) {
 }
 
 // src/commands/run.ts
-var runCommand = defineCommand20({
+var runCommand = defineCommand23({
   meta: {
     name: "run",
     group: "run",
@@ -4642,7 +5424,7 @@ var runCommand = defineCommand20({
   async run({ args }) {
     const command = [...getInnerArgs()];
     if (command.length === 0) {
-      consola25.error(
+      consola28.error(
         "No command provided. Usage: `monoceros run <containername> -- <cmd> [args\u2026]`."
       );
       process.exit(1);
@@ -4654,16 +5436,16 @@ var runCommand = defineCommand20({
       });
       process.exit(exitCode);
     } catch (err) {
-      consola25.error(err instanceof Error ? err.message : String(err));
+      consola28.error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
   }
 });
 
 // src/commands/shell.ts
-import { defineCommand as defineCommand21 } from "citty";
-import { consola as consola26 } from "consola";
-var shellCommand = defineCommand21({
+import { defineCommand as defineCommand24 } from "citty";
+import { consola as consola29 } from "consola";
+var shellCommand = defineCommand24({
   meta: {
     name: "shell",
     group: "run",
@@ -4681,15 +5463,16 @@ var shellCommand = defineCommand21({
       const exitCode = await runShell({ root: containerDir(args.name) });
       process.exit(exitCode);
     } catch (err) {
-      consola26.error(err instanceof Error ? err.message : String(err));
+      consola29.error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
   }
 });
 
 // src/commands/start.ts
-import { defineCommand as defineCommand22 } from "citty";
-var startCommand = defineCommand22({
+import { defineCommand as defineCommand25 } from "citty";
+import { consola as consola30 } from "consola";
+var startCommand = defineCommand25({
   meta: {
     name: "start",
     group: "run",
@@ -4703,13 +5486,33 @@ var startCommand = defineCommand22({
     }
   },
   run({ args }) {
-    return dispatch(() => runStart({ root: containerDir(args.name) }));
+    return dispatch(async () => {
+      let needsProxy = false;
+      let hostPort = 80;
+      try {
+        const parsed = await readConfig(containerConfigPath(args.name));
+        if ((parsed.config.routing?.ports ?? []).length > 0) {
+          needsProxy = true;
+          const global = await readMonocerosConfig();
+          hostPort = proxyHostPort(global);
+        }
+      } catch (err) {
+        consola30.warn(
+          `Could not read container yml ahead of start: ${err instanceof Error ? err.message : String(err)}. Skipping Traefik pre-flight.`
+        );
+      }
+      if (needsProxy) {
+        await preflightHostPort(hostPort);
+        await ensureProxy({ hostPort });
+      }
+      return runStart({ root: containerDir(args.name) });
+    });
   }
 });
 
 // src/commands/status.ts
-import { defineCommand as defineCommand23 } from "citty";
-var statusCommand = defineCommand23({
+import { defineCommand as defineCommand26 } from "citty";
+var statusCommand = defineCommand26({
   meta: {
     name: "status",
     group: "run",
@@ -4737,8 +5540,9 @@ var statusCommand = defineCommand23({
 });
 
 // src/commands/stop.ts
-import { defineCommand as defineCommand24 } from "citty";
-var stopCommand = defineCommand24({
+import { defineCommand as defineCommand27 } from "citty";
+import { consola as consola31 } from "consola";
+var stopCommand = defineCommand27({
   meta: {
     name: "stop",
     group: "run",
@@ -4756,17 +5560,27 @@ var stopCommand = defineCommand24({
     }
   },
   run({ args }) {
-    return dispatch(
-      () => runStop({
+    return dispatch(async () => {
+      const exit = await runStop({
         root: containerDir(args.name),
         ...typeof args.service === "string" ? { service: args.service } : {}
-      })
-    );
+      });
+      try {
+        await maybeStopProxy({
+          logger: { info: (msg) => consola31.info(msg) }
+        });
+      } catch (err) {
+        consola31.warn(
+          `Could not tear down the Traefik proxy: ${err instanceof Error ? err.message : String(err)}. Ignored.`
+        );
+      }
+      return exit;
+    });
   }
 });
 
 // src/main.ts
-var main = defineCommand25({
+var main = defineCommand28({
   meta: {
     name: "monoceros",
     version: CLI_VERSION,
@@ -4790,12 +5604,15 @@ var main = defineCommand25({
     "add-feature": addFeatureCommand,
     "add-from-url": addFromUrlCommand,
     "add-repo": addRepoCommand,
+    "add-port": addPortCommand,
     "remove-service": removeServiceCommand,
     "remove-language": removeLanguageCommand,
     "remove-apt-packages": removeAptPackagesCommand,
     "remove-feature": removeFeatureCommand,
     "remove-from-url": removeFromUrlCommand,
     "remove-repo": removeRepoCommand,
+    "remove-port": removePortCommand,
+    port: portCommand,
     completion: completionCommand
   }
 });