diff --git a/.env.example b/.env.example
new file mode 100644
index 000000000..52eb78ee5
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,8 @@
+# NemoClaw port configuration — copy to .env and edit as needed.
+# Ports must be integers in range 1024–65535.
+# Run scripts/check-ports.sh to find port conflicts
+
+NEMOCLAW_DASHBOARD_PORT=18789
+NEMOCLAW_GATEWAY_PORT=8080
+NEMOCLAW_VLLM_PORT=8000
+NEMOCLAW_OLLAMA_PORT=11434
diff --git a/.gitignore b/.gitignore
index 5e68edf79..dde97ea46 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,3 +8,8 @@ docs/_build/
 coverage/
 vdr-notes/
 draft_newsletter_*
+tmp/
+.env
+.env.local
+.venv/
+uv.lock
diff --git a/README.md b/README.md
index 287ff0d82..b9d1f68c7 100644
--- a/README.md
+++ b/README.md
@@ -160,6 +160,36 @@ curl -fsSL https://raw.githubusercontent.com/NVIDIA/NemoClaw/refs/heads/main/uni
 
 ---
 
+## Port Configuration
+
+NemoClaw uses four network ports. All are configurable via environment variables or a `.env` file at the project root (copy `.env.example` to get started).
+
+| Port | Default | Env var | Purpose | Conflict risk |
+|------|---------|---------|---------|---------------|
+| Dashboard | 18789 | `NEMOCLAW_DASHBOARD_PORT` | OpenClaw web UI, forwarded from sandbox to host | Low |
+| Gateway | 8080 | `NEMOCLAW_GATEWAY_PORT` | OpenShell gateway signal channel | **High** — Jenkins, Tomcat, K8s dashboard |
+| vLLM/NIM | 8000 | `NEMOCLAW_VLLM_PORT` | Local vLLM or NIM inference endpoint | **High** — Django, PHP dev server |
+| Ollama | 11434 | `NEMOCLAW_OLLAMA_PORT` | Local Ollama inference endpoint | Low |
+
+To use non-default ports, set the environment variables before running `nemoclaw onboard`:
+
+```bash
+export NEMOCLAW_GATEWAY_PORT=9080
+export NEMOCLAW_VLLM_PORT=9000
+nemoclaw onboard
+```
+
+Or create a `.env` file at the project root (see `.env.example`).
+
+> **ℹ️ Note**
+>
+> Changing the dashboard port requires rebuilding the sandbox image because the CORS origin is baked in at build time. Re-run `nemoclaw onboard` after changing `NEMOCLAW_DASHBOARD_PORT`.
+
+> **⚠️ Network exposure**
+>
+> When using local inference (Ollama or vLLM), the inference service binds to `0.0.0.0` so that containers can reach it via `host.openshell.internal`. This means the service is reachable from your local network, not just localhost. This is required for the sandbox architecture but should be considered in shared or untrusted network environments.
+---
+
 ## How It Works
 
 NemoClaw installs the NVIDIA OpenShell runtime and Nemotron models, then uses a versioned blueprint to create a sandboxed environment where every network request, file access, and inference call is governed by declarative policy. The `nemoclaw` CLI orchestrates the full stack: OpenShell gateway, sandbox, inference provider, and network policy.
diff --git a/bin/lib/env.js b/bin/lib/env.js
new file mode 100644
index 000000000..c0eb54ce7
--- /dev/null
+++ b/bin/lib/env.js
@@ -0,0 +1,93 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+//
+// Lightweight .env loader — reads .env files from the project root and populates
+// process.env. Existing environment variables are never overwritten, so shell
+// exports always take precedence over file values.
+//
+// Supports:
+//   - Multiple files (loaded in order; first file's values win over later files)
+//   - Comments (#) and blank lines
+//   - KEY=VALUE, KEY="VALUE", KEY='VALUE'
+//   - Inline comments after unquoted values
+
+const fs = require("fs");
+const path = require("path");
+
+const ROOT = path.resolve(__dirname, "..", "..");
+const CWD = process.cwd();
+
+// Walk up from a directory looking for a .git marker to find the repo root.
+function findGitRoot(start) {
+  let dir = start;
+  while (true) {
+    try {
+      fs.statSync(path.join(dir, ".git"));
+      return dir;
+    } catch {
+      const parent = path.dirname(dir);
+      if (parent === dir) return null;
+      dir = parent;
+    }
+  }
+}
+
+const GIT_ROOT = findGitRoot(CWD);
+
+function parseEnvFile(filePath) {
+  let content;
+  try {
+    content = fs.readFileSync(filePath, "utf-8");
+  } catch {
+    return; // file doesn't exist or isn't readable — skip silently
+  }
+
+  for (const raw of content.split("\n")) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+
+    const eqIndex = line.indexOf("=");
+    if (eqIndex === -1) continue;
+
+    const key = line.slice(0, eqIndex).trim();
+    if (!key) continue;
+
+    let value = line.slice(eqIndex + 1).trim();
+
+    // Remove inline comments for unquoted values first, then strip quotes.
+    // This handles cases like KEY='value' # comment correctly.
+    const hashIndex = value.indexOf(" #");
+    if (hashIndex !== -1) {
+      value = value.slice(0, hashIndex).trim();
+    }
+
+    // Strip surrounding quotes
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+
+    // Never overwrite existing env vars
+    if (process.env[key] === undefined) {
+      process.env[key] = value;
+    }
+  }
+}
+
+// Collect unique directories to search for .env files.  The git repo root and
+// CWD are checked in addition to the __dirname-relative ROOT so that a user's
+// .env.local (which is gitignored and therefore not synced into the sandbox
+// source directory) is still picked up on a fresh install.
+const SEARCH_DIRS = [...new Set([ROOT, GIT_ROOT, CWD].filter(Boolean))];
+
+// Load .env files in priority order — first file wins for any given key
+// because we never overwrite once set.
+const ENV_FILES = [".env.local", ".env"];
+
+for (const file of ENV_FILES) {
+  for (const dir of SEARCH_DIRS) {
+    parseEnvFile(path.join(dir, file));
+  }
+}
diff --git a/bin/lib/local-inference.js b/bin/lib/local-inference.js
index 1065a70e3..07f266d19 100644
--- a/bin/lib/local-inference.js
+++ b/bin/lib/local-inference.js
@@ -1,6 +1,7 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+const { VLLM_PORT, OLLAMA_PORT } = require("./ports");
 const { shellQuote } = require("./runner");
 
 const HOST_GATEWAY_URL = "http://host.openshell.internal";
