@clawscarf/cli 0.1.0-alpha.5 → 0.1.0-alpha.7

package/scripts/deployment/public-web.js

@@ -0,0 +1,176 @@
+// Public unicast ranges, excluding private and special-use destinations.
+// Keep aligned with the browser egress boundary in deploy/execution/network/squid.conf.
+export const publicWebAddresses = [
+    "1.0.0.0/8",
+    "2.0.0.0/7",
+    "4.0.0.0/6",
+    "8.0.0.0/7",
+    "11.0.0.0/8",
+    "12.0.0.0/6",
+    "16.0.0.0/4",
+    "32.0.0.0/3",
+    "64.0.0.0/3",
+    "96.0.0.0/6",
+    "100.0.0.0/10",
+    "100.128.0.0/9",
+    "101.0.0.0/8",
+    "102.0.0.0/7",
+    "104.0.0.0/5",
+    "112.0.0.0/5",
+    "120.0.0.0/6",
+    "124.0.0.0/7",
+    "126.0.0.0/8",
+    "128.0.0.0/3",
+    "160.0.0.0/5",
+    "168.0.0.0/8",
+    "169.0.0.0/9",
+    "169.128.0.0/10",
+    "169.192.0.0/11",
+    "169.224.0.0/12",
+    "169.240.0.0/13",
+    "169.248.0.0/14",
+    "169.252.0.0/15",
+    "169.255.0.0/16",
+    "170.0.0.0/7",
+    "172.0.0.0/12",
+    "172.32.0.0/11",
+    "172.64.0.0/10",
+    "172.128.0.0/9",
+    "173.0.0.0/8",
+    "174.0.0.0/7",
+    "176.0.0.0/4",
+    "192.0.1.0/24",
+    "192.0.3.0/24",
+    "192.0.4.0/22",
+    "192.0.8.0/21",
+    "192.0.16.0/20",
+    "192.0.32.0/19",
+    "192.0.64.0/18",
+    "192.0.128.0/17",
+    "192.1.0.0/16",
+    "192.2.0.0/15",
+    "192.4.0.0/14",
+    "192.8.0.0/13",
+    "192.16.0.0/12",
+    "192.32.0.0/11",
+    "192.64.0.0/12",
+    "192.80.0.0/13",
+    "192.88.0.0/18",
+    "192.88.64.0/19",
+    "192.88.96.0/23",
+    "192.88.98.0/24",
+    "192.88.100.0/22",
+    "192.88.104.0/21",
+    "192.88.112.0/20",
+    "192.88.128.0/17",
+    "192.89.0.0/16",
+    "192.90.0.0/15",
+    "192.92.0.0/14",
+    "192.96.0.0/11",
+    "192.128.0.0/11",
+    "192.160.0.0/13",
+    "192.169.0.0/16",
+    "192.170.0.0/15",
+    "192.172.0.0/14",
+    "192.176.0.0/12",
+    "192.192.0.0/10",
+    "193.0.0.0/8",
+    "194.0.0.0/7",
+    "196.0.0.0/7",
+    "198.0.0.0/12",
+    "198.16.0.0/15",
+    "198.20.0.0/14",
+    "198.24.0.0/13",
+    "198.32.0.0/12",
+    "198.48.0.0/15",
+    "198.50.0.0/16",
+    "198.51.0.0/18",
+    "198.51.64.0/19",
+    "198.51.96.0/22",
+    "198.51.101.0/24",
+    "198.51.102.0/23",
+    "198.51.104.0/21",
+    "198.51.112.0/20",
+    "198.51.128.0/17",
+    "198.52.0.0/14",
+    "198.56.0.0/13",
+    "198.64.0.0/10",
+    "198.128.0.0/9",
+    "199.0.0.0/8",
+    "200.0.0.0/7",
+    "202.0.0.0/8",
+    "203.0.0.0/18",
+    "203.0.64.0/19",
+    "203.0.96.0/20",
+    "203.0.112.0/24",
+    "203.0.114.0/23",
+    "203.0.116.0/22",
+    "203.0.120.0/21",
+    "203.0.128.0/17",
+    "203.1.0.0/16",
+    "203.2.0.0/15",
+    "203.4.0.0/14",
+    "203.8.0.0/13",
+    "203.16.0.0/12",
+    "203.32.0.0/11",
+    "203.64.0.0/10",
+    "203.128.0.0/9",
+    "204.0.0.0/6",
+    "208.0.0.0/4",
+    "2000::/16",
+    "2001:200::/23",
+    "2001:400::/22",
+    "2001:800::/22",
+    "2001:c00::/24",
+    "2001:d00::/25",
+    "2001:d80::/27",
+    "2001:da0::/28",
+    "2001:db0::/29",
+    "2001:db9::/32",
+    "2001:dba::/31",
+    "2001:dbc::/30",
+    "2001:dc0::/26",
+    "2001:e00::/23",
+    "2001:1000::/20",
+    "2001:2000::/19",
+    "2001:4000::/18",
+    "2001:8000::/17",
+    "2003::/16",
+    "2004::/14",
+    "2008::/13",
+    "2010::/12",
+    "2020::/11",
+    "2040::/10",
+    "2080::/9",
+    "2100::/8",
+    "2200::/7",
+    "2400::/6",
+    "2800::/5",
+    "3000::/5",
+    "3800::/6",
+    "3c00::/7",
+    "3e00::/8",
+    "3f00::/9",
+    "3f80::/10",
+    "3fc0::/11",
+    "3fe0::/12",
+    "3ff0::/13",
+    "3ff8::/14",
+    "3ffc::/15",
+    "3ffe::/16",
+    "3fff:1000::/20",
+    "3fff:2000::/19",
+    "3fff:4000::/18",
+    "3fff:8000::/17",
+];
+export function publicWebPolicy(enabled) {
+    return enabled
+        ? {
+            name: "Public web",
+            endpoints: [
+                { ports: [80, 443], allowed_ips: publicWebAddresses, tls: "skip" },
+            ],
+            binaries: [{ path: "/**" }],
+        }
+        : null;
+}

