@clawscarf/cli 0.1.0-alpha.1

package/scripts/deployment/initial-services.js

@@ -0,0 +1,53 @@
+import { browserDefaults } from "./browser.js";
+/** Compose a fresh native preset. Existing native state is never reconciled through this helper. */
+export function withInitialServices(native, services) {
+    const browser = services.browserToken === undefined
+        ? undefined
+        : browserDefaults(services.browserToken);
+    return {
+        ...native,
+        ...(services.connectionsBrokerUrl
+            ? {
+                secrets: {
+                    ...("secrets" in native ? native.secrets : {}),
+                    providers: {
+                        ...("secrets" in native ? native.secrets.providers : {}),
+                        "clawscarf-connections": {
+                            source: "env",
+                            allowlist: ["CLAWSCARF_CONNECTIONS_TOKEN"],
+                        },
+                    },
+                },
+                plugins: {
+                    ...native.plugins,
+                    entries: {
+                        ...native.plugins.entries,
+                        "clawscarf-connections": {
+                            enabled: true,
+                            config: {
+                                brokerUrl: services.connectionsBrokerUrl,
+                                credential: {
+                                    source: "env",
+                                    provider: "clawscarf-connections",
+                                    id: "CLAWSCARF_CONNECTIONS_TOKEN",
+                                },
+                            },
+                        },
+                    },
+                },
+            }
+            : {}),
+        ...(browser && services.browserNode
+            ? {
+                gateway: {
+                    ...native.gateway,
+                    nodes: {
+                        pairing: { autoApproveLocal: false },
+                        browser: { mode: "manual", node: services.browserNode },
+                    },
+                },
+            }
+            : {}),
+        ...(browser ? { browser: { ...native.browser, ...browser } } : {}),
+    };
+}

package/scripts/deployment/launch.js