@@ -10,9 +11,9 @@ const DEFAULT_OLLAMA_MODEL = "nemotron-3-nano:30b";
 function getLocalProviderBaseUrl(provider) {
   switch (provider) {
     case "vllm-local":
-      return `${HOST_GATEWAY_URL}:8000/v1`;
+      return `${HOST_GATEWAY_URL}:${VLLM_PORT}/v1`;
     case "ollama-local":
-      return `${HOST_GATEWAY_URL}:11434/v1`;
+      return `${HOST_GATEWAY_URL}:${OLLAMA_PORT}/v1`;
     default:
       return null;
   }
@@ -21,9 +22,9 @@ function getLocalProviderBaseUrl(provider) {
 function getLocalProviderHealthCheck(provider) {
   switch (provider) {
     case "vllm-local":
-      return "curl -sf http://localhost:8000/v1/models 2>/dev/null";
+      return `curl -sf http://localhost:${VLLM_PORT}/v1/models 2>/dev/null`;
     case "ollama-local":
-      return "curl -sf http://localhost:11434/api/tags 2>/dev/null";
+      return `curl -sf http://localhost:${OLLAMA_PORT}/api/tags 2>/dev/null`;
     default:
       return null;
   }
@@ -32,9 +33,9 @@ function getLocalProviderHealthCheck(provider) {
 function getLocalProviderContainerReachabilityCheck(provider) {
   switch (provider) {
     case "vllm-local":
-      return `docker run --rm --add-host host.openshell.internal:host-gateway ${CONTAINER_REACHABILITY_IMAGE} -sf http://host.openshell.internal:8000/v1/models 2>/dev/null`;
+      return `docker run --rm --add-host host.openshell.internal:host-gateway ${CONTAINER_REACHABILITY_IMAGE} -sf http://host.openshell.internal:${VLLM_PORT}/v1/models 2>/dev/null`;
     case "ollama-local":
-      return `docker run --rm --add-host host.openshell.internal:host-gateway ${CONTAINER_REACHABILITY_IMAGE} -sf http://host.openshell.internal:11434/api/tags 2>/dev/null`;
+      return `docker run --rm --add-host host.openshell.internal:host-gateway ${CONTAINER_REACHABILITY_IMAGE} -sf http://host.openshell.internal:${OLLAMA_PORT}/api/tags 2>/dev/null`;
     default:
       return null;
   }
@@ -52,12 +53,12 @@ function validateLocalProvider(provider, runCapture) {
       case "vllm-local":
         return {
           ok: false,
-          message: "Local vLLM was selected, but nothing is responding on http://localhost:8000.",
+          message: `Local vLLM was selected, but nothing is responding on http://localhost:${VLLM_PORT}.`,
         };
       case "ollama-local":
         return {
           ok: false,
-          message: "Local Ollama was selected, but nothing is responding on http://localhost:11434.",
+          message: `Local Ollama was selected, but nothing is responding on http://localhost:${OLLAMA_PORT}.`,
         };
       default:
         return { ok: false, message: "The selected local inference provider is unavailable." };
@@ -79,13 +80,13 @@ function validateLocalProvider(provider, runCapture) {
       return {
         ok: false,
         message:
-          "Local vLLM is responding on localhost, but containers cannot reach http://host.openshell.internal:8000. Ensure the server is reachable from containers, not only from the host shell.",
+          `Local vLLM is responding on localhost, but containers cannot reach http://host.openshell.internal:${VLLM_PORT}. Ensure the server is reachable from containers, not only from the host shell.`,
       };
     case "ollama-local":
       return {
         ok: false,
         message:
-          "Local Ollama is responding on localhost, but containers cannot reach http://host.openshell.internal:11434. Ensure Ollama listens on 0.0.0.0:11434 instead of 127.0.0.1 so sandboxes can reach it.",
+          `Local Ollama is responding on localhost, but containers cannot reach http://host.openshell.internal:${OLLAMA_PORT}. Ensure Ollama listens on 0.0.0.0:${OLLAMA_PORT} instead of 127.0.0.1 so sandboxes can reach it.`,
       };
     default:
       return { ok: false, message: "The selected local inference provider is unavailable from containers." };
@@ -123,7 +124,7 @@ function getOllamaWarmupCommand(model, keepAlive = "15m") {
     stream: false,
     keep_alive: keepAlive,
   });
-  return `nohup curl -s http://localhost:11434/api/generate -H 'Content-Type: application/json' -d ${shellQuote(payload)} >/dev/null 2>&1 &`;
+  return `nohup curl -s http://localhost:${OLLAMA_PORT}/api/generate -H 'Content-Type: application/json' -d ${shellQuote(payload)} >/dev/null 2>&1 &`;
 }
 
 function getOllamaProbeCommand(model, timeoutSeconds = 120, keepAlive = "15m") {
@@ -133,7 +134,7 @@ function getOllamaProbeCommand(model, timeoutSeconds = 120, keepAlive = "15m") {
     stream: false,
     keep_alive: keepAlive,
   });
-  return `curl -sS --max-time ${timeoutSeconds} http://localhost:11434/api/generate -H 'Content-Type: application/json' -d ${shellQuote(payload)} 2>/dev/null`;
+  return `curl -sS --max-time ${timeoutSeconds} http://localhost:${OLLAMA_PORT}/api/generate -H 'Content-Type: application/json' -d ${shellQuote(payload)} 2>/dev/null`;
 }
 
 function validateOllamaModel(model, runCapture) {
diff --git a/bin/lib/nim.js b/bin/lib/nim.js
index 548b2db23..ec0e4bd27 100644
--- a/bin/lib/nim.js
+++ b/bin/lib/nim.js
@@ -4,6 +4,7 @@
 // NIM container management — pull, start, stop, health-check NIM images.
 
 const { run, runCapture, shellQuote } = require("./runner");
+const { VLLM_PORT } = require("./ports");
 const nimImages = require("./nim-images.json");
 
 function containerName(sandboxName) {
@@ -125,7 +126,7 @@ function pullNimImage(model) {
   return image;
 }
 
-function startNimContainer(sandboxName, model, port = 8000) {
+function startNimContainer(sandboxName, model, port = VLLM_PORT) {
   const name = containerName(sandboxName);
   const image = getImageForModel(model);
   if (!image) {
@@ -139,12 +140,13 @@ function startNimContainer(sandboxName, model, port = 8000) {
 
   console.log(`  Starting NIM container: ${name}`);
   run(
+    // Right-hand :8000 is the NIM image's internal port — fixed by the image, not configurable.
     `docker run -d --gpus all -p ${Number(port)}:8000 --name ${qn} --shm-size 16g ${shellQuote(image)}`
   );
   return name;
 }
 
-function waitForNimHealth(port = 8000, timeout = 300) {
+function waitForNimHealth(port = VLLM_PORT, timeout = 300) {
   const start = Date.now();
   const interval = 5000;
   const safePort = Number(port);
@@ -175,7 +177,7 @@ function stopNimContainer(sandboxName) {
   run(`docker rm ${qn} 2>/dev/null || true`, { ignoreError: true });
 }
 
-function nimStatus(sandboxName) {
+function nimStatus(sandboxName, port = VLLM_PORT) {
   const name = containerName(sandboxName);
   try {
     const state = runCapture(
@@ -186,7 +188,7 @@ function nimStatus(sandboxName) {
 
     let healthy = false;
     if (state === "running") {
-      const health = runCapture(`curl -sf http://localhost:8000/v1/models 2>/dev/null`, {
+      const health = runCapture(`curl -sf http://localhost:${port}/v1/models 2>/dev/null`, {
         ignoreError: true,
       });
       healthy = !!health;
diff --git a/bin/lib/onboard.js b/bin/lib/onboard.js
index 2bbbda577..e58f91a8b 100644
--- a/bin/lib/onboard.js
+++ b/bin/lib/onboard.js
@@ -9,6 +9,7 @@ const fs = require("fs");
 const os = require("os");
 const path = require("path");
 const { ROOT, SCRIPTS, run, runCapture, shellQuote } = require("./runner");
+const { DASHBOARD_PORT, GATEWAY_PORT, VLLM_PORT, OLLAMA_PORT } = require("./ports");
 const {
   getDefaultOllamaModel,
   getLocalProviderBaseUrl,
@@ -235,6 +236,16 @@ function getNonInteractiveModel(providerKey) {
 async function preflight() {
   step(1, 7, "Preflight checks");
 
+  // Bootstrap .env from .env.example on first run so port defaults are
+  // discoverable and editable.  This doesn't affect the current process
+  // (ports.js is already loaded), but ensures .env exists for future runs.
+  const envFile = path.join(ROOT, ".env");
+  const envExample = path.join(ROOT, ".env.example");
+  if (!fs.existsSync(envFile) && fs.existsSync(envExample)) {
+    fs.copyFileSync(envExample, envFile);
+    console.log("  ✓ Created .env from .env.example");
+  }
+
   // Docker
   if (!isDockerRunning()) {
     console.error("  Docker is not running. Please start Docker and try again.");
@@ -271,17 +282,17 @@ async function preflight() {
   const gwInfo = runCapture("openshell gateway info -g nemoclaw 2>/dev/null", { ignoreError: true });
   if (hasStaleGateway(gwInfo)) {
     console.log("  Cleaning up previous NemoClaw session...");
-    run("openshell forward stop 18789 2>/dev/null || true", { ignoreError: true });
+    run(`openshell forward stop ${DASHBOARD_PORT} 2>/dev/null || true`, { ignoreError: true });
     run("openshell gateway destroy -g nemoclaw 2>/dev/null || true", { ignoreError: true });
     console.log("  ✓ Previous session cleaned up");
   }
 
-  // Required ports — gateway (8080) and dashboard (18789)
+  // Required ports — gateway and dashboard
   const requiredPorts = [
-    { port: 8080, label: "OpenShell gateway" },
-    { port: 18789, label: "NemoClaw dashboard" },
+    { port: GATEWAY_PORT, label: "OpenShell gateway", envVar: "NEMOCLAW_GATEWAY_PORT" },
+    { port: DASHBOARD_PORT, label: "NemoClaw dashboard", envVar: "NEMOCLAW_DASHBOARD_PORT" },
   ];
-  for (const { port, label } of requiredPorts) {
+  for (const { port, label, envVar } of requiredPorts) {
     const portCheck = await checkPortAvailable(port);
     if (!portCheck.ok) {
       console.error("");
@@ -291,7 +302,7 @@ async function preflight() {
       if (portCheck.process && portCheck.process !== "unknown") {
         console.error(`     Blocked by: ${portCheck.process}${portCheck.pid ? ` (PID ${portCheck.pid})` : ""}`);
         console.error("");
-        console.error("     To fix, stop the conflicting process:");
+        console.error("     To fix, either stop the conflicting process:");
         console.error("");
         if (portCheck.pid) {
           console.error(`       sudo kill ${portCheck.pid}`);
@@ -305,6 +316,9 @@ async function preflight() {
         console.error(`     Run: lsof -i :${port} -sTCP:LISTEN`);
       }
       console.error("");
+      console.error(`     Or use a different port by adding to .env.local:`);
+      console.error(`       echo '${envVar}=<port>' >> .env.local`);
+      console.error("");
       console.error(`     Detail: ${portCheck.reason}`);
       process.exit(1);
     }
@@ -333,7 +347,7 @@ async function startGateway(gpu) {
   // Destroy old gateway
   run("openshell gateway destroy -g nemoclaw 2>/dev/null || true", { ignoreError: true });
 
-  const gwArgs = ["--name", "nemoclaw"];
+  const gwArgs = ["--name", "nemoclaw", "--port", String(GATEWAY_PORT)];
   // Do NOT pass --gpu here. On DGX Spark (and most GPU hosts), inference is
   // routed through a host-side provider (Ollama, vLLM, or cloud API) — the
   // sandbox itself does not need direct GPU access. Passing --gpu causes
@@ -434,16 +448,23 @@ async function createSandbox(gpu) {
   // Create sandbox (use -- echo to avoid dropping into interactive shell)
   // Pass the base policy so sandbox starts in proxy mode (required for policy updates later)
   const basePolicyPath = path.join(ROOT, "nemoclaw-blueprint", "policies", "openclaw-sandbox.yaml");
+  const chatUiUrl = process.env.CHAT_UI_URL || `http://127.0.0.1:${DASHBOARD_PORT}`;
   const createArgs = [
     `--from "${buildCtx}/Dockerfile"`,
     `--name "${sandboxName}"`,
     `--policy "${basePolicyPath}"`,
   ];
+  // CHAT_UI_URL is passed as an env arg below; the Dockerfile ARG default
+  // covers the standard port at build time. --build-arg is not supported by
+  // the current openshell sandbox create CLI.
   // --gpu is intentionally omitted. See comment in startGateway().
 
   console.log(`  Creating sandbox '${sandboxName}' (this takes a few minutes on first run)...`);
-  const chatUiUrl = process.env.CHAT_UI_URL || 'http://127.0.0.1:18789';
-  const envArgs = [`CHAT_UI_URL=${shellQuote(chatUiUrl)}`];
+  const envArgs = [
+    `CHAT_UI_URL=${shellQuote(chatUiUrl)}`,
+    `NEMOCLAW_DASHBOARD_PORT=${DASHBOARD_PORT}`,
+    `PUBLIC_PORT=${DASHBOARD_PORT}`,
+  ];
   if (process.env.NVIDIA_API_KEY) {
     envArgs.push(`NVIDIA_API_KEY=${shellQuote(process.env.NVIDIA_API_KEY)}`);
   }
@@ -507,12 +528,12 @@ async function createSandbox(gpu) {
     process.exit(1);
   }
 
-  // Release any stale forward on port 18789 before claiming it for the new sandbox.
+  // Release any stale forward on the dashboard port before claiming it for the new sandbox.
   // A previous onboard run may have left the port forwarded to a different sandbox,
   // which would silently prevent the new sandbox's dashboard from being reachable.
-  run(`openshell forward stop 18789 2>/dev/null || true`, { ignoreError: true });
+  run(`openshell forward stop ${DASHBOARD_PORT} 2>/dev/null || true`, { ignoreError: true });
   // Forward dashboard port to the new sandbox
-  run(`openshell forward start --background 18789 "${sandboxName}"`, { ignoreError: true });
+  run(`openshell forward start --background ${DASHBOARD_PORT} "${sandboxName}"`, { ignoreError: true });
 
   // Register only after confirmed ready — prevents phantom entries
   registry.registerSandbox({
@@ -535,8 +556,8 @@ async function setupNim(sandboxName, gpu) {
 
   // Detect local inference options
   const hasOllama = !!runCapture("command -v ollama", { ignoreError: true });
-  const ollamaRunning = !!runCapture("curl -sf http://localhost:11434/api/tags 2>/dev/null", { ignoreError: true });
-  const vllmRunning = !!runCapture("curl -sf http://localhost:8000/v1/models 2>/dev/null", { ignoreError: true });
+  const ollamaRunning = !!runCapture(`curl -sf http://localhost:${OLLAMA_PORT}/api/tags 2>/dev/null`, { ignoreError: true });
+  const vllmRunning = !!runCapture(`curl -sf http://localhost:${VLLM_PORT}/v1/models 2>/dev/null`, { ignoreError: true });
   const requestedProvider = isNonInteractive() ? getNonInteractiveProvider() : null;
   const requestedModel = isNonInteractive() ? getNonInteractiveModel(requestedProvider || "cloud") : null;
   // Build options list — only show local options with NEMOCLAW_EXPERIMENTAL=1
@@ -554,14 +575,14 @@ async function setupNim(sandboxName, gpu) {
     options.push({
       key: "ollama",
       label:
-        `Local Ollama (localhost:11434)${ollamaRunning ? " — running" : ""}` +
+        `Local Ollama (localhost:${OLLAMA_PORT})${ollamaRunning ? " — running" : ""}` +
         (ollamaRunning ? " (suggested)" : ""),
     });
   }
   if (EXPERIMENTAL && vllmRunning) {
     options.push({
       key: "vllm",
-      label: "Existing vLLM instance (localhost:8000) — running [experimental] (suggested)",
+      label: `Existing vLLM instance (localhost:${VLLM_PORT}) — running [experimental] (suggested)`,
     });
   }
 
@@ -654,10 +675,10 @@ async function setupNim(sandboxName, gpu) {
     } else if (selected.key === "ollama") {
       if (!ollamaRunning) {
         console.log("  Starting Ollama...");
-        run("OLLAMA_HOST=0.0.0.0:11434 ollama serve > /dev/null 2>&1 &", { ignoreError: true });
+        run(`OLLAMA_HOST=0.0.0.0:${OLLAMA_PORT} ollama serve > /dev/null 2>&1 &`, { ignoreError: true });
         sleep(2);
       }
-      console.log("  ✓ Using Ollama on localhost:11434");
+      console.log(`  ✓ Using Ollama on localhost:${OLLAMA_PORT}`);
       provider = "ollama-local";
       if (isNonInteractive()) {
         model = requestedModel || getDefaultOllamaModel(runCapture);
@@ -668,9 +689,9 @@ async function setupNim(sandboxName, gpu) {
       console.log("  Installing Ollama via Homebrew...");
       run("brew install ollama", { ignoreError: true });
       console.log("  Starting Ollama...");
-      run("OLLAMA_HOST=0.0.0.0:11434 ollama serve > /dev/null 2>&1 &", { ignoreError: true });
+      run(`OLLAMA_HOST=0.0.0.0:${OLLAMA_PORT} ollama serve > /dev/null 2>&1 &`, { ignoreError: true });
         sleep(2);
-      console.log("  ✓ Using Ollama on localhost:11434");
+      console.log(`  ✓ Using Ollama on localhost:${OLLAMA_PORT}`);
       provider = "ollama-local";
       if (isNonInteractive()) {
         model = requestedModel || getDefaultOllamaModel(runCapture);
@@ -678,7 +699,7 @@ async function setupNim(sandboxName, gpu) {
         model = await promptOllamaModel();
       }
     } else if (selected.key === "vllm") {
-      console.log("  ✓ Using existing vLLM on localhost:8000");
+      console.log(`  ✓ Using existing vLLM on localhost:${VLLM_PORT}`);
       provider = "vllm-local";
       model = "vllm-local";
     }
@@ -701,6 +722,23 @@ async function setupNim(sandboxName, gpu) {
     console.log(`  Using NVIDIA Endpoint API with model: ${model}`);
   }
 
+  // Warn (don't block) if the selected inference port is occupied by another process.
+  // Only check for vllm-local when we did NOT start NIM ourselves (nimContainer is
+  // set when we launched a NIM container).  For ollama-local we always start or
+  // adopt the service, so the port being in use is expected — skip the warning.
+  if (provider === "vllm-local" && !nimContainer) {
+    const vllmCheck = await checkPortAvailable(VLLM_PORT);
+    if (!vllmCheck.ok) {
+      const who = vllmCheck.process !== "unknown"
+        ? ` by ${vllmCheck.process}${vllmCheck.pid ? ` (PID ${vllmCheck.pid})` : ""}`
+        : "";
+      console.log("");
+      console.log(`  ⚠  Port ${VLLM_PORT} is in use${who}.`);
+      console.log(`     vLLM/NIM inference needs this port. If this is your inference server, you're fine.`);
+      console.log(`     Otherwise, stop the conflicting process or set NEMOCLAW_VLLM_PORT to a different port.`);
+    }
+  }
+
   registry.updateSandbox(sandboxName, { model, provider, nimContainer });
 
   return { model, provider };
diff --git a/bin/lib/ports.js b/bin/lib/ports.js
new file mode 100644
index 000000000..42fcb7241
--- /dev/null
+++ b/bin/lib/ports.js
@@ -0,0 +1,31 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+//
+// Central port configuration — single source of truth for all configurable ports.
+// Override via environment variables or a .env file at the project root.
+
+function parsePort(envVar, fallback) {
+  const raw = process.env[envVar];
+  if (raw === undefined || raw === "") return fallback;
+  const parsed = parseInt(raw, 10);
+  if (Number.isNaN(parsed) || parsed < 1024 || parsed > 65535) {
+    throw new Error(
+      `Invalid port: ${envVar}="${raw}" — must be an integer between 1024 and 65535`
+    );
+  }
+  return parsed;
+}
+
+// Dashboard port supports legacy env var fallback chain:
+//   NEMOCLAW_DASHBOARD_PORT → DASHBOARD_PORT → PUBLIC_PORT → 18789
+const DASHBOARD_PORT = parsePort(
+  "NEMOCLAW_DASHBOARD_PORT",
+  parsePort("DASHBOARD_PORT", parsePort("PUBLIC_PORT", 18789))
+);
+
+module.exports = {
+  DASHBOARD_PORT,
+  GATEWAY_PORT: parsePort("NEMOCLAW_GATEWAY_PORT", 8080),
+  VLLM_PORT: parsePort("NEMOCLAW_VLLM_PORT", 8000),
+  OLLAMA_PORT: parsePort("NEMOCLAW_OLLAMA_PORT", 11434),
+};
diff --git a/bin/lib/preflight.js b/bin/lib/preflight.js
index 7f191413d..a77768a2a 100644
--- a/bin/lib/preflight.js
+++ b/bin/lib/preflight.js
@@ -5,6 +5,7 @@
 
 const net = require("net");
 const { runCapture } = require("./runner");
+const { DASHBOARD_PORT } = require("./ports");
 
 /**
  * Check whether a TCP port is available for listening.
@@ -21,7 +22,7 @@ const { runCapture } = require("./runner");
  *   { ok: false, process: string, pid: number|null, reason: string }
  */
 async function checkPortAvailable(port, opts) {
-  const p = port || 18789;
+  const p = port || DASHBOARD_PORT;
   const o = opts || {};
 
   // ── lsof path ──────────────────────────────────────────────────
diff --git a/bin/nemoclaw.js b/bin/nemoclaw.js
index 832a8d3cc..a31645218 100755
--- a/bin/nemoclaw.js
+++ b/bin/nemoclaw.js
@@ -7,6 +7,10 @@ const path = require("path");
 const fs = require("fs");
 const os = require("os");
 
+// Load .env files before any module reads process.env (e.g. ports.js)
+require("./lib/env");
+
+
 const { ROOT, SCRIPTS, run, runCapture, runInteractive, shellQuote, validateName } = require("./lib/runner");
 const {
   ensureApiKey,
@@ -17,6 +21,7 @@ const {
 const registry = require("./lib/registry");
 const nim = require("./lib/nim");
 const policies = require("./lib/policies");
+const { DASHBOARD_PORT } = require("./lib/ports");
 
 // ── Global commands ──────────────────────────────────────────────
 
@@ -283,7 +288,7 @@ function listSandboxes() {
 function sandboxConnect(sandboxName) {
   const qn = shellQuote(sandboxName);
   // Ensure port forward is alive before connecting
-  run(`openshell forward start --background 18789 ${qn} 2>/dev/null || true`, { ignoreError: true });
+  run(`openshell forward start --background ${DASHBOARD_PORT} ${qn} 2>/dev/null || true`, { ignoreError: true });
   runInteractive(`openshell sandbox connect ${qn}`);
 }
 
diff --git a/docs/reference/port-configuration.md b/docs/reference/port-configuration.md
new file mode 100644
index 000000000..b6540c81c
--- /dev/null
+++ b/docs/reference/port-configuration.md
@@ -0,0 +1,118 @@
+---
+title:
+  page: "NemoClaw Port Configuration"
+  nav: "Port Configuration"
+description: "Configure NemoClaw network ports using environment variables or a .env file."
+keywords: ["nemoclaw ports", "nemoclaw port configuration", "nemoclaw port conflict"]
+topics: ["generative_ai", "ai_agents"]
+tags: ["openclaw", "openshell", "configuration", "nemoclaw"]
+content:
+  type: reference
+  difficulty: technical_beginner
+  audience: ["developer", "engineer"]
+status: published
+---
+
+<!--
+  SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+  SPDX-License-Identifier: Apache-2.0
+-->
+
+# NemoClaw Port Configuration
+
+NemoClaw uses four network ports.
+All ports are configurable through environment variables or a `.env` file at the project root.
+
+## Default Ports
+
+| Port | Default | Environment variable | Purpose |
+|------|---------|----------------------|---------|
+| Dashboard | 18789 | `NEMOCLAW_DASHBOARD_PORT` | OpenClaw web UI, forwarded from sandbox to host |
+| Gateway | 8080 | `NEMOCLAW_GATEWAY_PORT` | OpenShell gateway API |
+| vLLM/NIM | 8000 | `NEMOCLAW_VLLM_PORT` | Local vLLM or NIM inference server |
+| Ollama | 11434 | `NEMOCLAW_OLLAMA_PORT` | Local Ollama inference server |
+
+## Configure Ports with a .env File
+
+Copy the example file and edit it to set your preferred ports.
+
+```console
+$ cp .env.example .env
+```
+
+The `.env.example` file contains all four port variables with their defaults:
+
+```bash
+NEMOCLAW_DASHBOARD_PORT=18789
+NEMOCLAW_GATEWAY_PORT=8080
+NEMOCLAW_VLLM_PORT=8000
+NEMOCLAW_OLLAMA_PORT=11434
+```
+
+Edit `.env` to change any port.
+Ports must be integers in the range 1024 to 65535.
+The `.env` file is gitignored and not committed to the repository.
+
+## Configure Ports with Environment Variables
+
+Export the variables directly in your shell instead of using a `.env` file.
+
+```console
+$ export NEMOCLAW_DASHBOARD_PORT=28789
+$ export NEMOCLAW_VLLM_PORT=9000
+$ nemoclaw onboard
+```
+
+Shell exports take precedence over `.env` file values.
+
+## Dashboard Port Fallback Chain
+
+The dashboard port checks multiple variables for backward compatibility.
+The first defined value wins:
+
+1. `NEMOCLAW_DASHBOARD_PORT`
+2. `DASHBOARD_PORT`
+3. `PUBLIC_PORT`
+4. `18789` (default)
+
+## Check for Port Conflicts
+
+Run the port checker script before onboarding to detect conflicts.
+
+```console
+$ scripts/check-ports.sh
+```
+
+The script reads your `.env` and `.env.local` files (if present) to resolve the configured ports, then checks each one.
+If a port is in use, the output shows the process name and PID holding it.
+
+```text
+Checking NemoClaw ports...
+
+  ok        18789 (dashboard)
+  CONFLICT  8080 (gateway) — in use by nginx (PID 1234)
+  ok        8000 (vllm/nim)
+  ok        11434 (ollama)
+
+1 port conflict(s) found.
+Set NEMOCLAW_*_PORT env vars or edit .env to use different ports.
+```
+
+You can also pass custom ports as arguments to check additional ports.
+
+```console
+$ scripts/check-ports.sh 9000 9080
+```
+
+The onboarding preflight also checks for port conflicts automatically.
+
+:::{note}
+Ports 8080 and 8000 are common conflict sources.
+Port 8080 is used by many web servers and proxies.
+Port 8000 is used by development servers and other inference tools.
+:::
+
+## Next Steps
+
+- [Troubleshooting](troubleshooting.md) for resolving port and onboarding issues.
+- [CLI Commands](commands.md) for the full command reference.
diff --git a/docs/reference/troubleshooting.md b/docs/reference/troubleshooting.md
index 16f345423..67a47b4a9 100644
--- a/docs/reference/troubleshooting.md
+++ b/docs/reference/troubleshooting.md
@@ -90,17 +90,29 @@ Add the `export` line to your `~/.bashrc` or `~/.zshrc` to make it permanent, th
 
 ### Port already in use
 
-The NemoClaw gateway uses port `18789` by default.
-If another process is already bound to this port, onboarding fails.
-Identify the conflicting process, verify it is safe to stop, and terminate it:
+NemoClaw uses four ports (see the [Port Configuration](../../README.md#port-configuration) section in the README).
+If another process is bound to one of these ports, onboarding fails with a message identifying the conflicting process.
+
+To resolve, either stop the conflicting process:
 
 ```console
-$ lsof -i :18789
+$ lsof -i :8080
 $ kill <PID>
 ```
 
-If the process does not exit, use `kill -9 <PID>` to force-terminate it.
-Then retry onboarding.
+Or use a different port by setting the corresponding environment variable before onboarding:
+
+```console
+$ export NEMOCLAW_GATEWAY_PORT=9080
+$ nemoclaw onboard
+```
+
+| Default port | Env var | Common conflicts |
+|-------------|---------|-----------------|
+| 8080 | `NEMOCLAW_GATEWAY_PORT` | Jenkins, Tomcat, K8s dashboard |
+| 8000 | `NEMOCLAW_VLLM_PORT` | Django, PHP dev server |
+| 18789 | `NEMOCLAW_DASHBOARD_PORT` | Uncommon |
+| 11434 | `NEMOCLAW_OLLAMA_PORT` | Uncommon |
 
 ## Onboarding
 
diff --git a/nemoclaw-blueprint/blueprint.yaml b/nemoclaw-blueprint/blueprint.yaml
index f55f9f651..7d9e0d176 100644
--- a/nemoclaw-blueprint/blueprint.yaml
+++ b/nemoclaw-blueprint/blueprint.yaml
@@ -20,7 +20,7 @@ components:
   sandbox:
     image: "ghcr.io/nvidia/openshell-community/sandboxes/openclaw:latest"
     name: "openclaw"
-    forward_ports:
+    forward_ports:  # Override at runtime via NEMOCLAW_DASHBOARD_PORT
       - 18789
 
   inference:
@@ -42,14 +42,14 @@ components:
       nim-local:
         provider_type: "openai"
         provider_name: "nim-local"
-        endpoint: "http://nim-service.local:8000/v1"
+        endpoint: "http://nim-service.local:8000/v1"  # Port overridden by NEMOCLAW_VLLM_PORT via runner.py
         model: "nvidia/nemotron-3-super-120b-a12b"
         credential_env: "NIM_API_KEY"
 
       vllm:
         provider_type: "openai"
         provider_name: "vllm-local"
-        endpoint: "http://localhost:8000/v1"
+        endpoint: "http://localhost:8000/v1"  # Port overridden by NEMOCLAW_VLLM_PORT via runner.py
         model: "nvidia/nemotron-3-nano-30b-a3b"
         credential_env: "OPENAI_API_KEY"
         credential_default: "dummy"
@@ -61,5 +61,5 @@ components:
         name: nim_service
         endpoints:
           - host: "nim-service.local"
-            port: 8000
+            port: 8000  # Overridden by NEMOCLAW_VLLM_PORT via runner.py
             protocol: rest
diff --git a/nemoclaw-blueprint/orchestrator/runner.py b/nemoclaw-blueprint/orchestrator/runner.py
index 432c228c3..31f2bc327 100644
--- a/nemoclaw-blueprint/orchestrator/runner.py
+++ b/nemoclaw-blueprint/orchestrator/runner.py
@@ -17,6 +17,7 @@
 import argparse
 import json
 import os
+import re
 import shutil
 import subprocess
 import sys
@@ -29,27 +30,84 @@
 
 
 def log(msg: str) -> None:
+    """Print a message to stdout with immediate flush."""
     print(msg, flush=True)
 
 
 def progress(pct: int, label: str) -> None:
+    """Emit a PROGRESS:<pct>:<label> line for the TS plugin to parse."""
     print(f"PROGRESS:{pct}:{label}", flush=True)
 
 
 def emit_run_id() -> str:
+    """Generate a unique run ID and print it as a RUN_ID:<id> line."""
     rid = f"nc-{datetime.now(UTC).strftime('%Y%m%d-%H%M%S')}-{uuid.uuid4().hex[:8]}"
     print(f"RUN_ID:{rid}", flush=True)
     return rid
 
 
 def load_blueprint() -> dict[str, Any]:
+    """Load blueprint.yaml from NEMOCLAW_BLUEPRINT_PATH and apply port overrides."""
     blueprint_path = Path(os.environ.get("NEMOCLAW_BLUEPRINT_PATH", "."))
     bp_file = blueprint_path / "blueprint.yaml"
     if not bp_file.exists():
         log(f"ERROR: blueprint.yaml not found at {bp_file}")
         sys.exit(1)
     with bp_file.open() as f:
-        return yaml.safe_load(f)
+        bp = yaml.safe_load(f)
+    _apply_port_overrides(bp)
+    return bp
+
+
+def _parse_port_env(env_var: str) -> int | None:
+    """Read and validate a port from an environment variable.
+
+    Returns the port as an int, or None if the variable is unset/empty.
+    Exits with a clear error for invalid values (matching ports.js behavior).
+    """
+    raw = os.environ.get(env_var, "")
+    if not raw:
+        return None
+    try:
+        port = int(raw)
+    except ValueError:
+        log(f'ERROR: {env_var}="{raw}" is not a valid port number')
+        sys.exit(1)
+    if port < 1024 or port > 65535:
+        log(f"ERROR: {env_var}={port} — must be between 1024 and 65535")
+        sys.exit(1)
+    return port
+
+
+def _apply_port_overrides(bp: dict[str, Any]) -> None:
+    """Override hardcoded ports from NEMOCLAW_*_PORT env vars.
+
+    Keeps blueprint.yaml as a readable reference of defaults while allowing
+    runtime configuration without editing YAML.
+    """
+    components = bp.setdefault("components", {})
+
+    # Dashboard / forward port
+    dashboard_port = _parse_port_env("NEMOCLAW_DASHBOARD_PORT")
+    if dashboard_port:
+        sandbox = components.setdefault("sandbox", {})
+        sandbox["forward_ports"] = [dashboard_port]
+
+    # vLLM / NIM inference port
+    vllm_port = _parse_port_env("NEMOCLAW_VLLM_PORT")
+    if vllm_port:
+        profiles = components.get("inference", {}).get("profiles", {})
+        for key in ("nim-local", "vllm"):
+            if key in profiles:
+                old_endpoint = profiles[key].get("endpoint", "")
+                # Replace the port in endpoint URL (matches any numeric port)
+                profiles[key]["endpoint"] = re.sub(r":\d+(/|$)", f":{vllm_port}\\1", old_endpoint)
+
+        # Policy addition: nim_service port
+        additions = components.get("policy", {}).get("additions", {})
+        nim_svc = additions.get("nim_service", {})
+        for ep in nim_svc.get("endpoints", []):
+            ep["port"] = vllm_port
 
 
 def run_cmd(
@@ -310,6 +368,7 @@ def action_rollback(rid: str) -> None:
 
 
 def main() -> None:
+    """Parse CLI arguments and dispatch to the requested action."""
     parser = argparse.ArgumentParser(description="NemoClaw Blueprint Runner")
     parser.add_argument("action", choices=["plan", "apply", "status", "rollback"])
     parser.add_argument("--profile", default="default")
diff --git a/package-lock.json b/package-lock.json
index 362db593d..3e81a1777 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -891,14 +891,6 @@
         "scripts/actions/documentation"
       ]
     },
-    "node_modules/@buape/carbon/node_modules/opusscript": {
-      "version": "0.0.8",
-      "resolved": "https://registry.npmjs.org/opusscript/-/opusscript-0.0.8.tgz",
-      "integrity": "sha512-VSTi1aWFuCkRCVq+tx/BQ5q9fMnQ9pVZ3JU4UHKqTkf0ED3fKEPdr+gKAAl3IA2hj9rrP6iyq3hlcJq3HELtNQ==",
-      "license": "MIT",
-      "optional": true,
-      "peer": true
-    },
     "node_modules/@buape/carbon/node_modules/prism-media": {
       "version": "1.3.5",
       "resolved": "https://registry.npmjs.org/prism-media/-/prism-media-1.3.5.tgz",
@@ -1291,14 +1283,6 @@
         "url": "https://github.com/discordjs/discord.js?sponsor"
       }
     },
-    "node_modules/@discordjs/voice/node_modules/opusscript": {
-      "version": "0.0.8",
-      "resolved": "https://registry.npmjs.org/opusscript/-/opusscript-0.0.8.tgz",
-      "integrity": "sha512-VSTi1aWFuCkRCVq+tx/BQ5q9fMnQ9pVZ3JU4UHKqTkf0ED3fKEPdr+gKAAl3IA2hj9rrP6iyq3hlcJq3HELtNQ==",
-      "license": "MIT",
-      "optional": true,
-      "peer": true
-    },
     "node_modules/@discordjs/voice/node_modules/prism-media": {
       "version": "1.3.5",
       "resolved": "https://registry.npmjs.org/prism-media/-/prism-media-1.3.5.tgz",
diff --git a/scripts/brev-setup.sh b/scripts/brev-setup.sh
index 4421b5bce..d7c3667f1 100755
--- a/scripts/brev-setup.sh
+++ b/scripts/brev-setup.sh
@@ -27,6 +27,9 @@ fail() { echo -e "${RED}[brev]${NC} $1"; exit 1; }
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 
+# Load port overrides if present
+[ -f "${SCRIPT_DIR}/../.env" ] && set -a && . "${SCRIPT_DIR}/../.env" && set +a
+
 [ -n "${NVIDIA_API_KEY:-}" ] || fail "NVIDIA_API_KEY not set"
 
 # Suppress needrestart noise from apt (Scanning processes, No services need...)
@@ -129,19 +132,20 @@ if command -v nvidia-smi > /dev/null 2>&1; then
   fi
 
   # Start vLLM if not already running
-  if curl -s http://localhost:8000/v1/models > /dev/null 2>&1; then
-    info "vLLM already running on :8000"
+  VLLM_PORT="${NEMOCLAW_VLLM_PORT:-8000}"
+  if curl -s "http://localhost:${VLLM_PORT}/v1/models" > /dev/null 2>&1; then
+    info "vLLM already running on :${VLLM_PORT}"
   elif python3 -c "import vllm" 2>/dev/null; then
     info "Starting vLLM with $VLLM_MODEL..."
     nohup python3 -m vllm.entrypoints.openai.api_server \
       --model "$VLLM_MODEL" \
-      --port 8000 \
+      --port "$VLLM_PORT" \
       --host 0.0.0.0 \
       > /tmp/vllm-server.log 2>&1 &
     VLLM_PID=$!
     info "Waiting for vLLM to load model (this can take a few minutes)..."
-    for i in $(seq 1 120); do
-      if curl -s http://localhost:8000/v1/models > /dev/null 2>&1; then
+    for _i in $(seq 1 120); do
+      if curl -s "http://localhost:${VLLM_PORT}/v1/models" > /dev/null 2>&1; then
         info "vLLM ready (PID $VLLM_PID)"
         break
       fi
diff --git a/scripts/check-ports.sh b/scripts/check-ports.sh
new file mode 100755
index 000000000..103786b36
--- /dev/null
+++ b/scripts/check-ports.sh
@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# check-ports.sh — Check whether NemoClaw ports are available.
+#
+# Reads configured ports from .env (if present), falls back to defaults.
+# Pass custom ports as arguments to check additional ports.
+#
+# Usage:
+#   scripts/check-ports.sh            # check configured/default ports
+#   scripts/check-ports.sh 9000 9080  # check custom ports
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# ── Load .env ────────────────────────────────────────────────────────
+load_env() {
+  local env_file="$1"
+  [[ -f "$env_file" ]] || return 0
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    line="${line%%#*}"        # strip comments
+    line="${line#"${line%%[![:space:]]*}"}"  # trim leading whitespace
+    line="${line%"${line##*[![:space:]]}"}"  # trim trailing whitespace
+    [[ -z "$line" ]] && continue
+    [[ "$line" == *=* ]] || continue
+    local key="${line%%=*}"
+    local val="${line#*=}"
+    # Strip surrounding quotes
+    val="${val#\"}" ; val="${val%\"}"
+    val="${val#\'}" ; val="${val%\'}"
+    # Only set if not already in environment
+    if [[ -z "${!key+x}" ]]; then
+      export "$key=$val"
+    fi
+  done < "$env_file"
+}
+
+load_env "$PROJECT_ROOT/.env.local"
+load_env "$PROJECT_ROOT/.env"
+
+# ── Resolve ports ────────────────────────────────────────────────────
+DASHBOARD_PORT="${NEMOCLAW_DASHBOARD_PORT:-${DASHBOARD_PORT:-${PUBLIC_PORT:-18789}}}"
+GATEWAY_PORT="${NEMOCLAW_GATEWAY_PORT:-8080}"
+VLLM_PORT="${NEMOCLAW_VLLM_PORT:-8000}"
+OLLAMA_PORT="${NEMOCLAW_OLLAMA_PORT:-11434}"
+
+# ── Validate ports ──────────────────────────────────────────────────
+validate_port() {
+  local name="$1"
+  local value="$2"
+  if ! [[ "$value" =~ ^[0-9]+$ ]]; then
+    echo "Error: $name is not a valid integer: '$value'" >&2
+    exit 1
+  fi
+  if (( value < 1024 || value > 65535 )); then
+    echo "Error: $name=$value is out of range (must be 1024–65535)" >&2
+    exit 1
+  fi
+}
+
+validate_port "DASHBOARD_PORT" "$DASHBOARD_PORT"
+validate_port "GATEWAY_PORT" "$GATEWAY_PORT"
+validate_port "VLLM_PORT" "$VLLM_PORT"
+validate_port "OLLAMA_PORT" "$OLLAMA_PORT"
+
+# ── Ensure lsof is available ────────────────────────────────────────
+if ! command -v lsof >/dev/null 2>&1; then
+  echo "Error: lsof is required but not found in PATH" >&2
+  exit 1
+fi
+
+# ── Check a single port ─────────────────────────────────────────────
+conflicts=0
+
+check_port() {
+  local port="$1"
+  local label="${2:-}"
+  local prefix="$port"
+  [[ -n "$label" ]] && prefix="$port ($label)"
+
+  if lsof -iTCP:"$port" -sTCP:LISTEN -nP >/dev/null 2>&1; then
+    local proc
+    proc="$(lsof -iTCP:"$port" -sTCP:LISTEN -nP 2>/dev/null | awk 'NR==2 {print $1 " (PID " $2 ")"}')"
+    echo "  CONFLICT  $prefix — in use by $proc"
+    conflicts=$((conflicts + 1))
+    return 1
+  else
+    echo "  ok        $prefix"
+    return 0
+  fi
+}
+
+# ── Run checks ───────────────────────────────────────────────────────
+echo "Checking NemoClaw ports..."
+echo ""
+
+check_port "$DASHBOARD_PORT" "dashboard" || true
+check_port "$GATEWAY_PORT" "gateway" || true
+check_port "$VLLM_PORT" "vllm/nim" || true
+check_port "$OLLAMA_PORT" "ollama" || true
+
+if [[ $# -gt 0 ]]; then
+  echo ""
+  echo "Custom ports:"
+  for p in "$@"; do
+    check_port "$p" || true
+  done
+fi
+
+echo ""
+if [[ $conflicts -gt 0 ]]; then
+  echo "$conflicts port conflict(s) found."
+  echo "Set NEMOCLAW_*_PORT env vars or edit .env to use different ports."
+  exit 1
+else
+  echo "All ports available."
+fi
diff --git a/scripts/debug.sh b/scripts/debug.sh
index 3fa2647e6..db1a5a872 100755
--- a/scripts/debug.sh
+++ b/scripts/debug.sh
@@ -285,7 +285,7 @@ if [ "$QUICK" = false ]; then
   # shellcheck disable=SC2016
   collect "curl-models" sh -c 'code=$(curl -s -o /dev/null -w "%{http_code}" https://integrate.api.nvidia.com/v1/models); echo "HTTP $code"; if [ "$code" -ge 200 ] && [ "$code" -lt 500 ]; then echo "NIM API reachable"; else echo "NIM API unreachable"; exit 1; fi'
   collect "lsof-net" sh -c 'lsof -i -P -n 2>/dev/null | head -50'
-  collect "lsof-18789" lsof -i :18789
+  collect "lsof-dashboard" lsof -i :"${NEMOCLAW_DASHBOARD_PORT:-18789}"
 fi
 
 # -- Kernel / IO (full mode only) --
diff --git a/scripts/lib/runtime.sh b/scripts/lib/runtime.sh
index 3bf546847..3e6b03e02 100644
--- a/scripts/lib/runtime.sh
+++ b/scripts/lib/runtime.sh
@@ -206,8 +206,8 @@ get_local_provider_base_url() {
   local provider="${1:-}"
 
   case "$provider" in
-    vllm-local) printf 'http://host.openshell.internal:8000/v1\n' ;;
-    ollama-local) printf 'http://host.openshell.internal:11434/v1\n' ;;
+    vllm-local) printf 'http://host.openshell.internal:%s/v1\n' "${NEMOCLAW_VLLM_PORT:-8000}" ;;
+    ollama-local) printf 'http://host.openshell.internal:%s/v1\n' "${NEMOCLAW_OLLAMA_PORT:-11434}" ;;
     *) return 1 ;;
   esac
 }
@@ -217,10 +217,10 @@ check_local_provider_health() {
 
   case "$provider" in
     vllm-local)
-      curl -sf http://localhost:8000/v1/models > /dev/null 2>&1
+      curl -sf "http://localhost:${NEMOCLAW_VLLM_PORT:-8000}/v1/models" > /dev/null 2>&1
       ;;
     ollama-local)
-      curl -sf http://localhost:11434/api/tags > /dev/null 2>&1
+      curl -sf "http://localhost:${NEMOCLAW_OLLAMA_PORT:-11434}/api/tags" > /dev/null 2>&1
       ;;
     *)
       return 1
diff --git a/scripts/nemoclaw-start.sh b/scripts/nemoclaw-start.sh
index d28b96374..3d26aae76 100755
--- a/scripts/nemoclaw-start.sh
+++ b/scripts/nemoclaw-start.sh
@@ -12,8 +12,8 @@
 set -euo pipefail
 
 NEMOCLAW_CMD=("$@")
-CHAT_UI_URL="${CHAT_UI_URL:-http://127.0.0.1:18789}"
-PUBLIC_PORT=18789
+PUBLIC_PORT="${NEMOCLAW_DASHBOARD_PORT:-${PUBLIC_PORT:-18789}}"
+CHAT_UI_URL="${CHAT_UI_URL:-http://127.0.0.1:${PUBLIC_PORT}}"
 
 write_auth_profile() {
   if [ -z "${NVIDIA_API_KEY:-}" ]; then
diff --git a/scripts/setup.sh b/scripts/setup.sh
index 22b3ccfec..c0e39c439 100755
--- a/scripts/setup.sh
+++ b/scripts/setup.sh
@@ -31,6 +31,11 @@ NC='\033[0m'
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# Load port overrides if present (.env.local takes precedence)
+[ -f "${REPO_DIR}/.env" ] && set -a && . "${REPO_DIR}/.env" && set +a
+[ -f "${REPO_DIR}/.env.local" ] && set -a && . "${REPO_DIR}/.env.local" && set +a
+
 # shellcheck source=./lib/runtime.sh
 . "$SCRIPT_DIR/lib/runtime.sh"
 
@@ -106,7 +111,7 @@ fi
 # 1. Gateway — always start fresh to avoid stale state
 info "Starting OpenShell gateway..."
 openshell gateway destroy -g nemoclaw > /dev/null 2>&1 || true
-GATEWAY_ARGS=(--name nemoclaw)
+GATEWAY_ARGS=(--name nemoclaw --port "${NEMOCLAW_GATEWAY_PORT:-8080}")
 command -v nvidia-smi > /dev/null 2>&1 && GATEWAY_ARGS+=(--gpu)
 openshell gateway start "${GATEWAY_ARGS[@]}" 2>&1 | grep -E "Gateway|✓|Error|error" || true
 
@@ -156,7 +161,7 @@ if [ "$(uname -s)" = "Darwin" ]; then
     # Start Ollama service if not running
     if ! check_local_provider_health "ollama-local"; then
       info "Starting Ollama service..."
-      OLLAMA_HOST=0.0.0.0:11434 ollama serve > /dev/null 2>&1 &
+      OLLAMA_HOST="0.0.0.0:${NEMOCLAW_OLLAMA_PORT:-11434}" ollama serve > /dev/null 2>&1 &
       sleep 2
     fi
     OLLAMA_LOCAL_BASE_URL="$(get_local_provider_base_url "ollama-local")"
diff --git a/scripts/start-services.sh b/scripts/start-services.sh
index cbce0f183..9549ddd2b 100755
--- a/scripts/start-services.sh
+++ b/scripts/start-services.sh
@@ -16,7 +16,12 @@ set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
-DASHBOARD_PORT="${DASHBOARD_PORT:-18789}"
+
+# Load port overrides if present (.env.local takes precedence)
+[ -f "${REPO_DIR}/.env" ] && set -a && . "${REPO_DIR}/.env" && set +a
+[ -f "${REPO_DIR}/.env.local" ] && set -a && . "${REPO_DIR}/.env.local" && set +a
+
+DASHBOARD_PORT="${NEMOCLAW_DASHBOARD_PORT:-${DASHBOARD_PORT:-18789}}"
 
 # ── Parse flags ──────────────────────────────────────────────────
 SANDBOX_NAME="${NEMOCLAW_SANDBOX:-${SANDBOX_NAME:-default}}"
diff --git a/scripts/telegram-bridge.js b/scripts/telegram-bridge.js
index e885b09f2..d82192b22 100755
--- a/scripts/telegram-bridge.js
+++ b/scripts/telegram-bridge.js
@@ -18,7 +18,6 @@
 
 const https = require("https");
 const { execFileSync, spawn } = require("child_process");
-const crypto = require("crypto");
 const { resolveOpenshell } = require("../bin/lib/resolve-openshell");
 const { shellQuote, validateName } = require("../bin/lib/runner");
 
diff --git a/test/e2e/test-double-onboard.sh b/test/e2e/test-double-onboard.sh
index 7ebdddcd5..fd63f0f37 100755
--- a/test/e2e/test-double-onboard.sh
+++ b/test/e2e/test-double-onboard.sh
@@ -51,7 +51,7 @@ if command -v nemoclaw > /dev/null 2>&1; then
 fi
 openshell sandbox delete "$SANDBOX_A" 2>/dev/null || true
 openshell sandbox delete "$SANDBOX_B" 2>/dev/null || true
-openshell forward stop 18789 2>/dev/null || true
+openshell forward stop "${NEMOCLAW_DASHBOARD_PORT:-18789}" 2>/dev/null || true
 openshell gateway destroy -g nemoclaw 2>/dev/null || true
 pass "Pre-cleanup complete"
 
@@ -156,13 +156,13 @@ echo "$output2" | grep -q "Cleaning up previous NemoClaw session" \
   && pass "Stale session cleanup fired on second onboard" \
   || fail "Stale session cleanup did NOT fire (regression: #397)"
 
-echo "$output2" | grep -q "Port 8080 is not available" \
-  && fail "Port 8080 conflict detected (regression: #21)" \
-  || pass "No port 8080 conflict"
+echo "$output2" | grep -q "Port ${NEMOCLAW_GATEWAY_PORT:-8080} is not available" \
+  && fail "Port ${NEMOCLAW_GATEWAY_PORT:-8080} conflict detected (regression: #21)" \
+  || pass "No port ${NEMOCLAW_GATEWAY_PORT:-8080} conflict"
 
-echo "$output2" | grep -q "Port 18789 is not available" \
-  && fail "Port 18789 conflict detected" \
-  || pass "No port 18789 conflict"
+echo "$output2" | grep -q "Port ${NEMOCLAW_DASHBOARD_PORT:-18789} is not available" \
+  && fail "Port ${NEMOCLAW_DASHBOARD_PORT:-18789} conflict detected" \
+  || pass "No port ${NEMOCLAW_DASHBOARD_PORT:-18789} conflict"
 
 echo "$output2" | grep -q "Sandbox '${SANDBOX_A}' created" \
   && pass "Sandbox '$SANDBOX_A' recreated" \
@@ -197,13 +197,13 @@ echo "$output3" | grep -q "Cleaning up previous NemoClaw session" \
   && pass "Stale session cleanup fired on third onboard" \
   || fail "Stale session cleanup did NOT fire on third onboard"
 
-echo "$output3" | grep -q "Port 8080 is not available" \
-  && fail "Port 8080 conflict on third onboard (regression)" \
-  || pass "No port 8080 conflict on third onboard"
+echo "$output3" | grep -q "Port ${NEMOCLAW_GATEWAY_PORT:-8080} is not available" \
+  && fail "Port ${NEMOCLAW_GATEWAY_PORT:-8080} conflict on third onboard (regression)" \
+  || pass "No port ${NEMOCLAW_GATEWAY_PORT:-8080} conflict on third onboard"
 
-echo "$output3" | grep -q "Port 18789 is not available" \
-  && fail "Port 18789 conflict on third onboard" \
-  || pass "No port 18789 conflict on third onboard"
+echo "$output3" | grep -q "Port ${NEMOCLAW_DASHBOARD_PORT:-18789} is not available" \
+  && fail "Port ${NEMOCLAW_DASHBOARD_PORT:-18789} conflict on third onboard" \
+  || pass "No port ${NEMOCLAW_DASHBOARD_PORT:-18789} conflict on third onboard"
 
 echo "$output3" | grep -q "Sandbox '${SANDBOX_B}' created" \
   && pass "Sandbox '$SANDBOX_B' created" \
@@ -218,7 +218,7 @@ nemoclaw "$SANDBOX_A" destroy 2>/dev/null || true
 nemoclaw "$SANDBOX_B" destroy 2>/dev/null || true
 openshell sandbox delete "$SANDBOX_A" 2>/dev/null || true
 openshell sandbox delete "$SANDBOX_B" 2>/dev/null || true
-openshell forward stop 18789 2>/dev/null || true
+openshell forward stop "${NEMOCLAW_DASHBOARD_PORT:-18789}" 2>/dev/null || true
 openshell gateway destroy -g nemoclaw 2>/dev/null || true
 
 openshell sandbox get "$SANDBOX_A" > /dev/null 2>&1 \
diff --git a/test/local-inference.test.js b/test/local-inference.test.js
index 5b77ee2f7..4c648d839 100644
--- a/test/local-inference.test.js
+++ b/test/local-inference.test.js
@@ -18,33 +18,34 @@ const {
   validateOllamaModel,
   validateLocalProvider,
 } = require("../bin/lib/local-inference");
+const { VLLM_PORT, OLLAMA_PORT } = require("../bin/lib/ports");
 
 describe("local inference helpers", () => {
   it("returns the expected base URL for vllm-local", () => {
     assert.equal(
       getLocalProviderBaseUrl("vllm-local"),
-      "http://host.openshell.internal:8000/v1",
+      `http://host.openshell.internal:${VLLM_PORT}/v1`,
     );
   });
 
   it("returns the expected base URL for ollama-local", () => {
     assert.equal(
       getLocalProviderBaseUrl("ollama-local"),
-      "http://host.openshell.internal:11434/v1",
+      `http://host.openshell.internal:${OLLAMA_PORT}/v1`,
     );
   });
 
   it("returns the expected health check command for ollama-local", () => {
     assert.equal(
       getLocalProviderHealthCheck("ollama-local"),
-      "curl -sf http://localhost:11434/api/tags 2>/dev/null",
+      `curl -sf http://localhost:${OLLAMA_PORT}/api/tags 2>/dev/null`,
     );
   });
 
   it("returns the expected container reachability command for ollama-local", () => {
     assert.equal(
       getLocalProviderContainerReachabilityCheck("ollama-local"),
-      `docker run --rm --add-host host.openshell.internal:host-gateway ${CONTAINER_REACHABILITY_IMAGE} -sf http://host.openshell.internal:11434/api/tags 2>/dev/null`,
+      `docker run --rm --add-host host.openshell.internal:host-gateway ${CONTAINER_REACHABILITY_IMAGE} -sf http://host.openshell.internal:${OLLAMA_PORT}/api/tags 2>/dev/null`,
     );
   });
 
@@ -61,7 +62,7 @@ describe("local inference helpers", () => {
   it("returns a clear error when ollama-local is unavailable", () => {
     const result = validateLocalProvider("ollama-local", () => "");
     assert.equal(result.ok, false);
-    assert.match(result.message, /http:\/\/localhost:11434/);
+    assert.match(result.message, new RegExp(`http://localhost:${OLLAMA_PORT}`));
   });
 
   it("returns a clear error when ollama-local is not reachable from containers", () => {
@@ -71,14 +72,14 @@ describe("local inference helpers", () => {
       return callCount === 1 ? '{"models":[]}' : "";
     });
     assert.equal(result.ok, false);
-    assert.match(result.message, /host\.openshell\.internal:11434/);
-    assert.match(result.message, /0\.0\.0\.0:11434/);
+    assert.match(result.message, new RegExp(`host\\.openshell\\.internal:${OLLAMA_PORT}`));
+    assert.match(result.message, new RegExp(`0\\.0\\.0\\.0:${OLLAMA_PORT}`));
   });
 
   it("returns a clear error when vllm-local is unavailable", () => {
     const result = validateLocalProvider("vllm-local", () => "");
     assert.equal(result.ok, false);
-    assert.match(result.message, /http:\/\/localhost:8000/);
+    assert.match(result.message, new RegExp(`http://localhost:${VLLM_PORT}`));
   });
 
   it("parses model names from ollama list output", () => {
@@ -121,14 +122,14 @@ describe("local inference helpers", () => {
 
   it("builds a background warmup command for ollama models", () => {
     const command = getOllamaWarmupCommand("nemotron-3-nano:30b");
-    assert.match(command, /^nohup curl -s http:\/\/localhost:11434\/api\/generate /);
+    assert.match(command, new RegExp(`^nohup curl -s http://localhost:${OLLAMA_PORT}/api/generate `));
     assert.match(command, /"model":"nemotron-3-nano:30b"/);
     assert.match(command, /"keep_alive":"15m"/);
   });
 
   it("builds a foreground probe command for ollama models", () => {
     const command = getOllamaProbeCommand("nemotron-3-nano:30b");
-    assert.match(command, /^curl -sS --max-time 120 http:\/\/localhost:11434\/api\/generate /);
+    assert.match(command, new RegExp(`^curl -sS --max-time 120 http://localhost:${OLLAMA_PORT}/api/generate `));
     assert.match(command, /"model":"nemotron-3-nano:30b"/);
   });
 
diff --git a/test/onboard-selection.test.js b/test/onboard-selection.test.js
index 9000943ba..3cc608943 100644
--- a/test/onboard-selection.test.js
+++ b/test/onboard-selection.test.js
@@ -17,10 +17,12 @@ describe("onboard provider selection UX", () => {
     const credentialsPath = JSON.stringify(path.join(repoRoot, "bin", "lib", "credentials.js"));
     const runnerPath = JSON.stringify(path.join(repoRoot, "bin", "lib", "runner.js"));
     const registryPath = JSON.stringify(path.join(repoRoot, "bin", "lib", "registry.js"));
+    const portsPath = JSON.stringify(path.join(repoRoot, "bin", "lib", "ports.js"));
     const script = String.raw`
 const credentials = require(${credentialsPath});
 const runner = require(${runnerPath});
 const registry = require(${registryPath});
+const { VLLM_PORT, OLLAMA_PORT } = require(${portsPath});
 
 let promptCalls = 0;
 const messages = [];
@@ -34,9 +36,9 @@ credentials.prompt = async (message) => {
 credentials.ensureApiKey = async () => {};
 runner.runCapture = (command) => {
   if (command.includes("command -v ollama")) return "/usr/bin/ollama";
-  if (command.includes("localhost:11434/api/tags")) return JSON.stringify({ models: [{ name: "nemotron-3-nano:30b" }] });
+  if (command.includes("localhost:" + OLLAMA_PORT + "/api/tags")) return JSON.stringify({ models: [{ name: "nemotron-3-nano:30b" }] });
   if (command.includes("ollama list")) return "nemotron-3-nano:30b  abc  24 GB  now\\nqwen3:32b  def  20 GB  now";
-  if (command.includes("localhost:8000/v1/models")) return "";
+  if (command.includes("localhost:" + VLLM_PORT + "/v1/models")) return "";
   return "";
 };
 registry.updateSandbox = (_name, update) => updates.push(update);
diff --git a/test/preflight.test.js b/test/preflight.test.js
index 6471d7983..2150a43b9 100644
--- a/test/preflight.test.js
+++ b/test/preflight.test.js
@@ -6,6 +6,7 @@ const assert = require("node:assert/strict");
 
 const net = require("net");
 const { checkPortAvailable } = require("../bin/lib/preflight");
+const { DASHBOARD_PORT } = require("../bin/lib/ports");
 
 describe("checkPortAvailable", () => {
   it("falls through to net probe when lsof output is empty", async () => {
@@ -104,7 +105,7 @@ describe("checkPortAvailable", () => {
     assert.equal(result.ok, true);
   });
 
-  it("defaults to port 18789 when no args given", async () => {
+  it(`defaults to port ${DASHBOARD_PORT} when no args given`, async () => {
     // Should not throw — just verify it returns a valid result object
     const result = await checkPortAvailable();
     assert.equal(typeof result.ok, "boolean");
diff --git a/test/runtime-shell.test.js b/test/runtime-shell.test.js
index 979460b98..150cd0ae7 100644
--- a/test/runtime-shell.test.js
+++ b/test/runtime-shell.test.js
@@ -119,13 +119,13 @@ describe("shell runtime helpers", () => {
   it("returns the vllm-local base URL", () => {
     const result = runShell(`source "${RUNTIME_SH}"; get_local_provider_base_url vllm-local`);
     assert.equal(result.status, 0);
-    assert.equal(result.stdout.trim(), "http://host.openshell.internal:8000/v1");
+    assert.equal(result.stdout.trim(), `http://host.openshell.internal:${process.env.NEMOCLAW_VLLM_PORT || "8000"}/v1`);
   });
 
   it("returns the ollama-local base URL", () => {
     const result = runShell(`source "${RUNTIME_SH}"; get_local_provider_base_url ollama-local`);
     assert.equal(result.status, 0);
-    assert.equal(result.stdout.trim(), "http://host.openshell.internal:11434/v1");
+    assert.equal(result.stdout.trim(), `http://host.openshell.internal:${process.env.NEMOCLAW_OLLAMA_PORT || "11434"}/v1`);
   });
 
   it("rejects unknown local providers", () => {
diff --git a/uninstall.sh b/uninstall.sh
index 9b35cc484..bc7835a23 100755
--- a/uninstall.sh
+++ b/uninstall.sh
@@ -25,6 +25,29 @@ warn() { echo -e "${YELLOW}[uninstall]${NC} $1"; }
 fail() { echo -e "${RED}[uninstall]${NC} $1"; exit 1; }
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# ── Load .env so custom port overrides are visible ──────────────────
+_load_env() {
+  local env_file="$1"
+  [[ -f "$env_file" ]] || return 0
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    line="${line%%#*}"
+    line="${line#"${line%%[![:space:]]*}"}"
+    line="${line%"${line##*[![:space:]]}"}"
+    [[ -z "$line" ]] && continue
+    [[ "$line" == *=* ]] || continue
+    local key="${line%%=*}"
+    local val="${line#*=}"
+    val="${val#\"}" ; val="${val%\"}"
+    val="${val#\'}" ; val="${val%\'}"
+    if [[ -z "${!key+x}" ]]; then
+      export "$key=$val"
+    fi
+  done < "$env_file"
+}
+_load_env "$SCRIPT_DIR/.env.local"
+_load_env "$SCRIPT_DIR/.env"
+
 NEMOCLAW_STATE_DIR="${HOME}/.nemoclaw"
 OPENSHELL_CONFIG_DIR="${HOME}/.config/openshell"
 NEMOCLAW_CONFIG_DIR="${HOME}/.config/nemoclaw"
@@ -165,7 +188,7 @@ stop_openshell_forward_processes() {
   while IFS= read -r pid; do
     [ -n "$pid" ] || continue
     pids+=("$pid")
-  done < <(pgrep -f 'openshell.*forward.*18789' 2>/dev/null || true)
+  done < <(pgrep -f "openshell.*forward.*${NEMOCLAW_DASHBOARD_PORT:-18789}" 2>/dev/null || true)
 
   if [ "${#pids[@]}" -eq 0 ]; then
     info "No local OpenShell forward processes found"