package/scripts/installation/command.js

@@ -20,12 +20,13 @@ import { runConfiguration } from "./installer/run.js";
 import { installationOptions } from "./options.js";
 import { InstallationError } from "./errors.js";
 import { administratorSetup } from "./administrator.js";
-export function installationCommand() {
+export function installationCommand(observation) {
     const program = new Command("clawscarf")
         .description("Install and operate a protected OpenClaw team server.")
         .option("--json", "Print machine-readable results; diagnostics go to stderr");
     program.addCommand(peopleCommand(program));
     const output = (value, human) => {
+        observation?.result(value);
         writeResult(program, value, human);
     };
     installationOptions(program.command("configure"))
@@ -43,9 +44,11 @@ export function installationCommand() {
         const result = await runConfiguration({
             ...options,
             ...program.opts(),
-        });
+        }, (mode) => observation?.configurationMode(mode));
         if (options.nonInteractive)
             output(result);
+        else
+            observation?.result(result);
     });
     program
         .command("recipes")
@@ -91,7 +94,7 @@ export function installationCommand() {
                 });
                 const directory = await resolveLocation(options);
                 const result = await progress("Deleting installation", (signal) => deleteInstallation(directory, signal), program.opts());
-                output(result, "Installation deleted from Docker. You can now remove its installation folder.");
+                output(result, "Installation deleted from Docker. The local folder still contains configuration and credentials. To install again, move or remove that folder, or configure a new --directory.");
                 return;
             }
             if (options.confirmDelete !== undefined || options.acceptDataLoss)

package/scripts/installation/configuration.js

@@ -65,6 +65,7 @@ export const installationSchema = z
         }),
     ]),
     resources: z.strictObject({ runtime: resources }),