@@ -0,0 +1,177 @@
+import { applyConnectionPolicy } from "./connection-policy.js";
+import { verifyRuntimeImage } from "./images.js";
+import { startBrowserNode } from "./browser-node-pairing.js";
+import { verifyBrowserNode } from "./browser-node.js";
+import { verifyRelayConfiguration } from "./relay.js";
+import { verifyBrowserListener, verifyBrowserConfiguration, } from "./browser.js";
+import { probeTeamAccess } from "./team.js";
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { z } from "zod";
+import { readState, resourceNames } from "./state.js";
+import { verifyLocalNetworks } from "./networks.js";
+import { compose } from "./compose.js";
+import { ensureRuntime, stopRuntime } from "./runtime.js";
+import { LocalSetupError, run } from "./process.js";
+import { verifyLocalExecutables, verifyLocalPorts } from "./preflight.js";
+import { verifyRuntimeBinding } from "./runtime-binding.js";
+import { requireNoUpgrade } from "./upgrade-state.js";
+/** Internal operation: the caller holds the installation lock for its full lifetime. */
+export async function launchLocal(directoryInput, report, control = {}) {
+    const directory = resolve(directoryInput);
+    const state = await readState(directory);
+    z.strictObject({
+        ownerId: z.literal(state.ownerId),
+        settingsCandidate: z.string().optional(),
+        settingsReapply: z.enum(["models", "connections"]).optional(),
+    }).parse(JSON.parse(await readFile(join(directory, "prepared.json"), "utf8")));
+    if (Object.keys(process.env).some((key) => key.startsWith("OPENSHELL_")))
+        throw new LocalSetupError("configuration_changed", "Unset OPENSHELL_* overrides before starting this installation.");
+    const controller = join(directory, "controller");
+    const env = {
+        ...process.env,
+        XDG_CONFIG_HOME: join(controller, "config"),
+        XDG_STATE_HOME: join(controller, "state"),
+        XDG_DATA_HOME: join(controller, "data"),
+    };
+    const name = resourceNames(state).sandbox;
+    await requireNoUpgrade(directory);
+    await verifyRuntimeImage(state.input.runtimeImage);
+    await verifyLocalExecutables(state);
+    await verifyLocalPorts(state);
+    await verifyLocalNetworks(directory, state);
+    await verifyBrowserConfiguration(directory, state);
+    await verifyBrowserNode(directory, state);
+    await verifyRelayConfiguration(directory, state);
+    const cancellation = new AbortController();
+    const stopSignal = () => {
+        cancellation.abort();
+    };
+    const check = () => {
+        if (cancellation.signal.aborted)
+            throw new LocalSetupError("startup_interrupted", "Startup interrupted. Services already started remain available; use stop to stop the installation.");
+    };
+    async function waitFor(probe) {
+        const deadline = Date.now() + 90_000;
+        let lastFailure;
+        while (Date.now() < deadline) {
+            check();
+            try {
+                await probe();
+                check();
+                return;
+            }
+            catch (error) {
+                check();
+                lastFailure = error;
+                await delay(500);
+            }
+        }
+        throw lastFailure instanceof Error
+            ? lastFailure
+            : new LocalSetupError("startup_timed_out", "Local startup did not become ready before its deadline.");
+    }
+    control.signal?.addEventListener("abort", stopSignal, { once: true });
+    if (control.signal?.aborted)
+        stopSignal();
+    process.on("SIGINT", stopSignal);
+    process.on("SIGTERM", stopSignal);
+    try {
+        report("Starting controller…");
+        await compose(directory, ["up", "-d", "controller"]);
+        await waitFor(async () => {
+            await run(state.input.openshellCli, ["sandbox", "list", "--gateway", name, "--output", "json"], { env, timeout: 5000 });
+        });
+        await applyConnectionPolicy(directory, state, env);
+        if (state.input.modelGateway) {
+            report("Starting model gateway…");
+            await compose(directory, [
+                "up",
+                "-d",
+                "--wait",
+                "--wait-timeout",
+                "120",
+                "models",
+            ]);
+            check();
+        }
+        if (state.input.browser) {
+            report("Starting browser relay…");
+            await compose(directory, ["up", "-d", "browser-relay"]);
+            const browserPort = state.input.browser.port;
+            await waitFor(() => verifyBrowserListener(directory, browserPort));
+        }
+        report("Starting OpenClaw…");
+        const runtime = await ensureRuntime(directory, state, env);
+        check();
+        await compose(directory, ["up", "-d", "application", "widgets"]);
+        await waitFor(async () => {
+            const response = await fetch(`http://127.0.0.1:${String(state.input.ports.native)}/healthz`, { signal: AbortSignal.timeout(3000) });
+            if (!response.ok)
+                throw new LocalSetupError("native_unavailable", "OpenClaw has not become healthy.");
+            await response.body?.cancel();
+        });
+        await verifyRuntimeBinding(state, runtime);
+        await applyConnectionPolicy(directory, state, env, true);
+        if (state.input.browser) {
+            report("Starting native browser node…");
+            await startBrowserNode(directory, state, cancellation.signal);
+        }
+        report("Starting access…");
+        await compose(directory, ["up", "-d", "--wait", "companion"]);
+        await waitFor(() => probeTeamAccess(directory, state.input, AbortSignal.any([cancellation.signal, AbortSignal.timeout(3000)])));
+        check();
+        report(`Open ${state.input.team.origin}`);
+        await control.activate?.();
+        check();
+    }
+    finally {
+        control.signal?.removeEventListener("abort", stopSignal);
+        process.off("SIGINT", stopSignal);
+        process.off("SIGTERM", stopSignal);
+    }
+}
+/** Stop entry first, then the owned runtime, and only then its controller. */
+export async function stopLocal(directory) {
+    const state = await readState(directory);
+    const controller = join(directory, "controller");
+    const env = {
+        ...process.env,
+        XDG_CONFIG_HOME: join(controller, "config"),
+        XDG_STATE_HOME: join(controller, "state"),
+        XDG_DATA_HOME: join(controller, "data"),
+    };
+    await compose(directory, [
+        "stop",
+        "companion",
+        "application",
+        "widgets",
+        ...(state.input.browser
+            ? ["browser-node", "browser-node-ingress", "browser-node-dns"]
+            : []),
+    ]);
+    // A stopped controller must be available to observe and stop its owned runtime.
+    await compose(directory, ["up", "-d", "controller"]);
+    const deadline = Date.now() + 30_000;
+    for (;;) {
+        try {
+            await run(state.input.openshellCli, [
+                "sandbox",
+                "list",
+                "--gateway",
+                resourceNames(state).sandbox,
+                "-o",
+                "json",
+            ], { env, timeout: 5000 });
+            break;
+        }
+        catch (error) {
+            if (Date.now() >= deadline)
+                throw error;
+            await delay(500);
+        }
+    }
+    await stopRuntime(directory, state, env);
+    await compose(directory, ["stop"]);
+}

