@clawscarf/cli 0.1.0-alpha.1 → 0.1.0-alpha.2

package/deploy/execution/network/node-ingress.cfg

@@ -32,4 +32,4 @@ frontend native_node
   default_backend native_gateway
 
 backend native_gateway
-  server gateway "host.docker.internal:${CLAWSCARF_NODE_GATEWAY_PORT}" resolvers docker init-addr libc,none
+  server gateway "application:${CLAWSCARF_NODE_GATEWAY_PORT}" resolvers docker init-addr libc,none

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "engines": {
     "node": ">=24.16.0 <25 || >=26.1.0"
   },

package/recipes/team-server/recipe.json

@@ -1,7 +1,7 @@
 {
   "id": "team-server",
   "version": "0.1.0",
-  "runtime": "../../runtime/releases/0.1.0-alpha.1.json",
+  "runtime": "../../runtime/releases/0.1.0-alpha.2.json",
   "name": "Team server",
   "description": "A protected OpenClaw server for your team, with hosted login, managed models and optional Connections.",
   "maturity": "supported",

package/release/README.md

@@ -14,9 +14,10 @@ Recipes and packs ship with the CLI; there is no separate registry or dependency
 The [model catalog](../deploy/models/catalog.json) is also a CLI asset. Recipe IDs select
 catalog entries; model protocols and limits have one definition.
 
-## Current development use
+## Published and development use
 
 ```sh
+npm install -g @clawscarf/cli@next
 clawscarf configure
 # Or use staging for hosted login and Connections:
 clawscarf configure --cloud-url https://cloud-staging.clawscarf.com
@@ -33,7 +34,13 @@ locally built Docker image IDs and checksum-pinned OpenShell tools under ignored
 published, clean-machine release**. Definitions belong in the tracked directories
 above. Compiled images, binaries and test artifacts are not source definitions.
 
-The current platform is macOS arm64 with Docker Desktop. Setup validates the host,
+Published candidates include macOS arm64 and Linux arm64/x86-64 tools, with Linux
+container images for both architectures. Windows uses the Linux CLI inside WSL2
+(experimental);
+Docker Desktop must expose its Linux engine to that distribution. Intel Mac is blocked
+by the pinned upstream OpenShell release lacking a Darwin x86-64 executable.
+See the [upstream support matrix](https://docs.nvidia.com/openshell/reference/support-matrix)
+for host requirements. Setup validates the host,
 tools and ports; it pulls registry images by digest and downloads missing runtime tools
 when their definition supplies an HTTPS URL and SHA-256. It cannot recover a missing
 local development image ID. See the
@@ -66,15 +73,23 @@ silently replaced. Docker verifies image digests. No start command resolves late
 with an exact version, such as `0.1.0-alpha.1`. It:
 
 1. Runs checks and tests the compiled operator outside the checkout on macOS arm64.
-2. Builds the pinned OpenClaw source and ClawScarf images on Linux arm64, checks
-   runtime capabilities and the Chromium sandbox, and pushes candidate images to GHCR.
+2. Builds the pinned OpenClaw source and ClawScarf images on Linux arm64 and x86-64,
+   checks runtime capabilities and the Chromium sandbox, then starts a protected
+   installation with private LiteLLM networking and verifies stop/start retention.
+   It publishes image indexes containing both architectures to GHCR.
 3. Downloads checksum-pinned OpenShell tools, records the image digests, and assembles
-   the runtime archive, individual executable assets, npm CLI, checksums and notices.
+   one runtime archive per host platform, individual executable assets, npm CLI,
+   checksums and notices.
 4. Installs the resulting npm archive into a temporary prefix and checks its CLI/catalog.
 
 The [image builder](../scripts/release/build-images.sh) and
 [candidate assembler](../scripts/release/candidate.ts) contain the build commands;
-Actions supplies runners and registry credentials. The source recipe pins the development
+GitHub Actions orchestrates the build and supplies registry credentials. Image builds
+and Linux installation checks use Depot ARM64/x86-64 runners; macOS checks and packaging
+use GitHub-hosted runners. The Depot Managed Runners app connects the ClawScarf organization
+to the RAW Labs Depot organization. The image job installs Docker 29.5.3 on its
+disposable runner for the network features required by installations.
+The source recipe pins the development
 runtime. Packaging resolves that same runtime to the candidate's immutable definition;
 it does not make recipes select latest. The first release uses the same CLI/runtime
 version. Recipe versions remain independent; bump them when defaults, pack selection
@@ -92,20 +107,33 @@ GitHub Release and publishes the already-built npm tarball. It never rebuilds im
 or packages. Prereleases use npm's `next` tag; stable versions use `latest`. Repeating
 a GitHub upload is allowed only when the existing checksums match exactly.
 
-Repository setup before first publication:
+Repository setup:
 
 - GHCR image packages must be publicly readable; a private candidate digest is not
   usable by an unauthenticated installer. The build uses GitHub's scoped job token.
-- Configure the GitHub `release` environment and npm trusted publishing for
-  `@clawscarf/cli`, repository `clawscarf/clawscarf`, workflow [publish-release.yml](../.github/workflows/publish-release.yml),
-  environment `release`. npm ownership/initial package setup is separate from code.
-- Check transitive notices/source obligations before distributing the first images.
+- The GitHub `release` environment restricts deployment to `main`. The npm
+  organization `@clawscarf` owns the public `@clawscarf/cli` package.
+- npm trusted publishing is configured for repository `clawscarf/clawscarf`, workflow
+  [publish-release.yml](../.github/workflows/publish-release.yml), environment `release`.
+  The first tested tarball was published using the owner's authenticated npm CLI because
+  npm requires a package to exist before configuring trust. Subsequent publication
+  uses the workflow's short-lived identity rather than a stored npm token. That next
+  workflow publication has not yet been exercised.
+- Transitive notices/source review remains open in [TODO.md](../TODO.md).
   Debian copyright files remain in the images; runtime assets include upstream notices
   and the image build exports its network-tool sources. Those files are not a claim of
   a completed license audit. Pinned Debian packages still depend on mirror retention.
 
-No npm/GitHub release has been published by adding these workflows. The first Actions
-run, clean-machine journey, registry access and publication remain in [TODO.md](../TODO.md).
+[Candidate 35524428880](https://github.com/clawscarf/clawscarf/actions/runs/35524428880)
+passed its checks, compiled archive test and all eight image builds. The same artifacts
+are available in the [0.1.0-alpha.1 GitHub prerelease](https://github.com/clawscarf/clawscarf/releases/tag/v0.1.0-alpha.1).
+The identical CLI tarball is published as `@clawscarf/cli@0.1.0-alpha.1`, tagged `next`.
+All eight GHCR images were verified anonymously readable by digest. The packaged CLI
+passed fresh setup on the development Mac, staging hosted administrator login, real
+GPT-6 Astra inference and stop/start with retained chat history. Published tool URLs
+passed download and SHA-256 verification. Disposable installation containers, volumes
+and networks were deleted afterward. This does not establish a newly provisioned
+host, production first-time signup, Linux/WSL or changed-version upgrades.
 
 ## Assemble runtime artifacts
 

package/release/components.json

@@ -12,12 +12,28 @@
       "darwin-arm64": {
         "url": "https://github.com/NVIDIA/OpenShell/releases/download/v0.0.116/openshell-aarch64-apple-darwin.tar.gz",
         "sha256": "e582f2374053bebac8e6aaeb4a369931b7d4bb97bd55055e2c02e85502627e22"
+      },
+      "linux-arm64": {
+        "url": "https://github.com/NVIDIA/OpenShell/releases/download/v0.0.116/openshell-aarch64-unknown-linux-musl.tar.gz",
+        "sha256": "7a949c48d1e000cd280869eea1e203e24816b9cfefc575b68a8b72b939cb3f43"
+      },
+      "linux-x64": {
+        "url": "https://github.com/NVIDIA/OpenShell/releases/download/v0.0.116/openshell-x86_64-unknown-linux-musl.tar.gz",
+        "sha256": "4fb4476d80a1875a0b83547ec3aba999cf0a2e2d75f95f2f709b622e2103520e"
       }
     },
     "gateway": {
       "darwin-arm64": {
         "url": "https://github.com/NVIDIA/OpenShell/releases/download/v0.0.116/openshell-gateway-aarch64-apple-darwin.tar.gz",
         "sha256": "f192d3d737c125264e13ef73458541df2ca6a9eb2fa599736a7f2587d5d2ce8d"
+      },
+      "linux-arm64": {
+        "url": "https://github.com/NVIDIA/OpenShell/releases/download/v0.0.116/openshell-gateway-aarch64-unknown-linux-gnu.tar.gz",
+        "sha256": "292c379193a339220234ffea585350901468bb8f4076e2076bc074e8ed18974b"
+      },
+      "linux-x64": {
+        "url": "https://github.com/NVIDIA/OpenShell/releases/download/v0.0.116/openshell-gateway-x86_64-unknown-linux-gnu.tar.gz",
+        "sha256": "59c6da724eae7a00c28826f9191efbdf4fbaa5c768afdc8dea6a80a949ebcc89"
       }
     },
     "gatewayImage": "ghcr.io/nvidia/openshell/gateway:0.0.116@sha256:05cf77bbb022a739aed6f22daa0e7e164415f4ab273b5f84319e46d91eb8f645"

package/release/operator.md

@@ -9,6 +9,17 @@ registry images by digest. Local development image IDs cannot be downloaded. The
 package is named `@clawscarf/cli` and exposes the `clawscarf` command. Development archives
 remain private; the release candidate builder makes the package publishable. [Release contents](README.md) defines the publication model.
 
+## Install from npm
+
+```sh
+npm install -g @clawscarf/cli@next
+clawscarf configure
+```
+
+The `next` tag selects the current alpha. Use an exact version instead when needed.
+npm installs the CLI dependencies; runtime images and tools are fetched during setup.
+See [release contents](README.md) for supported platforms and verification.
+
 ## Run the archive
 
 Verify the archive against its accompanying `SHA256SUMS`, then extract it into a new
@@ -28,7 +39,8 @@ Dependencies are installed from the included frozen lockfile. Its root importer
 contains only the production dependencies referenced by the staged operator;
 publisher and browser dependencies are omitted. Locked transitive versions are retained.
 No TypeScript compiler, contributor source or build step is needed to run the commands.
-The current local assembly supports macOS arm64 with Docker Desktop only.
+Platform support is determined by the selected runtime definition. Published candidates
+include macOS arm64 and Linux arm64/x86-64 tools; Windows runs the Linux CLI inside WSL2.
 
 The installer reviews recipe settings before credentials, prepares the installation,
 and offers **Start now**. It starts Docker services and protected OpenShell containers, then exits; closing

package/runtime/releases/0.1.0-alpha.2.json

@@ -0,0 +1,63 @@
+{
+  "schemaVersion": 1,
+  "version": "0.1.0-alpha.2",
+  "sourceRevision": "dc08bf392bad89efabce65bdd56e93c508553203",
+  "platforms": [
+    "darwin-arm64",
+    "linux-arm64",
+    "linux-x64"
+  ],
+  "images": {
+    "postgres": "postgres@sha256:742f40ea20b9ff2ff31db5458d127452988a2164df9e17441e191f3b72252193",
+    "gateway": "ghcr.io/clawscarf/clawscarf/runtime@sha256:01105abab6d0b6330b55022187dd3367d552c2b66f6ddca5c0bb0279740a9bd3",
+    "companion": "ghcr.io/clawscarf/clawscarf/companion@sha256:1cb04a8c4ec5a65c74095b54dfa63a0154621158348f7e8315b30e0679d8a3d0",
+    "openshellClient": "ghcr.io/clawscarf/clawscarf/openshell-client@sha256:9aef63fd71cf55b8eb3971db1f49f2f5c9a467f782b699059f599dce2ea3beb4",
+    "relay": "ghcr.io/clawscarf/clawscarf/browser-relay@sha256:a80196a2dcc9a7835947ba69bd75c7e704db1b5cedac28bbc8670a675eeb5dec",
+    "models": "ghcr.io/berriai/litellm:v1.100.1@sha256:a3715fa7ad8387941ab697259bd2881d68931657247a41984f90fae6d11c62bf",
+    "browser": {
+      "chromium": "ghcr.io/clawscarf/clawscarf/browser@sha256:6c8e0302ad8ce118440f4794772149cf4a621e9fa9d580492e24269efcc7618d",
+      "node": "ghcr.io/clawscarf/clawscarf/browser-node@sha256:47c9f847167eb8a9956b600f4f97310ede7428833f60bdbacfd3c0f91fee7da6",
+      "dns": "ghcr.io/clawscarf/clawscarf/browser-dns@sha256:f83d0bc00f8f71d6d809b5057eb5edbf4573b5e1565a8292dbe36021802c4c0b",
+      "egress": "ghcr.io/clawscarf/clawscarf/browser-egress@sha256:a863dcfe890596aa8824d2c35e503afe5ddeeb763d3eef83ce582eb4ea6fa595"
+    }
+  },
+  "tools": {
+    "openshell": {
+      "version": "0.0.116",
+      "cli": {
+        "darwin-arm64": {
+          "file": "tools/darwin-arm64/openshell",
+          "sha256": "0baeeffe0e4c184b08fde910ac9e8815fb0b8cfb808e49c0e634d7db65fb03bb",
+          "url": "https://github.com/clawscarf/clawscarf/releases/download/v0.1.0-alpha.2/openshell-darwin-arm64"
+        },
+        "linux-arm64": {
+          "file": "tools/linux-arm64/openshell",
+          "sha256": "84df9f059b16b66c83748606cc87d9edcda84b57effea19543f5c368aba7eb18",
+          "url": "https://github.com/clawscarf/clawscarf/releases/download/v0.1.0-alpha.2/openshell-linux-arm64"
+        },
+        "linux-x64": {
+          "file": "tools/linux-x64/openshell",
+          "sha256": "24e85062073d512d1951c76cd3890b7bce1ab01cc36a08f88b3b43c067a402da",
+          "url": "https://github.com/clawscarf/clawscarf/releases/download/v0.1.0-alpha.2/openshell-linux-x64"
+        }
+      },
+      "gateway": {
+        "darwin-arm64": {
+          "file": "tools/darwin-arm64/openshell-gateway",
+          "sha256": "298706259ef18350f334c222e981e91583558511d50bce22727c689d261203e6",
+          "url": "https://github.com/clawscarf/clawscarf/releases/download/v0.1.0-alpha.2/openshell-gateway-darwin-arm64"
+        },
+        "linux-arm64": {
+          "file": "tools/linux-arm64/openshell-gateway",
+          "sha256": "0e660428e655e7481f34ba8a4b351554400baf791863d32555c98dddb3f09ae2",
+          "url": "https://github.com/clawscarf/clawscarf/releases/download/v0.1.0-alpha.2/openshell-gateway-linux-arm64"
+        },
+        "linux-x64": {
+          "file": "tools/linux-x64/openshell-gateway",
+          "sha256": "780fc7ad871e2163f3fb866a2d0254ee682fc0d83e6261a84b350c8dcdd9f47b",
+          "url": "https://github.com/clawscarf/clawscarf/releases/download/v0.1.0-alpha.2/openshell-gateway-linux-x64"
+        }
+      }
+    }
+  }
+}

package/scripts/controller.js

@@ -11,6 +11,7 @@ const settingsSchema = z.strictObject({
     port: z.number().int().min(1024).max(65535),
     gateway: z.string().min(1),
     cli: z.string().min(1),
+    hostGatewayIp: z.ipv4().optional(),
 });
 const releaseInput = JSON.parse(await readFile(new URL("../release/components.json", import.meta.url), "utf8"));
 const release = z
@@ -75,6 +76,7 @@ gateway_id = ${JSON.stringify(settings.name)}
 ttl_secs = 0
 [openshell.drivers.docker]
 network_name = ${JSON.stringify(settings.name)}
+${settings.hostGatewayIp ? `host_gateway_ip = ${JSON.stringify(settings.hostGatewayIp)}` : ""}
 sandbox_namespace = ${JSON.stringify(settings.name)}
 supervisor_image = ${JSON.stringify(release.supervisorImage)}
 image_pull_policy = "IfNotPresent"
@@ -91,6 +93,7 @@ command
     .requiredOption("--directory <path>", "New private controller directory")
     .requiredOption("--gateway <path>", "Verified openshell-gateway executable")
     .requiredOption("--cli <path>", "Verified openshell executable")
+    .option("--host-gateway-ip <address>", "Controller address on the runtime bridge")
     .option("--name <name>", "Isolated controller name", "clawscarf")
     .option("--port <port>", "Loopback controller port", "17671")
     .action(async (options) => {
@@ -101,6 +104,7 @@ command
         port: Number(options.port),
         gateway: resolve(options.gateway),
         cli: resolve(options.cli),
+        hostGatewayIp: options.hostGatewayIp,
     });
     await verifyExecutable(settings.gateway);
     await verifyExecutable(settings.cli);
@@ -115,6 +119,8 @@ command
         "localhost",
         "--server-san",
         "host.openshell.internal",
+        "--server-san",
+        "controller.clawscarf.internal",
     ], { timeout: 30000 });
     const mtls = join(directory, "config/openshell/gateways", settings.name, "mtls");
     await mkdir(mtls, { recursive: true, mode: 0o700 });

package/scripts/deployment/browser-node-compose.js

@@ -41,7 +41,6 @@ export function browserNodeServices(state, directory, browserAddress, prepared)
             image: state.input.relayImage,
             user: String(process.getuid?.() ?? 1000),
             networks: { machine: { ipv4_address: addresses.ingress }, default: {} },
-            extra_hosts: ["host.docker.internal:host-gateway"],
             environment: {
                 CLAWSCARF_NODE_INGRESS_ADDRESS: addresses.ingress,
                 CLAWSCARF_NODE_GATEWAY_PORT: String(state.input.ports.native),

package/scripts/deployment/certificates.js

@@ -64,7 +64,7 @@ export async function ensureCertificates(directory) {
         "-subj",
         "/CN=ClawScarf local management",
         "-addext",
-        "subjectAltName=DNS:localhost,DNS:host.docker.internal,IP:127.0.0.1",
+        "subjectAltName=DNS:localhost,DNS:host.docker.internal,DNS:models.clawscarf.internal,IP:127.0.0.1",
         "-addext",
         "basicConstraints=critical,CA:TRUE",
     ]);

package/scripts/deployment/compose.js

@@ -6,7 +6,7 @@ import { resourceNames } from "./state.js";
 import { run } from "./process.js";
 import { modelGatewayServices } from "./model-gateway-compose.js";
 import { postgresImage } from "./images.js";
-export function composeConfiguration(state, directory, browserAddress, browserMachine) {
+export function composeConfiguration(state, directory, controllerAddress, browserAddress, browserMachine, controllerSocketGroup = 0) {
     const { input, ownerId } = state;
     const names = resourceNames(state);
     const privateDirectory = join(directory, "private");
@@ -23,7 +23,7 @@ export function composeConfiguration(state, directory, browserAddress, browserMa
     const configuration = {
         name: names.project,
         services: {
-            ...controllerServices(directory, state),
+            ...controllerServices(directory, state, controllerAddress, controllerSocketGroup),
             ...modelGatewayServices(directory, state),
             ...(input.browser && browserAddress && browserMachine
                 ? browserNodeServices(state, directory, browserAddress, browserMachine)
@@ -153,9 +153,7 @@ export function composeConfiguration(state, directory, browserAddress, browserMa
             },
         },
         networks: {
-            ...(input.relayImage
-                ? { runtime: { external: true, name: names.sandbox } }
-                : {}),
+            runtime: { external: true, name: names.sandbox },
             default: { external: true, name: `${names.project}_default` },
             ...(input.browser
                 ? {

package/scripts/deployment/configuration.js

@@ -187,8 +187,8 @@ export const localInput = z
 export function parseLocalInput(value) {
     return localInput.parse(value);
 }
-export function managementOrigin(input) {
-    return `https://host.docker.internal:${String(input.ports.management)}`;
+export function managementOrigin() {
+    return "https://localhost:18801";
 }
 function mountedPrivateFile(directory, path, name) {
     absolutePath.parse(path);
@@ -224,10 +224,10 @@ export function generateLocalConfiguration(options) {
             port: 18801,
         },
         runtime: {
-            origin: `http://host.docker.internal:${String(input.ports.native)}`,
-            managementOrigin: managementOrigin(input),
+            origin: `http://application:${String(input.ports.native)}`,
+            managementOrigin: managementOrigin(),
             widgetOrigin,
-            widgetUpstream: `http://host.docker.internal:${String(input.ports.nativeWidgets)}`,
+            widgetUpstream: `http://widgets:${String(input.ports.nativeWidgets)}`,
         },
         ...(input.team.certificateFile
             ? {

package/scripts/deployment/controller-compose.js

@@ -2,13 +2,14 @@ import { join } from "node:path";
 import { openshellGatewayImage } from "./images.js";
 import { resourceNames } from "./state.js";
 /** OpenShell alone receives Docker authority. Forwarders receive only client credentials. */
-export function controllerServices(directory, state) {
+export function controllerServices(directory, state, address, socketGroup) {
     const controller = join(directory, "controller");
     const { input } = state;
     const name = resourceNames(state).sandbox;
     const port = input.ports.controller;
     const forward = (target, port) => ({
         image: input.openshellClientImage,
+        user: `${String(process.getuid?.() ?? 1000)}:${String(process.getgid?.() ?? 1000)}`,
         init: true,
         read_only: true,
         cap_drop: ["ALL"],
@@ -21,23 +22,31 @@ export function controllerServices(directory, state) {
             XDG_DATA_HOME: "/tmp/data",
         },
         volumes: [`${join(controller, "config")}:/controller/config:ro`],
-        extra_hosts: ["host.openshell.internal:host-gateway"],
         command: [
             "forward",
-            "start",
+            "service",
+            "--target-port",
+            String(port),
+            "--local",
             `0.0.0.0:${String(port)}`,
             target,
             "--gateway",
             name,
             "--gateway-endpoint",
-            `https://host.openshell.internal:${String(input.ports.controller)}`,
+            `https://controller.clawscarf.internal:${String(input.ports.controller)}`,
         ],
         ports: [`127.0.0.1:${String(port)}:${String(port)}`],
     });
     return {
         controller: {
             image: openshellGatewayImage,
-            user: "0:0",
+            user: `${String(process.getuid?.() ?? 1000)}:${String(process.getgid?.() ?? 1000)}`,
+            // Desktop exposes a root-group socket; Linux Engine uses the host socket's group.
+            group_add: [...new Set(["0", String(socketGroup)])],
+            networks: {
+                default: { aliases: ["controller.clawscarf.internal"] },
+                runtime: { ipv4_address: address },
+            },
             command: ["--config", join(controller, "gateway.toml")],
             environment: {
                 XDG_CONFIG_HOME: join(controller, "config"),
@@ -51,7 +60,6 @@ export function controllerServices(directory, state) {
                 "/var/run/docker.sock:/var/run/docker.sock",
             ],
             ports: [`127.0.0.1:${String(port)}:${String(port)}`],
-            extra_hosts: ["host.openshell.internal:host-gateway"],
         },
         application: forward(name, input.ports.native),
         widgets: forward(name, input.ports.nativeWidgets),

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

@@ -28,6 +28,12 @@ export function modelGatewayServices(directory, state) {
         },
         models: {
             image: input.image,
+            user: `${String(process.getuid?.() ?? 1000)}:${String(process.getgid?.() ?? 1000)}`,
+            environment: { HOME: "/tmp" },
+            networks: {
+                default: {},
+                runtime: { aliases: ["models.clawscarf.internal"] },
+            },
             init: true,
             read_only: true,
             cap_drop: ["ALL"],

package/scripts/deployment/model-gateway.js

@@ -43,6 +43,14 @@ export async function prepareModelGateway(directory, state, options = {}) {
         return;
     const loaded = await loadGatewayConfiguration(input.configurationFile, input.upstreamEnvironmentFile);
     const root = join(directory, "private/models");
+    let baseUrl = "https://models.clawscarf.internal:4000/v1";
+    if (options.replaceConfiguration) {
+        const current = configurationSchema.parse(JSON.parse(await readFile(join(root, "native.json"), "utf8")));
+        if (current.mode !== "litellm")
+            throw new LocalSetupError("invalid_model_setup", "Expected an existing model gateway.");
+        // Model choices do not change the installation's retained network endpoint.
+        baseUrl = current.baseUrl;
+    }
     await mkdir(root, { recursive: true, mode: 0o700 });
     for (const [name, prefix] of [
         ["master-key", "sk-"],
@@ -74,7 +82,7 @@ export async function prepareModelGateway(directory, state, options = {}) {
     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`,
+        baseUrl,
     }));
 }
 export async function prepareModelCredential(directory, state) {

package/scripts/deployment/networks.js

@@ -264,6 +264,10 @@ export async function ensureLocalNetworks(directory, state, command = run) {
                     "create",
                     "--driver",
                     "bridge",
+                    // Docker chooses a free subnet; declaring its size permits static endpoints.
+                    ...(intent.purpose !== "companion"
+                        ? ["--subnet", "0.0.0.0/24"]
+                        : []),
                     ...(intent.purpose === "runtime" ? ["--attachable"] : []),
                     ...(["browser", "machine"].includes(intent.purpose)
                         ? [
@@ -352,3 +356,20 @@ export async function observedBrowserMachineAddresses(directory, state, command
         changed();
     return { node: observed.isolated.address, ingress, dns };
 }
+/** Stable address on the owned runtime bridge for the containerized OpenShell controller. */
+export async function observedControllerAddress(directory, state) {
+    await verifyLocalNetworks(directory, state);
+    const configs = z
+        .array(z.object({ Subnet: z.string(), Gateway: z.string() }))
+        .parse(JSON.parse(await run("docker", [
+        "network",
+        "inspect",
+        resourceNames(state).sandbox,
+        "--format",
+        "{{json .IPAM.Config}}",
+    ])));
+    const config = configs.find((item) => isIP(item.Gateway) === 4);
+    if (!config)
+        changed();
+    return reservedAddress(config).address;
+}

package/scripts/deployment/prepare.js

@@ -8,10 +8,10 @@ import { prepareRelay } from "./relay.js";
 import { prepareRuntimePolicy } from "./policy.js";
 import { prepareBrowser, initializeBrowserVolume } from "./browser.js";
 import { readTeamMaterials, prepareTeamFiles } from "./team.js";
-import { readFile, lstat } from "node:fs/promises";
+import { readFile, lstat, stat } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { prepareInitialModels, withInitialModels, } from "./models.js";
-import { ensureLocalNetworks } from "./networks.js";
+import { ensureLocalNetworks, observedControllerAddress } from "./networks.js";
 import { nodeEntrypoint } from "./entrypoint.js";
 import { ensureCertificates } from "./certificates.js";
 import { z } from "zod";
@@ -29,8 +29,9 @@ export async function prepareLocal(directoryInput, inputValue, capabilities) {
     const input = parseLocalInput(inputValue);
     const connections = await loadInitialConnections(input.connections);
     const teamMaterials = await readTeamMaterials(input.team);
-    if (process.platform !== "darwin" || process.arch !== "arm64")
-        throw new LocalSetupError("platform_unqualified", "This local assembly currently requires macOS arm64 with Docker Desktop; other platforms need qualification.");
+    if (!["darwin", "linux"].includes(process.platform) ||
+        !["arm64", "x64"].includes(process.arch))
+        throw new LocalSetupError("platform_unqualified", "Use macOS or Linux (including WSL2) with Linux Docker containers.");
     for (const image of [
         input.runtimeImage,
         input.openshellClientImage,
@@ -71,6 +72,7 @@ export async function prepareLocal(directoryInput, inputValue, capabilities) {
     const connectionsEndpoint = await prepareInitialConnections(directory, connections);
     await prepareModelGateway(directory, state);
     await ensureLocalNetworks(directory, state);
+    const controllerAddress = await observedControllerAddress(directory, state);
     const browser = await prepareBrowser(directory, state);
     const browserMachine = browser
         ? await prepareBrowserNode(directory, state, browser.token)
@@ -86,7 +88,9 @@ export async function prepareLocal(directoryInput, inputValue, capabilities) {
         await ensureOwnedVolume(names.browserVolume, state.ownerId);
         await initializeBrowserVolume(state, browser.token);
     }
-    await ensurePrivateFile(join(directory, "compose.json"), JSON.stringify(composeConfiguration(state, directory, browser?.address, browserMachine), null, 2));
+    await ensurePrivateFile(join(directory, "compose.json"), JSON.stringify(composeConfiguration(state, directory, controllerAddress, browser?.address, browserMachine, process.platform === "linux"
+        ? (await stat("/var/run/docker.sock")).gid
+        : 0), null, 2));
     await prepareModelCredential(directory, state);
     const models = await prepareInitialModels(directory, input.models);
     await prepareRuntimePolicy(directory, models, connectionsEndpoint);
@@ -151,6 +155,8 @@ export async function prepareLocal(directoryInput, inputValue, capabilities) {
             input.openshellGateway,
             "--cli",
             input.openshellCli,
+            "--host-gateway-ip",
+            controllerAddress,
             "--name",
             names.sandbox,
             "--port",

package/scripts/installation/installer/prompts.js

@@ -66,7 +66,11 @@ export const terminalPrompts = {
     note: clack.note,
     async openBrowser(url) {
         try {
-            await promisify(execFile)(process.platform === "darwin" ? "open" : "xdg-open", [url], { timeout: 5000 });
+            await promisify(execFile)(process.platform === "darwin"
+                ? "open"
+                : process.env.WSL_DISTRO_NAME
+                    ? "explorer.exe"
+                    : "xdg-open", [url], { timeout: 5000 });
         }
         catch {
             process.stderr.write("Could not open a browser. Open the link above manually.\n");

package/scripts/installation/prerequisites.js

@@ -12,8 +12,9 @@ import { acquireRuntimeTools } from "./runtime.js";
 import { InstallationError } from "./errors.js";
 /** No configuration, credentials or cloud account is needed for these checks. */
 export async function checkHost(command = run) {
-    if (process.platform !== "darwin" || process.arch !== "arm64")
-        throw new InstallationError("unsupported_platform", "This release requires macOS on Apple Silicon with Docker Desktop.");
+    if (!["darwin", "linux"].includes(process.platform) ||
+        !["arm64", "x64"].includes(process.arch))
+        throw new InstallationError("unsupported_platform", "Use macOS or Linux (including WSL2), with an ARM64 or x86-64 processor and Linux Docker containers. Run the Windows CLI inside WSL2.");
     let os;
     try {
         os = await command("docker", ["info", "--format", "{{.OSType}}"]);
@@ -23,8 +24,8 @@ export async function checkHost(command = run) {
             error.commandFailure?.reason === "spawn" &&
             error.commandFailure.systemCode === "ENOENT";
         throw new InstallationError("unavailable", missing
-            ? "Docker is not installed or is not on PATH. Install Docker Desktop, start it, then run configure again."
-            : "Cannot reach Docker. Start Docker Desktop and wait until it is running, then try again.");
+            ? "Docker is not installed or is not on PATH. Install Docker Engine with Compose or Docker Desktop, then run configure again."
+            : "Cannot reach Docker. Start Docker and check that your user can access its socket, then try again.");
     }
     if (os.trim() !== "linux")
         throw new InstallationError("unsupported_platform", "Docker must run Linux containers.");
@@ -32,8 +33,12 @@ export async function checkHost(command = run) {
         await command("docker", ["compose", "version"]);
     }
     catch {
-        throw new InstallationError("unavailable", "Docker Compose is unavailable. Install or update Docker Desktop, then try again.");
+        throw new InstallationError("unavailable", "Docker Compose is unavailable. Install the Docker Compose plugin or update Docker Desktop, then try again.");
     }
+    const version = (await command("docker", ["version", "--format", "{{.Server.Version}}"])).trim();
+    const major = Number(/^([0-9]+)\./.exec(version)?.[1]);
+    if (!Number.isInteger(major) || major < 29)
+        throw new InstallationError("unsupported_platform", "Docker Engine 29 or newer is required for automatic subnet allocation with fixed service addresses. Update Docker Engine or Docker Desktop, then try again.");
 }
 /** Stream only Docker's layer progress, never registry error payloads or credentials. */
 export function pullImage(image, report, signal) {

package/scripts/installation/resolve.js

@@ -3,7 +3,7 @@ import { hostedOidc, hostedConnections } from "../cloud/registration.js";
 import { dirname, resolve, join } from "node:path";
 import { loadGatewayConfiguration } from "../deployment/model-gateway.js";
 import { createServer } from "node:net";
-import { releaseSchema } from "../release/definition.js";
+import { releaseSchema, releaseTools } from "../release/definition.js";
 import { parseLocalInput, } from "../deployment/configuration.js";
 import { loadInitialModels } from "../deployment/models.js";
 import { loadInitialConnections, readInitialConnectionToken, } from "../deployment/connections.js";
@@ -49,10 +49,11 @@ export async function resolveInstallation(configFile, internalPorts) {
     if (!release.platforms.some((platform) => platform === `${process.platform}-${process.arch}`))
         throw new InstallationError("unsupported_platform", "This release does not support this host platform.");
     const toolBase = dirname(releasePath);
-    const cli = resolve(toolBase, release.tools.openshell.cli.file);
-    const gateway = resolve(toolBase, release.tools.openshell.gateway.file);
-    await verifyReleaseTool(cli, release.tools.openshell.cli.sha256);
-    await verifyReleaseTool(gateway, release.tools.openshell.gateway.sha256);
+    const tools = releaseTools(release);
+    const cli = resolve(toolBase, tools.cli.file);
+    const gateway = resolve(toolBase, tools.gateway.file);
+    await verifyReleaseTool(cli, tools.cli.sha256);
+    await verifyReleaseTool(gateway, tools.gateway.sha256);
     const [controller, management, native, nativeWidgets, database, browser, models,] = internalPorts;
     const inputs = {};
     async function inputFile(value, secret) {

package/scripts/installation/runtime.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { chmod, copyFile, mkdir, open, rename, rm, writeFile, } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
-import { releaseSchema } from "../release/definition.js";
+import { releaseSchema, releaseTools } from "../release/definition.js";
 import { readJson, verifyReleaseTool } from "./files.js";
 import { InstallationError } from "./errors.js";
 /** Installation-owned paths survive npm cache cleanup and later CLI updates. */
@@ -10,7 +10,7 @@ export async function retainRuntime(source, directory) {
     const target = join(directory, "runtime");
     await mkdir(join(target, "tools"), { recursive: true, mode: 0o700 });
     for (const name of ["cli", "gateway"]) {
-        const tool = release.tools.openshell[name];
+        const tool = releaseTools(release)[name];
         const original = resolve(dirname(source), tool.file);
         tool.file = `tools/openshell${name === "gateway" ? "-gateway" : ""}`;
         try {
@@ -34,7 +34,7 @@ export async function acquireRuntimeTools(releaseFile, options) {
     const release = releaseSchema.parse(await readJson(releaseFile));
     for (const name of ["cli", "gateway"]) {
         options.signal?.throwIfAborted();
-        const tool = release.tools.openshell[name];
+        const tool = releaseTools(release)[name];
         const file = resolve(dirname(releaseFile), tool.file);
         try {
             await verifyReleaseTool(file, tool.sha256);

package/scripts/release/definition.js

@@ -15,12 +15,18 @@ const file = z.strictObject({
     }, "Tool downloads require HTTPS without credentials.")
         .optional(),
 });
+export const hostPlatformSchema = z.enum([
+    "darwin-arm64",
+    "linux-arm64",
+    "linux-x64",
+]);
+const tool = z.union([file, z.partialRecord(hostPlatformSchema, file)]);
 /** Pinned runtime metadata, independent of recipe defaults and deployment state. */
 export const releaseSchema = z.strictObject({
     schemaVersion: z.literal(1),
     version: z.string().regex(/^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/),
     sourceRevision: z.string().regex(/^[a-f0-9]{40}$/),
-    platforms: z.array(z.literal("darwin-arm64")).min(1).max(1),
+    platforms: z.array(hostPlatformSchema).min(1),
     images: z
         .strictObject({
         postgres: z.literal(postgresImage),
@@ -44,8 +50,29 @@ export const releaseSchema = z.strictObject({
     tools: z.strictObject({
         openshell: z.strictObject({
             version: z.string().min(1),
-            cli: file,
-            gateway: file,
+            cli: tool,
+            gateway: tool,
         }),
     }),
 });
+/** Single-platform development bundles and multi-platform published bundles share resolution. */
+export function releaseTools(release, platform = `${process.platform}-${process.arch}`) {
+    const host = hostPlatformSchema.parse(platform);
+    if (!release.platforms.includes(host))
+        throw new Error(`Runtime ${release.version} does not include ${host}.`);
+    const select = (value) => {
+        if ("file" in value) {
+            if (release.platforms.length !== 1)
+                throw new Error("Multi-platform runtimes require a tool for each platform.");
+            return value;
+        }
+        const selected = value[host];
+        if (!selected)
+            throw new Error(`Missing runtime tool for ${host}.`);
+        return selected;
+    };
+    return {
+        cli: select(release.tools.openshell.cli),
+        gateway: select(release.tools.openshell.gateway),
+    };
+}

package/runtime/releases/0.1.0-alpha.1.json

@@ -1,37 +0,0 @@
-{
-  "schemaVersion": 1,
-  "version": "0.1.0-alpha.1",
-  "sourceRevision": "a53e95251321e61d8ffd6d06a6984f651c0b0db4",
-  "platforms": [
-    "darwin-arm64"
-  ],
-  "images": {
-    "postgres": "postgres@sha256:742f40ea20b9ff2ff31db5458d127452988a2164df9e17441e191f3b72252193",
-    "gateway": "ghcr.io/clawscarf/clawscarf/runtime@sha256:eaa25c8e487970176b95de657df8bf4faff605f9f265ca760197800d9a1e5fcf",
-    "companion": "ghcr.io/clawscarf/clawscarf/companion@sha256:97cfeb78ab56ba625b30aafe2249633d9b69f7f3c75de7116453385010e6281f",
-    "openshellClient": "ghcr.io/clawscarf/clawscarf/openshell-client@sha256:669f37f654926fc7714783cc8b1b76bae9666895c2a4da959580037d281ebf56",
-    "relay": "ghcr.io/clawscarf/clawscarf/browser-relay@sha256:5ee13e9496e3b76e076e91c59a861a10ad7a31a13b145384fba314d7f0b686b5",
-    "models": "ghcr.io/berriai/litellm:v1.100.1@sha256:a3715fa7ad8387941ab697259bd2881d68931657247a41984f90fae6d11c62bf",
-    "browser": {
-      "chromium": "ghcr.io/clawscarf/clawscarf/browser@sha256:28ca9e4007d3b7c1bb9cb8f4bbaf275d1bc36ee2744079326b151b1f9eec78fd",
-      "node": "ghcr.io/clawscarf/clawscarf/browser-node@sha256:2837d8b75df69fb39c7f7ca8fa68249d9de6e20d4e028213792de5f8f9ef1bd7",
-      "dns": "ghcr.io/clawscarf/clawscarf/browser-dns@sha256:9f14cb85df522014c2bfc068e2b5788568f26b6e8d948cebe1250aff7630847b",
-      "egress": "ghcr.io/clawscarf/clawscarf/browser-egress@sha256:bd819dffa4e1f60fbeed3b459a26b3b274300a4e5836bb90cbd080f6681d594c"
-    }
-  },
-  "tools": {
-    "openshell": {
-      "version": "0.0.116",
-      "cli": {
-        "file": "tools/openshell",
-        "sha256": "0baeeffe0e4c184b08fde910ac9e8815fb0b8cfb808e49c0e634d7db65fb03bb",
-        "url": "https://github.com/clawscarf/clawscarf/releases/download/v0.1.0-alpha.1/openshell-darwin-arm64"
-      },
-      "gateway": {
-        "file": "tools/openshell-gateway",
-        "sha256": "298706259ef18350f334c222e981e91583558511d50bce22727c689d261203e6",
-        "url": "https://github.com/clawscarf/clawscarf/releases/download/v0.1.0-alpha.1/openshell-gateway-darwin-arm64"
-      }
-    }
-  }
-}