+    publicWeb: z.boolean().default(false),
     browser: z.strictObject({ enabled: z.boolean() }),
     models: z.discriminatedUnion("mode", [
         externalLiteLlmSchema,

package/scripts/installation/configure.js

@@ -117,6 +117,7 @@ export async function configurationChanges(before, after) {
     return {
         models: !isDeepStrictEqual(await models(before), await models(after)),
         connections: !isDeepStrictEqual(before.connections, after.connections),
+        publicWeb: before.publicWeb !== after.publicWeb,
         packs: !isDeepStrictEqual(await packs(before), await packs(after)),
     };
 }

package/scripts/installation/installer/collect.js

@@ -175,6 +175,21 @@ export async function collectInstallation(ui, options, retained) {
                     case "resources":
                         config.resources = await collectResources(ui, config.resources);
                         break;
+                    case "public-web":
+                        config.publicWeb =
+                            (await ui.select("Public web access", [
+                                {
+                                    value: "on",
+                                    label: "On",
+                                    hint: "Public HTTP(S); agents can send team data to public services",
+                                },
+                                {
+                                    value: "off",
+                                    label: "Off",
+                                    hint: "Only configured services and explicit policies",
+                                },
+                            ], config.publicWeb ? "on" : "off")) === "on";
+                        break;
                     case "browser":
                         ui.note("Explicit browser node use works. Ordinary model-selected browsing is not qualified because of an upstream routing issue.", "Experimental browser");
                         config.browser.enabled =

package/scripts/installation/installer/menu.js

@@ -25,6 +25,7 @@ export function installationMenu(config, directory, browserAvailable, packIssues
         row("exposure", "Network", config.exposure.mode === "local"
             ? "This computer"
             : config.exposure.applicationOrigin),
+        row("public-web", "Public web", config.publicWeb ? "On" : "Off", "HTTP(S) for agents and tools; private destinations blocked"),
         row("models", "Models", modelSummary ?? "Choose a model"),
         row("connections", "Connections", config.connections.mode === "disabled" ? "Off" : "On"),
         row("packs", "Packs", packIssues.length
@@ -42,7 +43,7 @@ export function installationMenu(config, directory, browserAvailable, packIssues
     ];
     return existing
         ? [
-            ...choices.filter(({ value }) => ["review", "models", "connections", "packs"].includes(value)),
+            ...choices.filter(({ value }) => ["review", "models", "connections", "packs", "public-web"].includes(value)),
             { value: "model-credentials", label: "Change LLM API keys" },
         ]
         : choices;

package/scripts/installation/installer/run.js

@@ -161,7 +161,7 @@ function quote(value) {
     return `'${value.replaceAll("'", "'\\''")}'`;
 }
 /** The command selects the workflow; users never manipulate preparation files. */
-export async function runConfiguration(options) {
+export async function runConfiguration(options, observeMode) {
     options = {
         ...options,
         directory: options.directory ?? defaultInstallationDirectory,
@@ -193,6 +193,19 @@ export async function runConfiguration(options) {
                     throw error;
             }
         }
+        if (existing && state) {
+            try {
+                await access(join(state, "prepared.json"));
+            }
+            catch (error) {
+                if (!(error instanceof Error &&
+                    "code" in error &&
+                    error.code === "ENOENT"))
+                    throw error;
+                throw new InstallationError("invalid_configuration", `This folder retains settings but the installation is no longer prepared. If deletion failed, finish it with clawscarf stop --directory ${quote(options.directory ?? defaultInstallationDirectory)} --delete. After successful deletion, move or remove the installation folder before configuring it again, or choose a new --directory.`);
+            }
+        }
+        observeMode?.(existing ? "edit" : "new");
         let result = existing && state
             ? await editInstallationSettings(state, ui, options)
             : await installFromAnswers(options, ui, operations, (message, work) => progress(message, work, options));
@@ -218,14 +231,17 @@ export async function runConfiguration(options) {
                     : undefined;
             if (result.state === "cancelled")
                 clack.cancel("Cancelled.");
-            else
+            else {
+                if ("ready" in result && result.ready)
+                    ui.note(`clawscarf status --directory ${quote(options.directory ?? defaultInstallationDirectory)}\nclawscarf stop --directory ${quote(options.directory ?? defaultInstallationDirectory)}`, "Manage this installation");
                 clack.outro("ready" in result
                     ? result.ready
-                        ? `ClawScarf is ready.${applicationUrl ? ` Visit ${terminalLink(applicationUrl)}` : ""}\n\nManage this installation:\n  clawscarf status --directory ${quote(options.directory ?? defaultInstallationDirectory)}\n  clawscarf stop --directory ${quote(options.directory ?? defaultInstallationDirectory)}`
+                        ? `ClawScarf is ready.${applicationUrl ? ` Visit ${terminalLink(applicationUrl)}` : ""}`
                         : "ClawScarf needs attention. Check status for details."
                     : result.state === "unchanged"
                         ? "No changes. Server left as it was."
                         : "Configuration saved. Server stopped.");
+            }
             if ("ready" in result && result.ready && applicationUrl)
                 await ui.openBrowser(applicationUrl);
         }

package/scripts/installation/installer/settings.js

@@ -21,7 +21,7 @@ import { withInstallationLock, writePrivate } from "../../deployment/state.js";
 export async function editInstallationSettings(directory, ui, options = {}, prerequisites = { host: checkHost, check: checkInstallationPrerequisites }) {
     directory = resolve(directory);
     if (options.recipe || options.cloudUrl)
-        throw new InstallationError("change_unsupported", "Existing installations keep their recipe, software release and login service. Change models, keys, Connections or packs instead.");
+        throw new InstallationError("change_unsupported", "Existing installations keep their recipe, software release and login service. Change models, keys, Connections, public web or packs instead.");
     if (options.nonInteractive && !options.yes)
         throw new InstallationError("invalid_configuration", "Changing an existing installation noninteractively requires --yes. The server may restart and deselected packs may be removed.");
     const task = (message, work) => progress(message, work, options);
@@ -114,6 +114,9 @@ export async function editInstallationSettings(directory, ui, options = {}, prer
                     `Connections: ${plan.changes.connections.to === "disabled" ? "Off" : "On"}`,
                 ]
                 : []),
+            ...(plan.scopes.publicWeb
+                ? [`Public web: ${plan.changes.publicWeb.to ? "On" : "Off"}`]
+                : []),
             ...(plan.scopes.packs
                 ? [`Packs: ${plan.changes.packs.selected.join(", ") || "None"}`]
                 : []),

package/scripts/installation/installer/summary.js

@@ -39,6 +39,7 @@ export async function installationSummary(config, inputs) {
         `Administrator: ${config.access.administratorName} · ${config.access.mode === "hosted" ? "ClawScarf login" : "Custom OIDC"}`,
         `Models: ${model}`,
         `Connections: ${config.connections.mode === "disabled" ? "Off" : "On"}`,
+        `Public web: ${config.publicWeb ? "On" : "Off"} (private destinations blocked)`,
         `Browser: ${config.browser.enabled ? "Experimental" : "Off"} · Packs: ${config.packs.flatMap((pack) => pack.members).join(", ") || "None"}`,
     ].join("\n");
 }

package/scripts/installation/options.js

@@ -36,6 +36,7 @@ export const selectionSchema = z.object({
     connections: z.boolean().optional(),
     connectionsCloudUrl: cloudUrlSchema.optional(),
     browser: z.boolean().optional(),
+    publicWeb: z.boolean().optional(),
     model: text.optional(),
     provider: text.optional(),
     reasoning: z.enum(["low", "medium", "high"]).optional(),
@@ -79,6 +80,8 @@ export function installationOptions(command) {
         .option("--connections-cloud-url <url>", "Use a separate Connections service")
         .option("--browser", "Enable experimental browser capability")
         .option("--no-browser", "Disable browser capability")
+        .option("--public-web", "Allow public HTTP(S) from agents and tools")
+        .option("--no-public-web", "Restrict runtime egress to configured services")
         .option("--model <id>", "Default model from the model catalog")
         .option("--provider <id>", "Model provider, for example openai or openrouter")
         .addOption(new Option("--reasoning <level>", "Model reasoning level").choices([
@@ -116,6 +119,7 @@ export async function selectedDraft(context, recipe, selections, inputs, retaine
             "modelGatewayKeyFile",
             "modelGatewayCaFile",
             "connections",
+            "publicWeb",
             "connectionsCloudUrl",
             "pack",
             "packs",
@@ -123,7 +127,7 @@ export async function selectedDraft(context, recipe, selections, inputs, retaine
             "packPython",
         ]);
         if (Object.entries(o).some(([key, value]) => value !== undefined && !mutable.has(key)))
-            invalid("Existing installations support changes to models, keys, Connections and packs only.");
+            invalid("Existing installations support changes to models, keys, Connections, public web and packs only.");
     }
     const config = structuredClone(retained ?? recipeConfiguration(context, recipe));
     if (o.name !== undefined)
@@ -136,6 +140,8 @@ export async function selectedDraft(context, recipe, selections, inputs, retaine
         config.resources.runtime.memory = o.memory;
     if (o.browser !== undefined)
         config.browser.enabled = o.browser;
+    if (o.publicWeb !== undefined)
+        config.publicWeb = o.publicWeb;
     if (o.connections !== undefined)
         config.connections.mode = o.connections ? "hosted" : "disabled";
     if (o.connectionsCloudUrl)

package/scripts/installation/recipes/definition.js

@@ -11,6 +11,7 @@ export const recipeSchema = z.strictObject({
     defaults: z.strictObject({
         resources: installationSchema.shape.resources,
         browser: installationSchema.shape.browser,
+        publicWeb: z.boolean().default(false),
         connections: z.strictObject({ enabled: z.boolean() }).optional(),
     }),
     models: z.strictObject({

package/scripts/installation/reconfigure.js

@@ -1,3 +1,5 @@
+import { publicWebPolicy } from "../deployment/public-web.js";
+import { stageNetworkPolicyChange } from "../deployment/network-policy.js";
 import { applyConnectionSettings } from "../deployment/connection-settings.js";
 import { readFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
@@ -41,8 +43,8 @@ export async function planSettingsChange(configFile, reapply) {
     const previousPacks = selectionSchema.parse(await readJson(join(directory, "packs.json")));
     if (!desired.packSelection.python && previousPacks.python)
         desired.packSelection.python = previousPacks.python;
-    const { models: _oldModels, modelGateway: oldGateway, connections: oldConnections, ...oldFixed } = old;
-    const { models: _nextModels, modelGateway: nextGateway, connections: nextConnections, ...nextFixed } = next;
+    const { models: _oldModels, modelGateway: oldGateway, connections: oldConnections, publicWeb: oldPublicWeb, ...oldFixed } = old;
+    const { models: _nextModels, modelGateway: nextGateway, connections: nextConnections, publicWeb: nextPublicWeb, ...nextFixed } = next;
     if (!isDeepStrictEqual(oldFixed, nextFixed) ||
         !isDeepStrictEqual(await readJson(join(directory, "release.json")), desired.release))
         unsupported("Settings changes cannot replace the release, identity, addresses, access, resources or execution protection.");
@@ -92,6 +94,7 @@ export async function planSettingsChange(configFile, reapply) {
         scopes,
         reapply,
         changes: {
+            publicWeb: { from: oldPublicWeb, to: nextPublicWeb },
             models: modelConfiguration
                 ? {
                     enabled: modelConfiguration.models
@@ -235,6 +238,11 @@ export async function reconfigureInstallation(configFile, expectedFingerprint, r
             if (scopes.connections &&
                 (state.input.connections || desired.input.connections))
                 await applyConnectionSettings(directory, { ...state, input: desired.input }, checked.previousEndpoint, desired.connectorCredentialFile);
+            stage = "public web policy";
+            if (scopes.publicWeb)
+                await stageNetworkPolicyChange(directory, state, {
+                    public_web: publicWebPolicy(desired.input.publicWeb),
+                });
             stage = "accepted settings";
             if (scopes.models)
                 await writePrivate(join(directory, "private/model-bootstrap.json"), JSON.stringify(models));

package/scripts/installation/resolve.js

@@ -73,6 +73,7 @@ export async function resolveInstallation(configFile, internalPorts) {
         name: config.name,
         administratorName: access.administratorName,
         runtimeImage: release.images.gateway,
+        publicWeb: config.publicWeb,
         companionImage: release.images.companion,
         ...(config.browser.enabled ? { relayImage: release.images.relay } : {}),
         openshellCli: cli,

package/scripts/installation/setup.js

@@ -57,6 +57,7 @@ export function recipeConfiguration(context, recipeId) {
         },
         resources: structuredClone(recipe.defaults.resources),
         browser: structuredClone(recipe.defaults.browser),
+        publicWeb: recipe.defaults.publicWeb,
         connections: {
             mode: recipe.defaults.connections?.enabled ? "hosted" : "disabled",
             cloudUrl: context.cloudUrl,