openclaw-dev 0.1.0

package/assets/docker-compose.instance.yml

@@ -0,0 +1,101 @@
+services:
+  openclaw-init:
+    image: ${OPENCLAW_IMAGE:?Set OPENCLAW_IMAGE in the stack env file}
+    user: "0:0"
+    entrypoint:
+      [
+        "sh",
+        "-lc",
+        "mkdir -p /home/node/.openclaw/workspace && chown -R 1000:1000 /home/node",
+      ]
+    volumes:
+      - openclaw-home:/home/node
+      - openclaw-state:/home/node/.openclaw
+      - openclaw-workspace:/home/node/.openclaw/workspace
+    restart: "no"
+
+  openclaw-gateway:
+    image: ${OPENCLAW_IMAGE:?Set OPENCLAW_IMAGE in the stack env file}
+    environment:
+      HOME: /home/node
+      TERM: xterm-256color
+      TZ: ${OPENCLAW_TZ:-UTC}
+      OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN:?Set OPENCLAW_GATEWAY_TOKEN in the stack env file}
+      OPENCLAW_ALLOW_INSECURE_PRIVATE_WS: ${OPENCLAW_ALLOW_INSECURE_PRIVATE_WS:-}
+      CLAUDE_AI_SESSION_KEY: ${CLAUDE_AI_SESSION_KEY:-}
+      CLAUDE_WEB_SESSION_KEY: ${CLAUDE_WEB_SESSION_KEY:-}
+      CLAUDE_WEB_COOKIE: ${CLAUDE_WEB_COOKIE:-}
+    volumes:
+      - openclaw-home:/home/node
+      - openclaw-state:/home/node/.openclaw
+      - openclaw-workspace:/home/node/.openclaw/workspace
+    ports:
+      - "${OPENCLAW_GATEWAY_PORT:-18789}:18789"
+      - "${OPENCLAW_BRIDGE_PORT:-18790}:18790"
+    init: true
+    restart: unless-stopped
+    stop_grace_period: 30s
+    depends_on:
+      openclaw-init:
+        condition: service_completed_successfully
+    command:
+      [
+        "node",
+        "dist/index.js",
+        "gateway",
+        "--allow-unconfigured",
+        "--bind",
+        "${OPENCLAW_GATEWAY_BIND:-lan}",
+        "--port",
+        "18789",
+      ]
+    healthcheck:
+      test:
+        [
+          "CMD",
+          "node",
+          "-e",
+          "fetch('http://127.0.0.1:18789/healthz').then((r)=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))",
+        ]
+      interval: 30s
+      timeout: 5s
+      retries: 5
+      start_period: 20s
+
+  openclaw-cli:
+    image: ${OPENCLAW_IMAGE:?Set OPENCLAW_IMAGE in the stack env file}
+    network_mode: "service:openclaw-gateway"
+    cap_drop:
+      - NET_RAW
+      - NET_ADMIN
+    security_opt:
+      - no-new-privileges:true
+    environment:
+      HOME: /home/node
+      TERM: xterm-256color
+      TZ: ${OPENCLAW_TZ:-UTC}
+      BROWSER: echo
+      OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN:?Set OPENCLAW_GATEWAY_TOKEN in the stack env file}
+      OPENCLAW_ALLOW_INSECURE_PRIVATE_WS: ${OPENCLAW_ALLOW_INSECURE_PRIVATE_WS:-}
+      CLAUDE_AI_SESSION_KEY: ${CLAUDE_AI_SESSION_KEY:-}
+      CLAUDE_WEB_SESSION_KEY: ${CLAUDE_WEB_SESSION_KEY:-}
+      CLAUDE_WEB_COOKIE: ${CLAUDE_WEB_COOKIE:-}
+    volumes:
+      - openclaw-home:/home/node
+      - openclaw-state:/home/node/.openclaw
+      - openclaw-workspace:/home/node/.openclaw/workspace
+    stdin_open: true
+    tty: true
+    init: true
+    entrypoint: ["node", "dist/index.js"]
+    depends_on:
+      openclaw-gateway:
+        condition: service_healthy
+
+volumes:
+  openclaw-home:
+    name: ${OPENCLAW_HOME_VOLUME:?Set OPENCLAW_HOME_VOLUME}
+  openclaw-state:
+    name: ${OPENCLAW_STATE_VOLUME:?Set OPENCLAW_STATE_VOLUME}
+  openclaw-workspace:
+    name: ${OPENCLAW_WORKSPACE_VOLUME:?Set OPENCLAW_WORKSPACE_VOLUME}