package/scripts/deployment/logs.js

@@ -0,0 +1,15 @@
+export const localLogNames = [
+    "controller",
+    "application",
+    "widgets",
+    "companion",
+    "postgres",
+    "models",
+    "models-database",
+    "browser-relay",
+    "browser",
+    "browser-egress",
+    "browser-node",
+    "browser-node-ingress",
+    "browser-node-dns",
+];

package/scripts/deployment/model-gateway-compose.js

@@ -0,0 +1,74 @@
+import { join } from "node:path";
+import { postgresImage } from "./images.js";
+export function modelGatewayServices(directory, state) {
+    const input = state.input.modelGateway;
+    if (!input)
+        return {};
+    const root = join(directory, "private/models");
+    const labels = { "clawscarf.installation": state.ownerId };
+    return {
+        "models-database": {
+            image: postgresImage,
+            environment: {
+                POSTGRES_DB: "models",
+                POSTGRES_USER: "models",
+                POSTGRES_PASSWORD_FILE: "/run/secrets/password",
+            },
+            volumes: [
+                "models-database:/var/lib/postgresql/data",
+                `${join(root, "database-password")}:/run/secrets/password:ro`,
+            ],
+            healthcheck: {
+                test: ["CMD-SHELL", "pg_isready -U models -d models"],
+                interval: "2s",
+                timeout: "3s",
+                retries: 30,
+            },
+            labels,
+        },
+        models: {
+            image: input.image,
+            init: true,
+            read_only: true,
+            cap_drop: ["ALL"],
+            security_opt: ["no-new-privileges:true"],
+            tmpfs: ["/tmp:size=256m,mode=1777"],
+            command: [
+                "--config",
+                "/etc/clawscarf/models.json",
+                "--host",
+                "0.0.0.0",
+                "--port",
+                "4000",
+                "--ssl_keyfile_path",
+                "/run/clawscarf/key.pem",
+                "--ssl_certfile_path",
+                "/run/clawscarf/cert.pem",
+            ],
+            env_file: [{ path: join(root, "gateway.env"), format: "raw" }],
+            volumes: [
+                `${join(root, "models.json")}:/etc/clawscarf/models.json:ro`,
+                `${join(directory, "private/management-key.pem")}:/run/clawscarf/key.pem:ro`,
+                `${join(directory, "private/management-cert.pem")}:/run/clawscarf/cert.pem:ro`,
+            ],
+            ports: [`127.0.0.1:${String(input.port)}:4000`],
+            depends_on: { "models-database": { condition: "service_healthy" } },
+            healthcheck: {
+                test: [
+                    "CMD",
+                    "python",
+                    "-c",
+                    "import ssl,urllib.request; urllib.request.urlopen('https://127.0.0.1:4000/health/liveliness',context=ssl.create_default_context(cafile='/run/clawscarf/cert.pem'),timeout=3)",
+                ],
+                interval: "3s",
+                timeout: "5s",
+                retries: 40,
+            },
+            logging: {
+                driver: "json-file",
+                options: { "max-size": "10m", "max-file": "3" },
+            },
+            labels,
+        },
+    };
+}

package/scripts/deployment/model-gateway.js

