openportal 0.1.30 → 0.1.32

package/dist/index.js

@@ -2,7 +2,15 @@
 // @bun
 
 // src/index.ts
-import { existsSync, readFileSync, writeFileSync } from "fs";
+import {
+  closeSync,
+  existsSync,
+  openSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+  writeSync
+} from "fs";
 
 // ../../node_modules/.bun/get-port-please@3.2.0/node_modules/get-port-please/dist/index.mjs
 import { createServer, Server } from "net";
@@ -263,9 +271,13 @@ import { fileURLToPath } from "url";
 var __filename2 = fileURLToPath(import.meta.url);
 var __dirname2 = dirname(__filename2);
 var CONFIG_PATH = join(homedir(), ".portal.json");
+var CONFIG_LOCK_PATH = `${CONFIG_PATH}.lock`;
 var DEFAULT_HOSTNAME = "0.0.0.0";
+var DEFAULT_CODEX_HOSTNAME = "127.0.0.1";
 var DEFAULT_PORT = 3000;
 var DEFAULT_OPENCODE_PORT = 4000;
+var DEFAULT_CODEX_PORT = 4500;
+var DEFAULT_CLAUDE_PORT = 4600;
 var WEB_SERVER_PATH = join(__dirname2, "..", "web", "server", "index.mjs");
 function readConfig() {
   try {
@@ -273,6 +285,9 @@ function readConfig() {
       const config = JSON.parse(readFileSync(CONFIG_PATH, "utf-8"));
       config.instances = config.instances.map((instance) => ({
         ...instance,
+        provider: instance.provider ?? "opencode",
+        backendPort: instance.backendPort ?? instance.opencodePort,
+        backendPid: instance.backendPid ?? instance.opencodePid ?? null,
         opencodePid: instance.opencodePid ?? null,
         webPid: instance.webPid ?? null
       }));
@@ -286,6 +301,59 @@ function readConfig() {
 function writeConfig(config) {
   writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
 }
+function acquireConfigLock(timeoutMs = 30000) {
+  const start = Date.now();
+  let backoff = 50;
+  while (true) {
+    try {
+      const fd = openSync(CONFIG_LOCK_PATH, "wx");
+      writeSync(fd, String(process.pid));
+      closeSync(fd);
+      return () => {
+        try {
+          unlinkSync(CONFIG_LOCK_PATH);
+        } catch {}
+      };
+    } catch (err) {
+      if (err.code !== "EEXIST")
+        throw err;
+      if (tryStealStaleLock())
+        continue;
+      if (Date.now() - start > timeoutMs) {
+        throw new Error(`Could not acquire ${CONFIG_LOCK_PATH} within ${timeoutMs}ms.`);
+      }
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, backoff);
+      backoff = Math.min(backoff * 2, 250);
+    }
+  }
+}
+function tryStealStaleLock() {
+  let holderPid;
+  try {
+    holderPid = parseInt(readFileSync(CONFIG_LOCK_PATH, "utf-8"), 10);
+  } catch {
+    return true;
+  }
+  if (!Number.isFinite(holderPid) || holderPid <= 0)
+    return false;
+  if (isProcessRunning(holderPid))
+    return false;
+  try {
+    unlinkSync(CONFIG_LOCK_PATH);
+  } catch {}
+  return true;
+}
+function mutateConfig(mutator) {
+  const release = acquireConfigLock();
+  try {
+    const config = readConfig();
+    const result = mutator(config);
+    writeConfig(config);
+    return result;
+  } finally {
+    release();
+  }
+}
 function generateId() {
   return Math.random().toString(36).substring(2, 10);
 }
@@ -299,18 +367,51 @@ function isProcessRunning(pid) {
     return false;
   }
 }
+function getInstanceProvider(instance) {
+  return instance.provider ?? "opencode";
+}
+function getInstanceBackendPort(instance) {
+  return instance.backendPort ?? instance.opencodePort;
+}
+function getInstanceBackendPid(instance) {
+  return instance.backendPid ?? instance.opencodePid ?? null;
+}
 function isInstanceRunning(instance) {
-  return isProcessRunning(instance.opencodePid) || isProcessRunning(instance.webPid);
+  if (getInstanceProvider(instance) === "claude") {
+    return isProcessRunning(getInstanceBackendPid(instance)) || isProcessRunning(instance.webPid);
+  }
+  return isProcessRunning(getInstanceBackendPid(instance)) || isProcessRunning(instance.webPid);
+}
+function providerName(provider) {
+  if (provider === "codex")
+    return "Codex";
+  if (provider === "claude")
+    return "Claude";
+  return "OpenCode";
+}
+function backendName(provider) {
+  if (provider === "codex")
+    return "Codex app-server";
+  if (provider === "claude")
+    return "Claude SDK";
+  return "OpenCode API";
+}
+function backendLocation(provider, host, port) {
+  if (provider === "claude") {
+    return `Claude SDK managed by Web UI (instance key: ${port})`;
+  }
+  const displayHost = host === "0.0.0.0" ? "localhost" : host;
+  return `http://${displayHost}:${port}`;
 }
 function printHelp() {
   console.log(`
-OpenPortal CLI - Run OpenCode with a web UI
+OpenPortal CLI - Run coding agents with a web UI
 
 Usage: openportal [command] [options]
 
 Commands:
-  (default)       Start OpenCode server and Web UI
-  run [options]   Start only OpenCode server (no Web UI)
+  (default)       Start provider backend and Web UI
+  run [provider]  Start only a provider backend (opencode, codex, or claude)
   stop            Stop running instances
   list, ls        List running instances
   clean           Clean up stale entries
@@ -319,15 +420,27 @@ Options:
   -h, --help              Show this help message
   -d, --directory <path>  Working directory (default: current directory)
   -p, --port <port>       Web UI port (default: 3000)
+  --provider <provider>   Backend provider: opencode, codex, or claude (default: opencode)
+  --backend-port <port>   Backend server port for the selected provider
   --opencode-port <port>  OpenCode server port (default: 4000)
+  --codex-port <port>     Codex app-server port (default: 4500)
+  --claude-port <port>    Claude instance key (default: 4600)
+  --claude-binary <path>  Claude binary path (default: claude)
+  --claude-home <path>    Custom HOME for Claude
+  --claude-args <args>    Extra Claude launch args
   --hostname <host>       Hostname to bind (default: 0.0.0.0)
   --name <name>           Instance name
 
 Examples:
   openportal                               Start OpenCode + Web UI
+  openportal --provider codex              Start Codex + Web UI
+  openportal --provider claude             Start Claude + Web UI
   openportal .                             Start OpenCode + Web UI in current dir
   openportal run                           Start only OpenCode server
-  openportal run -d ./my-project           Start OpenCode in specific directory
+  openportal run opencode                  Start only OpenCode server
+  openportal run codex                     Start only Codex app-server
+  openportal run claude                    Keep Claude SDK backend registered
+  openportal run codex -d ./my-project     Start Codex in specific directory
   openportal --port 8080                   Use custom web UI port
   openportal stop                          Stop running instances
   openportal list                          List running instances
@@ -366,6 +479,36 @@ function parseArgs() {
   }
   return { args, flags };
 }
+function parseProvider(value) {
+  if (typeof value !== "string")
+    return null;
+  const normalized = value.toLowerCase();
+  if (normalized === "opencode" || normalized === "codex" || normalized === "claude") {
+    return normalized;
+  }
+  return null;
+}
+function getProviderOption(options) {
+  return parseProvider(options.provider) ?? "opencode";
+}
+async function getBackendPort(provider, options, hostname) {
+  const explicit = options["backend-port"] ?? (provider === "codex" ? options["codex-port"] : provider === "claude" ? options["claude-port"] : options["opencode-port"]);
+  if (explicit) {
+    return parseInt(explicit, 10);
+  }
+  if (provider === "claude") {
+    const used = new Set(readConfig().instances.filter((instance) => getInstanceProvider(instance) === "claude" && isInstanceRunning(instance)).map((instance) => getInstanceBackendPort(instance)));
+    let port = DEFAULT_CLAUDE_PORT;
+    while (used.has(port) && port < 65535) {
+      port += 1;
+    }
+    return port;
+  }
+  return getPort({
+    host: hostname,
+    port: provider === "codex" ? DEFAULT_CODEX_PORT : DEFAULT_OPENCODE_PORT
+  });
+}
 async function startOpenCodeServer(directory, opencodePort, hostname) {
   console.log(`Starting OpenCode server...`);
   const proc = Bun.spawn([
@@ -382,6 +525,30 @@ async function startOpenCodeServer(directory, opencodePort, hostname) {
   });
   return proc.pid;
 }
+async function startCodexServer(directory, codexPort) {
+  console.log(`Starting Codex app-server...`);
+  const proc = Bun.spawn([
+    "codex",
+    "app-server",
+    "--listen",
+    `ws://${DEFAULT_CODEX_HOSTNAME}:${codexPort}`
+  ], {
+    cwd: directory,
+    stdio: ["ignore", "pipe", "pipe"],
+    env: { ...process.env }
+  });
+  return proc.pid;
+}
+async function startBackendServer(provider, directory, backendPort, hostname) {
+  if (provider === "codex") {
+    return startCodexServer(directory, backendPort);
+  }
+  if (provider === "claude") {
+    console.log(`Claude SDK will be managed by the Web UI.`);
+    return null;
+  }
+  return startOpenCodeServer(directory, backendPort, hostname);
+}
 async function startWebServer(port, hostname) {
   console.log(`Starting Web UI server...`);
   const proc = Bun.spawn(["bun", "run", WEB_SERVER_PATH], {
@@ -397,30 +564,54 @@ async function startWebServer(port, hostname) {
   });
   return proc.pid;
 }
+async function waitForClaudeRegistration(instance) {
+  console.log(`
+Claude SDK registration is active.`);
+  console.log("Keep this command running while you use this Claude instance.");
+  console.log("Press Ctrl-C to stop it.");
+  await new Promise((resolve2) => {
+    const interval = setInterval(() => {}, 60 * 60 * 1000);
+    let settled = false;
+    const stop = () => {
+      if (settled)
+        return;
+      settled = true;
+      clearInterval(interval);
+      resolve2();
+    };
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+  });
+  mutateConfig((config) => {
+    config.instances = config.instances.filter((i) => i.id !== instance.id);
+  });
+  console.log(`
+Stopped Claude SDK backend: ${instance.name}`);
+}
 async function cmdDefault(options) {
+  const provider = getProviderOption(options);
   const hostname = options.hostname || DEFAULT_HOSTNAME;
   const directory = resolve(options.directory || options.d || process.cwd());
-  const name = options.name || directory.split("/").pop() || "opencode";
+  const name = options.name || directory.split("/").pop() || provider;
   const port = options.port || options.p ? parseInt(options.port || options.p, 10) : await getPort({ host: hostname, port: DEFAULT_PORT });
-  const opencodePort = options["opencode-port"] ? parseInt(options["opencode-port"], 10) : await getPort({ host: hostname, port: DEFAULT_OPENCODE_PORT });
-  const config = readConfig();
-  const existingIndex = config.instances.findIndex((i) => i.directory === directory);
-  if (existingIndex !== -1) {
-    const existing = config.instances[existingIndex];
-    const running = isInstanceRunning(existing);
-    if (running || isProcessRunning(existing.webPid)) {
-      console.log(`OpenPortal is already running for this directory.`);
-      console.log(`  Name: ${existing.name}`);
-      console.log(`  Web UI Port: ${existing.port ?? "N/A"}`);
-      console.log(`  OpenCode Port: ${existing.opencodePort}`);
-      if (existing.port) {
-        console.log(`
+  const backendHost = provider === "codex" ? DEFAULT_CODEX_HOSTNAME : hostname;
+  const backendPort = await getBackendPort(provider, options, backendHost);
+  const existing = readConfig().instances.find((i) => i.directory === directory && getInstanceProvider(i) === provider);
+  const existingIsActive = existing && (provider === "claude" ? isProcessRunning(existing.webPid) : isInstanceRunning(existing));
+  if (existing && existingIsActive) {
+    const existingProvider = getInstanceProvider(existing);
+    const existingBackendPort = getInstanceBackendPort(existing);
+    console.log(`OpenPortal is already running for this directory.`);
+    console.log(`  Name: ${existing.name}`);
+    console.log(`  Provider: ${existingProvider}`);
+    console.log(`  Web UI Port: ${existing.port ?? "N/A"}`);
+    console.log(`  ${existingProvider === "claude" ? "Instance Key" : "Backend Port"}: ${existingBackendPort}`);
+    if (existing.port) {
+      console.log(`
 \uD83D\uDCF1 Access OpenPortal at http://${hostname === "0.0.0.0" ? "localhost" : hostname}:${existing.port}`);
-      }
-      console.log(`\uD83D\uDD27 OpenCode API at http://${hostname === "0.0.0.0" ? "localhost" : hostname}:${existing.opencodePort}`);
-      return;
     }
-    config.instances.splice(existingIndex, 1);
+    console.log(`\uD83D\uDD27 ${backendName(existingProvider)} at ${backendLocation(existingProvider, backendHost, existingBackendPort)}`);
+    return;
   }
   if (!existsSync(WEB_SERVER_PATH)) {
     console.error(`\u274C Web server not found at ${WEB_SERVER_PATH}`);
@@ -429,34 +620,49 @@ async function cmdDefault(options) {
   }
   console.log(`Starting OpenPortal...`);
   console.log(`  Name: ${name}`);
+  console.log(`  Provider: ${provider}`);
   console.log(`  Directory: ${directory}`);
   console.log(`  Web UI Port: ${port}`);
-  console.log(`  OpenCode Port: ${opencodePort}`);
+  console.log(`  ${provider === "claude" ? "Instance Key" : "Backend Port"}: ${backendPort}`);
   console.log(`  Hostname: ${hostname}`);
   try {
-    const opencodePid = await startOpenCodeServer(directory, opencodePort, hostname);
+    const backendPid = await startBackendServer(provider, directory, backendPort, hostname);
     const webPid = await startWebServer(port, hostname);
     const instance = {
       id: generateId(),
       name,
       directory,
       port,
-      opencodePort,
-      hostname,
-      opencodePid,
+      provider,
+      backendPort,
+      backendPid,
+      opencodePort: backendPort,
+      hostname: backendHost,
+      opencodePid: provider === "opencode" ? backendPid : null,
       webPid,
-      startedAt: new Date().toISOString()
+      startedAt: new Date().toISOString(),
+      ...provider === "claude" ? {
+        claudeBinaryPath: options["claude-binary"],
+        claudeHomePath: options["claude-home"],
+        claudeLaunchArgs: options["claude-launch-args"] ?? options["claude-args"]
+      } : {}
     };
-    config.instances.push(instance);
-    writeConfig(config);
+    mutateConfig((config) => {
+      config.instances = config.instances.filter((i) => i.directory !== directory || getInstanceProvider(i) !== provider);
+      config.instances.push(instance);
+    });
     const displayHost = hostname === "0.0.0.0" ? "localhost" : hostname;
     console.log(`
 \u2705 OpenPortal started!`);
-    console.log(`   OpenCode PID: ${opencodePid}`);
+    if (backendPid) {
+      console.log(`   ${providerName(provider)} PID: ${backendPid}`);
+    } else {
+      console.log(`   ${backendName(provider)}: managed by Web UI`);
+    }
     console.log(`   Web UI PID: ${webPid}`);
     console.log(`
 \uD83D\uDCF1 Access OpenPortal at http://${displayHost}:${port}`);
-    console.log(`\uD83D\uDD27 OpenCode API at http://${displayHost}:${opencodePort}`);
+    console.log(`\uD83D\uDD27 ${backendName(provider)} at ${backendLocation(provider, backendHost, backendPort)}`);
   } catch (error) {
     if (error instanceof Error) {
       console.error(`
@@ -465,86 +671,124 @@ async function cmdDefault(options) {
     process.exit(1);
   }
 }
-async function cmdRun(options) {
+async function cmdRun(options, provider = getProviderOption(options)) {
   const hostname = options.hostname || DEFAULT_HOSTNAME;
   const directory = resolve(options.directory || options.d || process.cwd());
-  const name = options.name || directory.split("/").pop() || "opencode";
-  const opencodePort = options["opencode-port"] ? parseInt(options["opencode-port"], 10) : await getPort({ host: hostname, port: DEFAULT_OPENCODE_PORT });
-  const config = readConfig();
-  const existingIndex = config.instances.findIndex((i) => i.directory === directory);
-  if (existingIndex !== -1) {
-    const existing = config.instances[existingIndex];
-    const running = isInstanceRunning(existing);
-    if (running) {
-      console.log(`OpenCode is already running for this directory.`);
-      console.log(`  Name: ${existing.name}`);
-      console.log(`  OpenCode Port: ${existing.opencodePort}`);
-      console.log(`\uD83D\uDD27 OpenCode API at http://${hostname === "0.0.0.0" ? "localhost" : hostname}:${existing.opencodePort}`);
-      return;
-    }
-    config.instances.splice(existingIndex, 1);
+  const name = options.name || directory.split("/").pop() || provider;
+  const backendHost = provider === "codex" ? DEFAULT_CODEX_HOSTNAME : hostname;
+  const backendPort = await getBackendPort(provider, options, backendHost);
+  const existing = readConfig().instances.find((i) => i.directory === directory && getInstanceProvider(i) === provider);
+  if (existing && isInstanceRunning(existing)) {
+    const existingBackendPort = getInstanceBackendPort(existing);
+    console.log(`${providerName(provider)} is already running for this directory.`);
+    console.log(`  Name: ${existing.name}`);
+    console.log(`  Provider: ${getInstanceProvider(existing)}`);
+    console.log(`  ${provider === "claude" ? "Instance Key" : "Backend Port"}: ${existingBackendPort}`);
+    console.log(`\uD83D\uDD27 ${backendName(provider)} at ${backendLocation(provider, backendHost, existingBackendPort)}`);
+    return;
   }
-  console.log(`Starting OpenCode server...`);
+  console.log(provider === "claude" ? "Registering Claude SDK backend..." : `Starting ${backendName(provider)}...`);
   console.log(`  Name: ${name}`);
+  console.log(`  Provider: ${provider}`);
   console.log(`  Directory: ${directory}`);
-  console.log(`  OpenCode Port: ${opencodePort}`);
-  console.log(`  Hostname: ${hostname}`);
+  console.log(`  ${provider === "claude" ? "Instance Key" : "Backend Port"}: ${backendPort}`);
+  console.log(`  Hostname: ${backendHost}`);
   try {
-    const opencodePid = await startOpenCodeServer(directory, opencodePort, hostname);
+    if (provider === "claude") {
+      const instance2 = {
+        id: generateId(),
+        name,
+        directory,
+        port: null,
+        provider,
+        backendPort,
+        backendPid: process.pid,
+        opencodePort: backendPort,
+        hostname: backendHost,
+        opencodePid: null,
+        webPid: null,
+        startedAt: new Date().toISOString(),
+        claudeBinaryPath: options["claude-binary"],
+        claudeHomePath: options["claude-home"],
+        claudeLaunchArgs: options["claude-launch-args"] ?? options["claude-args"]
+      };
+      mutateConfig((config) => {
+        config.instances = config.instances.filter((i) => i.directory !== directory || getInstanceProvider(i) !== provider);
+        config.instances.push(instance2);
+      });
+      console.log(`
+\u2705 Claude SDK backend registered!`);
+      console.log(`   Claude holder PID: ${process.pid}`);
+      console.log(`\uD83D\uDD27 ${backendName(provider)} at ${backendLocation(provider, backendHost, backendPort)}`);
+      await waitForClaudeRegistration(instance2);
+      return;
+    }
+    const backendPid = await startBackendServer(provider, directory, backendPort, hostname);
     const instance = {
       id: generateId(),
       name,
       directory,
       port: null,
-      opencodePort,
-      hostname,
-      opencodePid,
+      provider,
+      backendPort,
+      backendPid,
+      opencodePort: backendPort,
+      hostname: backendHost,
+      opencodePid: provider === "opencode" ? backendPid : null,
       webPid: null,
       startedAt: new Date().toISOString()
     };
-    config.instances.push(instance);
-    writeConfig(config);
-    const displayHost = hostname === "0.0.0.0" ? "localhost" : hostname;
+    mutateConfig((config) => {
+      config.instances = config.instances.filter((i) => i.directory !== directory || getInstanceProvider(i) !== provider);
+      config.instances.push(instance);
+    });
     console.log(`
-\u2705 OpenCode server started!`);
-    console.log(`   OpenCode PID: ${opencodePid}`);
-    console.log(`\uD83D\uDD27 OpenCode API at http://${displayHost}:${opencodePort}`);
+\u2705 ${backendName(provider)} started!`);
+    if (backendPid) {
+      console.log(`   ${providerName(provider)} PID: ${backendPid}`);
+    }
+    console.log(`\uD83D\uDD27 ${backendName(provider)} at ${backendLocation(provider, backendHost, backendPort)}`);
   } catch (error) {
     if (error instanceof Error) {
       console.error(`
-\u274C Failed to start OpenCode: ${error.message}`);
+\u274C Failed to start ${providerName(provider)}: ${error.message}`);
     }
     process.exit(1);
   }
 }
 async function cmdStop(options) {
-  const config = readConfig();
   const directory = options.directory || options.d ? resolve(options.directory || options.d) : process.cwd();
-  const instance = options.name ? config.instances.find((i) => i.name === options.name) : config.instances.find((i) => i.directory === directory);
-  if (!instance) {
+  const removed = mutateConfig((config) => {
+    const instance = options.name ? config.instances.find((i) => i.name === options.name) : config.instances.find((i) => i.directory === directory);
+    if (!instance)
+      return null;
+    config.instances = config.instances.filter((i) => i.id !== instance.id);
+    return instance;
+  });
+  if (!removed) {
     console.error("No instance found.");
     process.exit(1);
   }
-  if (instance.opencodePid !== null) {
+  const provider = getInstanceProvider(removed);
+  const backendPid = getInstanceBackendPid(removed);
+  if (backendPid !== null) {
     try {
-      process.kill(instance.opencodePid, "SIGTERM");
-      console.log(`Stopped OpenCode (PID: ${instance.opencodePid})`);
+      process.kill(backendPid, "SIGTERM");
+      console.log(`Stopped ${providerName(provider)} (PID: ${backendPid})`);
     } catch {
-      console.log("OpenCode was already stopped.");
+      console.log(`${providerName(provider)} was already stopped.`);
     }
   }
-  if (instance.webPid !== null) {
+  if (removed.webPid !== null) {
     try {
-      process.kill(instance.webPid, "SIGTERM");
-      console.log(`Stopped Web UI (PID: ${instance.webPid})`);
+      process.kill(removed.webPid, "SIGTERM");
+      console.log(`Stopped Web UI (PID: ${removed.webPid})`);
     } catch {
       console.log("Web UI was already stopped.");
     }
   }
-  config.instances = config.instances.filter((i) => i.id !== instance.id);
-  writeConfig(config);
   console.log(`
-Stopped: ${instance.name}`);
+Stopped: ${removed.name}`);
 }
 async function cmdList() {
   const config = readConfig();
@@ -555,45 +799,56 @@ async function cmdList() {
   console.log(`
 OpenPortal Instances:
 `);
-  console.log("ID\t\tNAME\t\t\tPORT\tOPENCODE\tSTATUS\t\tDIRECTORY");
+  console.log("ID\t\tNAME\t\t\tPROVIDER\tPORT\tBACKEND\tSTATUS\t\tDIRECTORY");
   console.log("-".repeat(110));
-  const validInstances = [];
+  const liveIds = new Set;
   for (const instance of config.instances) {
-    const opencodeRunning = isProcessRunning(instance.opencodePid);
+    const provider = getInstanceProvider(instance);
+    const backendRunning = isProcessRunning(getInstanceBackendPid(instance));
     const webRunning = isProcessRunning(instance.webPid);
     let status = "stopped";
-    if (opencodeRunning && webRunning)
+    if (provider === "claude") {
+      if (webRunning)
+        status = "running";
+      else if (backendRunning)
+        status = "registered";
+    } else if (backendRunning && webRunning)
       status = "running";
-    else if (opencodeRunning)
-      status = "opencode";
+    else if (backendRunning)
+      status = provider;
     else if (webRunning)
       status = "web only";
-    if (opencodeRunning || webRunning) {
-      validInstances.push(instance);
+    if (backendRunning || webRunning) {
+      liveIds.add(instance.id);
     }
     const portDisplay = instance.port ?? "-";
-    console.log(`${instance.id}	${instance.name.padEnd(16)}	${String(portDisplay).padEnd(4)}	${instance.opencodePort}		${status.padEnd(12)}	${instance.directory}`);
+    console.log(`${instance.id}	${instance.name.padEnd(16)}	${provider.padEnd(8)}	${String(portDisplay).padEnd(4)}	${getInstanceBackendPort(instance)}		${status.padEnd(12)}	${instance.directory}`);
   }
-  if (validInstances.length !== config.instances.length) {
-    config.instances = validInstances;
-    writeConfig(config);
+  if (liveIds.size !== config.instances.length) {
+    mutateConfig((latest) => {
+      latest.instances = latest.instances.filter((i) => liveIds.has(i.id) || isInstanceRunning(i));
+    });
   }
 }
 async function cmdClean() {
-  const config = readConfig();
-  const validInstances = [];
-  for (const instance of config.instances) {
-    const running = isInstanceRunning(instance);
-    if (running || isProcessRunning(instance.webPid)) {
-      validInstances.push(instance);
-    } else {
-      console.log(`Removed stale entry: ${instance.name}`);
+  const result = mutateConfig((config) => {
+    const valid = [];
+    const removed = [];
+    for (const instance of config.instances) {
+      if (isInstanceRunning(instance)) {
+        valid.push(instance);
+      } else {
+        removed.push(instance.name);
+      }
     }
+    config.instances = valid;
+    return { valid, removed };
+  });
+  for (const name of result.removed) {
+    console.log(`Removed stale entry: ${name}`);
   }
-  config.instances = validInstances;
-  writeConfig(config);
   console.log(`
-Config cleaned. ${validInstances.length} active instance(s).`);
+Config cleaned. ${result.valid.length} active instance(s).`);
 }
 async function main() {
   const { args, flags } = parseArgs();
@@ -602,17 +857,27 @@ async function main() {
     return;
   }
   const command = args[0]?.toLowerCase();
-  if (!command || command === "." || command.startsWith("/") || command.startsWith("./")) {
+  const commandProvider = parseProvider(command);
+  if (!command || command === "." || command.startsWith("/") || command.startsWith("./") || commandProvider) {
     if (command && command !== ".") {
-      flags.directory = command;
+      if (commandProvider) {
+        flags.provider = commandProvider;
+      } else {
+        flags.directory = command;
+      }
     }
     await cmdDefault(flags);
     return;
   }
   switch (command) {
-    case "run":
-      await cmdRun(flags);
+    case "run": {
+      const provider = parseProvider(args[1]) ?? getProviderOption(flags);
+      if (args[1] && !parseProvider(args[1])) {
+        flags.directory = args[1];
+      }
+      await cmdRun(flags, provider);
       break;
+    }
     case "stop":
       await cmdStop(flags);
       break;