package/bin/ocdev

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { main } from "../src/cli.mjs";
+
+main(process.argv.slice(2)).catch((error) => {
+  console.error(error?.message || String(error));
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "openclaw-dev",
+  "version": "0.1.0",
+  "description": "CLI launcher for OpenClaw developer instances",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iAladdin/openclaw-developer-images.git"
+  },
+  "bin": {
+    "ocdev": "bin/ocdev"
+  },
+  "files": [
+    "assets",
+    "bin",
+    "src"
+  ],
+  "engines": {
+    "node": ">=22.16.0"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,481 @@
+import {
+  assertDockerAvailable,
+  collectComposeDiagnostics,
+  isComposeServiceRunning,
+  runDockerCompose,
+  runDockerComposeExec
+} from "./lib/docker.mjs";
+import {
+  buildConfigFromArgs,
+  defaultInstanceName,
+  hasFlag,
+  readEnvFile,
+  readFlag,
+  readPositional,
+  resolveInstancesRoot,
+  stackPaths,
+  writeStackFiles
+} from "./lib/instance.mjs";
+import { resolvePortPlan } from "./lib/ports.mjs";
+
+export async function main(argv, { cwd = process.cwd() } = {}) {
+  const command = argv[0] || "help";
+
+  if (command === "help" || hasFlag(argv, "-h", "--help")) {
+    printHelp(cwd);
+    return;
+  }
+
+  if (command === "up") {
+    await up(argv, { cwd });
+    return;
+  }
+
+  if (command === "down") {
+    await down(argv, { cwd });
+    return;
+  }
+
+  if (command === "logs") {
+    await logs(argv, { cwd });
+    return;
+  }
+
+  if (command === "token") {
+    await token(argv, { cwd });
+    return;
+  }
+
+  if (command === "approve") {
+    await approve(argv, { cwd });
+    return;
+  }
+
+  if (command === "exec") {
+    await execInContainer(argv, { cwd });
+    return;
+  }
+
+  if (command === "claw") {
+    await claw(argv, { cwd });
+    return;
+  }
+
+  throw new Error(`Unknown command: ${command}\n\n${helpText(cwd)}`);
+}
+
+async function up(argv, { cwd }) {
+  await assertDockerAvailable();
+
+  const requestedInstance = readFlag(argv, "--name") || readPositional(argv, 1) || defaultInstanceName(cwd);
+  const instancesRoot = resolveInstancesRoot();
+  const paths = stackPaths({ rootDir: instancesRoot, instance: requestedInstance });
+  const existingEnv = await readEnvFile(paths.envPath);
+  const hasExplicitPortSelection = Boolean(readFlag(argv, "--gateway-port") || readFlag(argv, "--bridge-port"));
+  const preserveExistingPorts =
+    !hasExplicitPortSelection &&
+    Object.keys(existingEnv).length > 0 &&
+    (await isComposeServiceRunning({
+      envFile: paths.envPath,
+      composeFile: paths.composePath,
+      service: "openclaw-gateway"
+    }));
+  const config = buildConfigFromArgs({
+    cwd,
+    argv,
+    defaults: {
+      instance: requestedInstance,
+      existingEnv
+    }
+  });
+  const portPlan = await resolvePortPlan({
+    gatewayPort: config.gatewayPort,
+    bridgePort: config.bridgePort,
+    preserveExistingPorts
+  });
+  config.gatewayPort = portPlan.gatewayPort;
+  config.bridgePort = portPlan.bridgePort;
+
+  const writtenPaths = await writeStackFiles({
+    rootDir: instancesRoot,
+    config,
+    refreshTemplate: hasFlag(argv, "--refresh-template")
+  });
+
+  try {
+    await startComposeWithRetries({
+      argv,
+      config,
+      writtenPaths
+    });
+  } catch (error) {
+    const diagnostics = await collectComposeDiagnostics({
+      envFile: writtenPaths.envPath,
+      composeFile: writtenPaths.composePath
+    });
+    const details = [
+      "OpenClaw developer instance failed to start.",
+      `Instance: ${config.instance}`,
+      `State directory: ${writtenPaths.stackDir}`,
+      "",
+      "Managed file policy:",
+      "- `.env` managed keys are refreshed on `ocdev up`; extra keys are preserved.",
+      "- `docker-compose.instance.yml` and `README.md` are only refreshed when you pass `--refresh-template`.",
+      ""
+    ];
+
+    if (portPlan.shifted) {
+      details.push(
+        `Ports ${portPlan.originalGatewayPort}/${portPlan.originalBridgePort} were unavailable, so ocdev shifted to ${config.gatewayPort}/${config.bridgePort}.`,
+        ""
+      );
+    }
+
+    const composeOutput = `${error.stdout || ""}${error.stderr || ""}`.trim();
+    if (composeOutput) {
+      details.push("Compose output:", composeOutput, "");
+    }
+
+    if (diagnostics) {
+      details.push("Diagnostics:", diagnostics);
+    }
+
+    throw new Error(details.join("\n"));
+  }
+
+  console.log("OpenClaw developer instance is starting.");
+  console.log(`Instance: ${config.instance}`);
+  console.log(`Profile: ${config.profile}`);
+  console.log(`Image: ${config.image}`);
+  console.log(`Control UI: http://127.0.0.1:${config.gatewayPort}`);
+  console.log(`State directory: ${writtenPaths.stackDir}`);
+  if (portPlan.shifted) {
+    console.log(
+      `Ports ${portPlan.originalGatewayPort}/${portPlan.originalBridgePort} were busy, so ocdev shifted to ${config.gatewayPort}/${config.bridgePort}.`
+    );
+  }
+  console.log("");
+  console.log("Managed file policy:");
+  console.log("- `.env` managed keys are refreshed on `ocdev up`; extra keys are preserved.");
+  console.log("- `docker-compose.instance.yml` and `README.md` are only refreshed when you pass `--refresh-template`.");
+  console.log("");
+  console.log("Next steps:");
+  console.log(`- View logs: ocdev logs ${config.instance}`);
+  console.log(`- Show token: ocdev token ${config.instance}`);
+  console.log(`- Approve the first browser device: ocdev approve ${config.instance}`);
+  console.log(`- Run OpenClaw CLI inside the instance: ocdev claw --name ${config.instance} devices list`);
+}
+
+async function startComposeWithRetries({ argv, config, writtenPaths }) {
+  const explicitPorts = Boolean(readFlag(argv, "--gateway-port") || readFlag(argv, "--bridge-port"));
+  let currentPaths = writtenPaths;
+
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    try {
+      await runDockerCompose({
+        envFile: currentPaths.envPath,
+        composeFile: currentPaths.composePath,
+        args: ["up", "-d", "--wait"],
+        capture: true
+      });
+      return;
+    } catch (error) {
+      if (!shouldRetryPortAllocation(error, explicitPorts) || attempt === 2) {
+        throw error;
+      }
+
+      await safeComposeDown(currentPaths);
+
+      const retryPlan = await resolvePortPlan({
+        gatewayPort: config.gatewayPort + 1,
+        bridgePort: config.bridgePort + 1
+      });
+      config.gatewayPort = retryPlan.gatewayPort;
+      config.bridgePort = retryPlan.bridgePort;
+      currentPaths = await writeStackFiles({
+        rootDir: resolveInstancesRoot(),
+        config,
+        refreshTemplate: hasFlag(argv, "--refresh-template")
+      });
+    }
+  }
+}
+
+async function down(argv, { cwd }) {
+  await assertDockerAvailable();
+
+  const instance = readFlag(argv, "--name") || readPositional(argv, 1) || defaultInstanceName(cwd);
+  const paths = stackPaths({ rootDir: resolveInstancesRoot(), instance });
+  const args = ["down"];
+
+  if (hasFlag(argv, "-v", "--volumes")) {
+    args.push("-v");
+  }
+
+  await ensureStackExists(paths);
+  await runDockerCompose({
+    envFile: paths.envPath,
+    composeFile: paths.composePath,
+    args
+  });
+}
+
+async function logs(argv, { cwd }) {
+  await assertDockerAvailable();
+
+  const instance = readFlag(argv, "--name") || readPositional(argv, 1) || defaultInstanceName(cwd);
+  const paths = stackPaths({ rootDir: resolveInstancesRoot(), instance });
+  const service = readFlag(argv, "--service") || "openclaw-gateway";
+
+  await ensureStackExists(paths);
+  await runDockerCompose({
+    envFile: paths.envPath,
+    composeFile: paths.composePath,
+    args: ["logs", "-f", service]
+  });
+}
+
+async function token(argv, { cwd }) {
+  const instance = readFlag(argv, "--name") || readPositional(argv, 1) || defaultInstanceName(cwd);
+  const paths = stackPaths({ rootDir: resolveInstancesRoot(), instance });
+
+  await ensureStackExists(paths);
+
+  const env = await readEnvFile(paths.envPath);
+  if (!env.OPENCLAW_GATEWAY_TOKEN) {
+    throw new Error(`No OPENCLAW_GATEWAY_TOKEN found in ${paths.envPath}`);
+  }
+
+  console.log(env.OPENCLAW_GATEWAY_TOKEN);
+}
+
+async function approve(argv, { cwd }) {
+  await assertDockerAvailable();
+
+  const { instance, requestId } = resolveApproveRequest(argv, { cwd });
+  const paths = stackPaths({ rootDir: resolveInstancesRoot(), instance });
+
+  await ensureStackExists(paths);
+
+  if (requestId && hasFlag(argv, "--latest")) {
+    throw new Error("Use either a specific request ID or `--latest`, not both.");
+  }
+
+  const commandArgs = ["openclaw", "devices", "approve"];
+  if (requestId) {
+    commandArgs.push(requestId);
+  } else {
+    commandArgs.push("--latest");
+  }
+
+  try {
+    const result = await runInstanceExec({
+      paths,
+      service: "openclaw-gateway",
+      commandArgs,
+      tty: false,
+      capture: true
+    });
+    const output = `${result.stdout || ""}${result.stderr || ""}`.trim();
+    if (output) {
+      console.log(output);
+    }
+  } catch (error) {
+    const output = `${error?.stdout || ""}\n${error?.stderr || ""}\n${error?.message || ""}`.trim();
+    if (/No pending device pairing requests to approve/i.test(output)) {
+      throw new Error(
+        `No pending device pairing requests found for instance ${instance}. Open the Control UI first, trigger a browser connection, then run \`ocdev approve ${instance}\` again.`
+      );
+    }
+    throw error;
+  }
+}
+
+async function execInContainer(argv, { cwd }) {
+  await assertDockerAvailable();
+
+  const { instance, commandArgs } = resolveExecRequest(argv, { cwd });
+  const paths = stackPaths({ rootDir: resolveInstancesRoot(), instance });
+  const service = readFlag(argv, "--service") || "openclaw-gateway";
+
+  await ensureStackExists(paths);
+  await runInstanceExec({
+    paths,
+    service,
+    commandArgs,
+    tty: shouldUseTty(argv)
+  });
+}
+
+async function claw(argv, { cwd }) {
+  await assertDockerAvailable();
+
+  const { instance, commandArgs } = resolveClawRequest(argv, { cwd });
+  const paths = stackPaths({ rootDir: resolveInstancesRoot(), instance });
+
+  await ensureStackExists(paths);
+  await runInstanceExec({
+    paths,
+    service: "openclaw-gateway",
+    commandArgs: ["openclaw", ...commandArgs],
+    tty: shouldUseTty(argv)
+  });
+}
+
+async function ensureStackExists(paths) {
+  const env = await readEnvFile(paths.envPath);
+  if (!Object.keys(env).length) {
+    throw new Error(
+      `No stack metadata found for instance ${paths.instance}. Run \`ocdev up --name ${paths.instance}\` first.`
+    );
+  }
+}
+
+async function safeComposeDown(paths) {
+  try {
+    await runDockerCompose({
+      envFile: paths.envPath,
+      composeFile: paths.composePath,
+      args: ["down"],
+      capture: true
+    });
+  } catch {
+    // Best-effort cleanup before a retry.
+  }
+}
+
+function shouldRetryPortAllocation(error, explicitPorts) {
+  if (explicitPorts) {
+    return false;
+  }
+
+  const output = `${error?.stdout || ""}\n${error?.stderr || ""}\n${error?.message || ""}`;
+  return /port is already allocated|Bind for .* failed: port is already allocated/i.test(output);
+}
+
+async function runInstanceExec({
+  paths,
+  service,
+  commandArgs,
+  tty,
+  capture = false
+}) {
+  return runDockerComposeExec({
+    envFile: paths.envPath,
+    composeFile: paths.composePath,
+    service,
+    commandArgs,
+    tty,
+    capture
+  });
+}
+
+function shouldUseTty(argv) {
+  return !hasFlag(argv, "-T", "--no-tty") && process.stdin.isTTY && process.stdout.isTTY;
+}
+
+function splitCommandArgv(argv) {
+  const separatorIndex = argv.indexOf("--");
+  if (separatorIndex === -1) {
+    return {
+      before: argv,
+      after: [],
+      hasSeparator: false
+    };
+  }
+
+  return {
+    before: argv.slice(0, separatorIndex),
+    after: argv.slice(separatorIndex + 1),
+    hasSeparator: true
+  };
+}
+
+export function resolveExecRequest(argv, { cwd }) {
+  const { before, after, hasSeparator } = splitCommandArgv(argv);
+  if (!hasSeparator || !after.length) {
+    throw new Error(
+      `Usage: ocdev exec [instance] [--service <service>] [-T|--no-tty] -- <command...>\n\n${helpText(cwd)}`
+    );
+  }
+
+  return {
+    instance: readFlag(before, "--name") || readPositional(before, 1) || defaultInstanceName(cwd),
+    commandArgs: after
+  };
+}
+
+export function resolveApproveRequest(argv, { cwd }) {
+  const namedInstance = readFlag(argv, "--name");
+  const requestFlag = readFlag(argv, "--request-id");
+  const positionalRequestId = namedInstance ? readPositional(argv, 1) : readPositional(argv, 2);
+
+  if (requestFlag && positionalRequestId) {
+    throw new Error("Use either a positional request ID or `--request-id`, not both.");
+  }
+
+  return {
+    instance: namedInstance || readPositional(argv, 1) || defaultInstanceName(cwd),
+    requestId: requestFlag || positionalRequestId || null
+  };
+}
+
+export function resolveClawRequest(argv, { cwd }) {
+  const { before, after, hasSeparator } = splitCommandArgv(argv);
+  if (hasSeparator) {
+    if (!after.length) {
+      throw new Error(`Usage: ocdev claw [instance] -- <openclaw args...>\n\n${helpText(cwd)}`);
+    }
+
+    return {
+      instance: readFlag(before, "--name") || readPositional(before, 1) || defaultInstanceName(cwd),
+      commandArgs: after
+    };
+  }
+
+  const namedInstance = readFlag(argv, "--name");
+  const commandArgs = [];
+  for (let index = 1; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "--name") {
+      index += 1;
+      continue;
+    }
+    commandArgs.push(token);
+  }
+
+  if (!commandArgs.length) {
+    throw new Error(`Usage: ocdev claw [--name <instance>] <openclaw args...>\n\n${helpText(cwd)}`);
+  }
+
+  return {
+    instance: namedInstance || defaultInstanceName(cwd),
+    commandArgs
+  };
+}
+
+function printHelp(cwd) {
+  console.log(helpText(cwd));
+}
+
+export function helpText(cwd) {
+  const defaultName = defaultInstanceName(cwd);
+
+  return [
+    "ocdev - OpenClaw developer instance launcher",
+    "",
+    "Usage:",
+    "  ocdev up [--name <instance>] [--profile <profile>] [--image <image>] [--gateway-port <port>] [--bridge-port <port>] [--timezone <iana-tz>] [--refresh-template]",
+    "  ocdev down [instance] [--volumes]",
+    "  ocdev logs [instance] [--service <service>]",
+    "  ocdev token [instance]",
+    "  ocdev approve [instance] [requestId|--latest] [--request-id <id>]",
+    "  ocdev exec [instance] [--service <service>] [-T|--no-tty] -- <command...>",
+    "  ocdev claw [--name <instance>] <openclaw args...>",
+    "  ocdev claw [instance] -- <openclaw args...>",
+    "  ocdev help",
+    "",
+    `Defaults: instance=${defaultName}, profile=node-python`,
+    `State root: ${resolveInstancesRoot()}`
+  ].join("\n");
+}