@@ -0,0 +1,125 @@
+import { z } from "zod";
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parseEnv } from "node:util";
+import { configurationSchema, gatewayRoutesSchema, liteLlmConfiguration, } from "../models/configuration.js";
+import { issueRuntimeCredential } from "../models/credentials.js";
+import { ensurePrivateFile, writePrivate } from "./state.js";
+import { LocalSetupError } from "./process.js";
+import { compose } from "./compose.js";
+export async function loadGatewayConfiguration(configurationFile, environmentFile) {
+    const routes = gatewayRoutesSchema.parse(JSON.parse(await readFile(configurationFile, "utf8")));
+    const configuration = configurationSchema.parse({
+        ...routes,
+        mode: "litellm",
+        baseUrl: "https://host.docker.internal/v1",
+    });
+    if (configuration.mode !== "litellm" || !configuration.defaultModel)
+        throw new LocalSetupError("invalid_model_setup", "Local models require LiteLLM routes and an enabled default.");
+    const environment = parseEnv(await readFile(environmentFile, "utf8"));
+    const required = new Set(configuration.models
+        .filter((m) => m.enabled)
+        .map((m) => m.route?.apiKeyEnv));
+    if (Object.keys(environment).some((k) => !required.has(k) ||
+        [
+            "DATABASE_URL",
+            "LITELLM_MASTER_KEY",
+            "STORE_MODEL_IN_DB",
+            "LITELLM_LOG",
+        ].includes(k) ||
+        /[\r\n]/.test(environment[k] ?? "")) ||
+        [...required].some((k) => !k || !environment[k]))
+        throw new LocalSetupError("invalid_model_setup", "The upstream environment file must contain exactly the enabled routes' credential variables.");
+    return { configuration, environment };
+}
+/** Generate local service credentials once, outside the Gateway and its image. */
+export async function prepareModelGateway(directory, state, options = {}) {
+    const input = state.input.modelGateway;
+    const publish = options.replaceConfiguration
+        ? writePrivate
+        : ensurePrivateFile;
+    if (!input)
+        return;
+    const loaded = await loadGatewayConfiguration(input.configurationFile, input.upstreamEnvironmentFile);
+    const root = join(directory, "private/models");
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    for (const [name, prefix] of [
+        ["master-key", "sk-"],
+        ["database-password", ""],
+    ]) {
+        try {
+            await readFile(join(root, name));
+        }
+        catch (error) {
+            if (!(error instanceof Error &&
+                "code" in error &&
+                error.code === "ENOENT"))
+                throw error;
+            await ensurePrivateFile(join(root, name), prefix + randomBytes(32).toString("hex"));
+        }
+    }
+    const password = (await readFile(join(root, "database-password"), "utf8")).trim();
+    const master = (await readFile(join(root, "master-key"), "utf8")).trim();
+    const environment = {
+        ...loaded.environment,
+        LITELLM_MASTER_KEY: master,
+        DATABASE_URL: `postgresql://models:${password}@models-database:5432/models`,
+        STORE_MODEL_IN_DB: "False",
+        LITELLM_LOG: "ERROR",
+    };
+    await publish(join(root, "gateway.env"), Object.entries(environment)
+        .map(([k, v]) => `${k}=${v}`)
+        .join("\n") + "\n");
+    await publish(join(root, "models.json"), JSON.stringify(liteLlmConfiguration(loaded.configuration)));
+    await publish(join(root, "native.json"), JSON.stringify({
+        ...loaded.configuration,
+        baseUrl: `https://host.docker.internal:${String(input.port)}/v1`,
+    }));
+}
+export async function prepareModelCredential(directory, state) {
+    if (!state.input.modelGateway)
+        return;
+    const root = join(directory, "private/models");
+    const output = join(root, "runtime-key");
+    try {
+        const key = await readFile(output, "utf8");
+        z.string().startsWith("sk-").parse(key.trim());
+        return;
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+            throw error;
+    }
+    const intent = join(root, "issuance-started");
+    try {
+        await readFile(intent);
+        throw new LocalSetupError("model_credential_pending", "Model credential issuance is unconfirmed. Inspect LiteLLM before an explicit retry; installation will not issue another key.");
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+            throw error;
+    }
+    try {
+        await compose(directory, [
+            "up",
+            "-d",
+            "--wait",
+            "--wait-timeout",
+            "120",
+            "models",
+        ]);
+        const configuration = configurationSchema.parse(JSON.parse(await readFile(join(root, "native.json"), "utf8")));
+        await ensurePrivateFile(intent, state.ownerId);
+        await issueRuntimeCredential({
+            origin: `https://127.0.0.1:${String(state.input.modelGateway.port)}`,
+            masterKeyFile: join(root, "master-key"),
+            output,
+            configuration,
+            caFile: join(directory, "private/management-ca.pem"),
+        });
+    }
+    finally {
+        await compose(directory, ["stop", "models", "models-database"]);
+    }
+}