package/src/lib/constants.mjs

@@ -0,0 +1,17 @@
+export const DEFAULT_PROFILE = "node-python";
+export const DEFAULT_GATEWAY_PORT = 18789;
+export const DEFAULT_BRIDGE_PORT_OFFSET = 1;
+export const DEFAULT_IMAGE_REGISTRY = "ghcr.io/ialaddin/openclaw-developer-images";
+
+export const PROFILE_ALIASES = new Map([
+  ["python-node", "node-python"]
+]);
+
+export const SUPPORTED_PROFILES = new Set([
+  "node",
+  "python",
+  "go",
+  "go-python",
+  "node-python",
+  "rust-cpp"
+]);

package/src/lib/docker.mjs

@@ -0,0 +1,151 @@
+import { spawn } from "node:child_process";
+
+export async function assertDockerAvailable() {
+  await runCommand("docker", ["version"], { stdio: "ignore" }).catch(() => {
+    throw new Error("Docker is required but `docker version` failed. Start Docker Desktop or install Docker first.");
+  });
+
+  await runCommand("docker", ["compose", "version"], { stdio: "ignore" }).catch(() => {
+    throw new Error("Docker Compose v2 is required but `docker compose version` failed.");
+  });
+}
+
+export async function runDockerCompose({
+  envFile,
+  composeFile,
+  args,
+  stdio = "inherit",
+  capture = false
+}) {
+  return runCommand("docker", ["compose", "--env-file", envFile, "-f", composeFile, ...args], {
+    stdio,
+    capture
+  });
+}
+
+export async function runDockerComposeExec({
+  envFile,
+  composeFile,
+  service,
+  commandArgs,
+  tty = process.stdin.isTTY && process.stdout.isTTY,
+  stdio = "inherit",
+  capture = false
+}) {
+  const args = ["compose", "--env-file", envFile, "-f", composeFile, "exec"];
+  if (!tty) {
+    args.push("-T");
+  }
+  args.push(service, ...commandArgs);
+
+  return runCommand("docker", args, {
+    stdio,
+    capture
+  });
+}
+
+export async function isComposeServiceRunning({
+  envFile,
+  composeFile,
+  service
+}) {
+  try {
+    const result = await runDockerCompose({
+      envFile,
+      composeFile,
+      args: ["ps", "--services", "--status", "running"],
+      capture: true
+    });
+
+    return result.stdout
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .includes(service);
+  } catch {
+    return false;
+  }
+}
+
+export async function collectComposeDiagnostics({
+  envFile,
+  composeFile,
+  service = "openclaw-gateway"
+}) {
+  const sections = [];
+
+  const psOutput = await tryComposeCommand({
+    envFile,
+    composeFile,
+    args: ["ps", "--all"],
+    label: "docker compose ps --all"
+  });
+  const logsOutput = await tryComposeCommand({
+    envFile,
+    composeFile,
+    args: ["logs", "--tail", "80", service],
+    label: `docker compose logs --tail 80 ${service}`
+  });
+
+  if (psOutput) {
+    sections.push(psOutput);
+  }
+  if (logsOutput) {
+    sections.push(logsOutput);
+  }
+
+  return sections.join("\n\n");
+}
+
+function runCommand(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const capture = Boolean(options.capture);
+    const child = spawn(command, args, {
+      stdio: capture ? "pipe" : options.stdio ?? "pipe"
+    });
+    let stdout = "";
+    let stderr = "";
+
+    if (child.stdout) {
+      child.stdout.on("data", (chunk) => {
+        stdout += chunk.toString();
+      });
+    }
+
+    if (child.stderr) {
+      child.stderr.on("data", (chunk) => {
+        stderr += chunk.toString();
+      });
+    }
+
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      if (code === 0) {
+        resolve({ code: 0, stdout, stderr });
+        return;
+      }
+
+      const error = new Error(`${command} ${args.join(" ")} exited with code ${code ?? 1}`);
+      error.code = code ?? 1;
+      error.stdout = stdout;
+      error.stderr = stderr;
+      reject(error);
+    });
+  });
+}
+
+async function tryComposeCommand({ envFile, composeFile, args, label }) {
+  try {
+    const result = await runDockerCompose({
+      envFile,
+      composeFile,
+      args,
+      capture: true
+    });
+    const output = `${result.stdout}${result.stderr}`.trim();
+    return output ? `${label}\n${output}` : null;
+  } catch (error) {
+    const output = `${error.stdout || ""}${error.stderr || ""}`.trim();
+    return output ? `${label}\n${output}` : null;
+  }
+}