package/scripts/deployment/models.js

@@ -0,0 +1,82 @@
+import { OperatorError } from "../errors.js";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { X509Certificate } from "node:crypto";
+import { z } from "zod";
+import { configurationSchema, nativeModelProvider, nativeModelDefaults, } from "../models/configuration.js";
+import { networkRequirementSchema } from "../packs/policy.js";
+import { LocalSetupError } from "./process.js";
+import { ensurePrivateFile } from "./state.js";
+const enabledConfiguration = configurationSchema.refine((value) => value.mode !== "disabled" && value.defaultModel !== null, "Initial model setup requires an enabled gateway and default model.");
+const tokenSchema = z.string().trim().min(1).max(65536);
+/** Validate all optional inputs before allocating resources; never include their values in errors. */
+export async function loadInitialModels(input) {
+    if (!input)
+        return undefined;
+    try {
+        const config = enabledConfiguration.parse(JSON.parse(await readFile(input.configurationFile, "utf8")));
+        if (config.mode === "disabled" || config.defaultModel === null)
+            throw new OperatorError("An initial default is required.");
+        const endpoint = new URL(config.baseUrl);
+        if (endpoint.protocol !== "https:")
+            throw new OperatorError("The runtime requires an HTTPS model gateway.");
+        const network = networkRequirementSchema.parse({
+            host: endpoint.hostname,
+            port: Number(endpoint.port || "443"),
+            protocol: "tcp",
+            binary: "/usr/local/bin/node",
+        });
+        const token = tokenSchema.parse(await readFile(input.runtimeKeyFile, "utf8"));
+        const ca = input.caFile ? await readFile(input.caFile, "utf8") : undefined;
+        // An explicitly trusted self-signed server certificate is also a valid trust anchor.
+        if (ca !== undefined)
+            new X509Certificate(ca);
+        return {
+            configuration: { ...config, defaultModel: config.defaultModel },
+            credential: { token, ...(ca === undefined ? {} : { ca }) },
+            network,
+        };
+    }
+    catch {
+        throw new LocalSetupError("invalid_model_setup", "Initial models require a valid enabled model configuration with a default, an HTTPS DNS endpoint reachable from the runtime, a nonempty scoped key file and, if supplied, a valid trust certificate. Use host.docker.internal for a gateway on this workstation.");
+    }
+}
+/** Only used to construct a fresh native preset, never to reconcile mutable native state. */
+export function withInitialModels(native, models) {
+    if (!models)
+        return native;
+    return {
+        ...native,
+        secrets: {
+            providers: {
+                "clawscarf-models": {
+                    source: "file",
+                    path: "/home/node/.openclaw/clawscarf-models/initial.json",
+                    mode: "json",
+                },
+            },
+        },
+        models: {
+            ...native.models,
+            providers: {
+                clawscarf: {
+                    ...nativeModelProvider(models.configuration),
+                    apiKey: {
+                        source: "file",
+                        provider: "clawscarf-models",
+                        id: "/token",
+                    },
+                },
+            },
+        },
+        agents: {
+            defaults: nativeModelDefaults(models.configuration),
+        },
+    };
+}
+export async function prepareInitialModels(directory, input) {
+    const models = await loadInitialModels(input);
+    if (models)
+        await ensurePrivateFile(join(directory, "private/model-bootstrap.json"), JSON.stringify(models));
+    return models;
+}