package/src/lib/instance.mjs

@@ -0,0 +1,395 @@
+import crypto from "node:crypto";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  DEFAULT_BRIDGE_PORT_OFFSET,
+  DEFAULT_GATEWAY_PORT,
+  DEFAULT_IMAGE_REGISTRY,
+  DEFAULT_PROFILE,
+  PROFILE_ALIASES,
+  SUPPORTED_PROFILES
+} from "./constants.mjs";
+
+const COMPOSE_TEMPLATE_PATH = new URL("../../assets/docker-compose.instance.yml", import.meta.url);
+const FLAGS_WITH_VALUES = new Set([
+  "--name",
+  "--profile",
+  "--image",
+  "--gateway-port",
+  "--bridge-port",
+  "--timezone",
+  "--service",
+  "--request-id"
+]);
+const MANAGED_ENV_KEYS = [
+  "COMPOSE_PROJECT_NAME",
+  "OPENCLAW_INSTANCE",
+  "OPENCLAW_PROFILE",
+  "OPENCLAW_IMAGE",
+  "OPENCLAW_GATEWAY_PORT",
+  "OPENCLAW_BRIDGE_PORT",
+  "OPENCLAW_GATEWAY_BIND",
+  "OPENCLAW_GATEWAY_TOKEN",
+  "OPENCLAW_TZ",
+  "OPENCLAW_HOME_VOLUME",
+  "OPENCLAW_STATE_VOLUME",
+  "OPENCLAW_WORKSPACE_VOLUME"
+];
+const MANAGED_ENV_HEADER = [
+  "# Managed by ocdev.",
+  "# Managed keys may be refreshed when you run `ocdev up` again.",
+  "# Extra keys are preserved, but comments and ordering are not guaranteed."
+].join("\n");
+
+export function sanitizeInstanceName(rawValue) {
+  const sanitized = `${rawValue || ""}`
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40);
+
+  if (!sanitized) {
+    throw new Error("Instance name must contain at least one ASCII letter or number.");
+  }
+
+  return sanitized;
+}
+
+export function defaultInstanceName(cwd = process.cwd()) {
+  return sanitizeInstanceName(path.basename(cwd) || "default");
+}
+
+export function resolveManagerHome({
+  env = process.env,
+  platform = process.platform,
+  homeDir = os.homedir()
+} = {}) {
+  if (env.OPENCLAW_DEV_HOME?.trim()) {
+    return path.resolve(env.OPENCLAW_DEV_HOME.trim());
+  }
+
+  if (platform === "darwin") {
+    return path.join(homeDir, "Library", "Application Support", "openclaw-dev");
+  }
+
+  if (platform === "win32" && env.APPDATA?.trim()) {
+    return path.join(env.APPDATA.trim(), "openclaw-dev");
+  }
+
+  if (env.XDG_STATE_HOME?.trim()) {
+    return path.join(env.XDG_STATE_HOME.trim(), "openclaw-dev");
+  }
+
+  return path.join(homeDir, ".local", "state", "openclaw-dev");
+}
+
+export function resolveInstancesRoot(options) {
+  return path.join(resolveManagerHome(options), "instances");
+}
+
+export function normalizeProfileId(rawProfile = DEFAULT_PROFILE) {
+  const normalized = `${rawProfile || ""}`.trim().toLowerCase();
+  const aliasResolved = PROFILE_ALIASES.get(normalized) || normalized || DEFAULT_PROFILE;
+
+  if (!SUPPORTED_PROFILES.has(aliasResolved)) {
+    throw new Error(
+      `Unsupported profile: ${rawProfile}. Supported profiles: ${[...SUPPORTED_PROFILES].join(", ")}`
+    );
+  }
+
+  return aliasResolved;
+}
+
+export function defaultImageForProfile(profile) {
+  return `${DEFAULT_IMAGE_REGISTRY}:main-${normalizeProfileId(profile)}`;
+}
+
+export function detectTimezone() {
+  return process.env.TZ || Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+}
+
+export function buildInstanceConfig({
+  instance,
+  profile,
+  image,
+  gatewayPort = DEFAULT_GATEWAY_PORT,
+  bridgePort,
+  timezone = "UTC"
+}) {
+  const sanitizedInstance = sanitizeInstanceName(instance);
+  const composeProjectName = `openclaw-${sanitizedInstance}`;
+  const resolvedBridgePort = bridgePort ?? gatewayPort + DEFAULT_BRIDGE_PORT_OFFSET;
+  const prefix = `openclaw_${sanitizedInstance}`;
+
+  return {
+    instance: sanitizedInstance,
+    profile: normalizeProfileId(profile),
+    image: image || defaultImageForProfile(profile),
+    composeProjectName,
+    gatewayPort,
+    bridgePort: resolvedBridgePort,
+    timezone,
+    gatewayToken: crypto.randomBytes(32).toString("hex"),
+    volumes: {
+      home: `${prefix}_home`,
+      state: `${prefix}_state`,
+      workspace: `${prefix}_workspace`
+    }
+  };
+}
+
+export function renderInstanceEnv(config, existingEntries = {}) {
+  return renderMergedEnvFile({
+    existingEntries,
+    managedEntries: buildManagedEnvEntries(config)
+  });
+}
+
+export function stackPaths({ rootDir = resolveInstancesRoot(), instance }) {
+  const sanitizedInstance = sanitizeInstanceName(instance);
+  const stackDir = path.join(rootDir, sanitizedInstance);
+
+  return {
+    instance: sanitizedInstance,
+    stackDir,
+    envPath: path.join(stackDir, ".env"),
+    composePath: path.join(stackDir, "docker-compose.instance.yml"),
+    readmePath: path.join(stackDir, "README.md")
+  };
+}
+
+export function readFlag(argv, flag) {
+  const index = argv.indexOf(flag);
+  return index === -1 ? null : argv[index + 1] ?? null;
+}
+
+export function hasFlag(argv, ...flags) {
+  return flags.some((flag) => argv.includes(flag));
+}
+
+export function readPositional(argv, offset = 0) {
+  const positionals = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token) {
+      continue;
+    }
+
+    if (token.startsWith("-")) {
+      if (FLAGS_WITH_VALUES.has(token)) {
+        index += 1;
+      }
+      continue;
+    }
+
+    positionals.push(token);
+  }
+
+  return positionals[offset] ?? null;
+}
+
+export function numberFlag(argv, flag, fallbackValue) {
+  const value = readFlag(argv, flag);
+  if (!value) {
+    return fallbackValue;
+  }
+
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`${flag} must be a positive integer.`);
+  }
+
+  return parsed;
+}
+
+export async function readEnvFile(filePath) {
+  try {
+    const raw = await readFile(filePath, "utf8");
+    return parseEnvContent(raw);
+  } catch {
+    return {};
+  }
+}
+
+export function buildConfigFromArgs({ cwd = process.cwd(), argv, defaults = {} }) {
+  const instance = sanitizeInstanceName(
+    readFlag(argv, "--name") || readPositional(argv, 1) || defaults.instance || defaultInstanceName(cwd)
+  );
+  const existingEnv = defaults.existingEnv || {};
+  const profile = normalizeProfileId(readFlag(argv, "--profile") || existingEnv.OPENCLAW_PROFILE || DEFAULT_PROFILE);
+  const gatewayPort = numberFlag(
+    argv,
+    "--gateway-port",
+    Number.parseInt(existingEnv.OPENCLAW_GATEWAY_PORT || "", 10) || DEFAULT_GATEWAY_PORT
+  );
+  const bridgePort = numberFlag(
+    argv,
+    "--bridge-port",
+    Number.parseInt(existingEnv.OPENCLAW_BRIDGE_PORT || "", 10) || gatewayPort + DEFAULT_BRIDGE_PORT_OFFSET
+  );
+  const timezone = readFlag(argv, "--timezone") || existingEnv.OPENCLAW_TZ || detectTimezone();
+  const image = readFlag(argv, "--image") || existingEnv.OPENCLAW_IMAGE || defaultImageForProfile(profile);
+
+  const config = buildInstanceConfig({
+    instance,
+    profile,
+    image,
+    gatewayPort,
+    bridgePort,
+    timezone
+  });
+
+  config.gatewayToken = existingEnv.OPENCLAW_GATEWAY_TOKEN || config.gatewayToken;
+  config.composeProjectName = existingEnv.COMPOSE_PROJECT_NAME || config.composeProjectName;
+  config.volumes = {
+    home: existingEnv.OPENCLAW_HOME_VOLUME || config.volumes.home,
+    state: existingEnv.OPENCLAW_STATE_VOLUME || config.volumes.state,
+    workspace: existingEnv.OPENCLAW_WORKSPACE_VOLUME || config.volumes.workspace
+  };
+
+  return config;
+}
+
+export async function loadComposeTemplate() {
+  return readFile(COMPOSE_TEMPLATE_PATH, "utf8");
+}
+
+export async function writeStackFiles({
+  rootDir = resolveInstancesRoot(),
+  cwd,
+  config,
+  refreshTemplate = false
+}) {
+  const effectiveRootDir = cwd || rootDir;
+  const paths = stackPaths({ rootDir: effectiveRootDir, instance: config.instance });
+  const composeTemplate = await loadComposeTemplate();
+  const existingEnv = await readEnvFile(paths.envPath);
+
+  await mkdir(paths.stackDir, { recursive: true });
+  await writeFile(paths.envPath, renderInstanceEnv(config, existingEnv), "utf8");
+
+  if (refreshTemplate || !(await fileExists(paths.composePath))) {
+    await writeFile(paths.composePath, composeTemplate, "utf8");
+  }
+
+  if (refreshTemplate || !(await fileExists(paths.readmePath))) {
+    await writeFile(paths.readmePath, renderStackReadme(config, paths), "utf8");
+  }
+
+  return paths;
+}
+
+export function buildManagedEnvEntries(config) {
+  return {
+    COMPOSE_PROJECT_NAME: config.composeProjectName,
+    OPENCLAW_INSTANCE: config.instance,
+    OPENCLAW_PROFILE: config.profile,
+    OPENCLAW_IMAGE: config.image,
+    OPENCLAW_GATEWAY_PORT: `${config.gatewayPort}`,
+    OPENCLAW_BRIDGE_PORT: `${config.bridgePort}`,
+    OPENCLAW_GATEWAY_BIND: "lan",
+    OPENCLAW_GATEWAY_TOKEN: config.gatewayToken,
+    OPENCLAW_TZ: config.timezone,
+    OPENCLAW_HOME_VOLUME: config.volumes.home,
+    OPENCLAW_STATE_VOLUME: config.volumes.state,
+    OPENCLAW_WORKSPACE_VOLUME: config.volumes.workspace
+  };
+}
+
+function renderMergedEnvFile({ existingEntries = {}, managedEntries }) {
+  const extraEntries = {};
+  for (const [key, value] of Object.entries(existingEntries)) {
+    if (!MANAGED_ENV_KEYS.includes(key)) {
+      extraEntries[key] = value;
+    }
+  }
+
+  const lines = [MANAGED_ENV_HEADER, ""];
+
+  for (const key of MANAGED_ENV_KEYS) {
+    lines.push(`${key}=${managedEntries[key]}`);
+  }
+
+  const extraKeys = Object.keys(extraEntries).sort();
+  if (extraKeys.length) {
+    lines.push("", "# Preserved extra keys");
+    for (const key of extraKeys) {
+      lines.push(`${key}=${extraEntries[key]}`);
+    }
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+function renderStackReadme(config, paths) {
+  return [
+    `# ${config.instance}`,
+    "",
+    "Managed by `ocdev`.",
+    "",
+    `State directory: \`${shellPath(paths.stackDir)}\``,
+    "Live profile, image, token, and port values are stored in `.env`.",
+    "",
+    "Managed file policy:",
+    "- `.env` managed keys may be refreshed on `ocdev up`; extra keys are preserved.",
+    "- `docker-compose.instance.yml` and `README.md` are only created once unless you explicitly refresh them later.",
+    "",
+    "Recommended `ocdev` commands:",
+    `- \`ocdev token ${config.instance}\``,
+    `- \`ocdev approve ${config.instance}\``,
+    `- \`ocdev logs ${config.instance}\``,
+    `- \`ocdev claw --name ${config.instance} devices list\``,
+    `- \`ocdev down ${config.instance}\``,
+    "",
+    "Low-level Docker Compose commands:",
+    `- \`docker compose --env-file ${shellQuote(paths.envPath)} -f ${shellQuote(paths.composePath)} up -d\``,
+    `- \`docker compose --env-file ${shellQuote(paths.envPath)} -f ${shellQuote(paths.composePath)} logs -f openclaw-gateway\``,
+    `- \`docker compose --env-file ${shellQuote(paths.envPath)} -f ${shellQuote(paths.composePath)} down\``,
+    ""
+  ].join("\n");
+}
+
+function parseEnvContent(raw) {
+  const entries = {};
+
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line || line.startsWith("#")) {
+      continue;
+    }
+
+    const separatorIndex = line.indexOf("=");
+    if (separatorIndex === -1) {
+      continue;
+    }
+
+    const key = line.slice(0, separatorIndex).trim();
+    const value = line.slice(separatorIndex + 1).trim();
+    if (key) {
+      entries[key] = value;
+    }
+  }
+
+  return entries;
+}
+
+async function fileExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function shellPath(filePath) {
+  return filePath.replace(/\\/g, "/");
+}
+
+function shellQuote(filePath) {
+  const normalized = shellPath(filePath);
+  return `'${normalized.replace(/'/g, `'\\''`)}'`;
+}

package/src/lib/ports.mjs

@@ -0,0 +1,64 @@
+import net from "node:net";
+
+export async function resolvePortPlan({
+  gatewayPort,
+  bridgePort,
+  preserveExistingPorts = false
+}) {
+  if (preserveExistingPorts) {
+    return {
+      gatewayPort,
+      bridgePort,
+      shifted: false,
+      originalGatewayPort: gatewayPort,
+      originalBridgePort: bridgePort
+    };
+  }
+
+  const requestedBridgePort = bridgePort ?? gatewayPort + 1;
+  const delta = requestedBridgePort - gatewayPort;
+  let currentGateway = gatewayPort;
+  let currentBridge = requestedBridgePort;
+
+  while (!(await arePortsAvailable(currentGateway, currentBridge))) {
+    currentGateway += 1;
+    currentBridge += delta === 0 ? 1 : delta;
+  }
+
+  return {
+    gatewayPort: currentGateway,
+    bridgePort: currentBridge,
+    shifted: currentGateway !== gatewayPort || currentBridge !== requestedBridgePort,
+    originalGatewayPort: gatewayPort,
+    originalBridgePort: requestedBridgePort
+  };
+}
+
+async function arePortsAvailable(gatewayPort, bridgePort) {
+  if (gatewayPort === bridgePort) {
+    return false;
+  }
+
+  const gatewayAvailable = await isPortAvailable(gatewayPort);
+  if (!gatewayAvailable) {
+    return false;
+  }
+
+  return isPortAvailable(bridgePort);
+}
+
+function isPortAvailable(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+
+    server.once("error", () => {
+      resolve(false);
+    });
+
+    server.once("listening", () => {
+      server.close(() => resolve(true));
+    });
+
+    server.listen(port, "0.0.0.0");
+  });
+}