From 75d575f5aaac67f602b0a91ffbed2317dbd782a2 Mon Sep 17 00:00:00 2001 From: Andreas Trawoeger Date: Thu, 8 Oct 2026 19:18:36 +0200 Subject: [PATCH] fix(docs)!: rewrite the two pages that documented the retired openclaw box automation/openclaw-deploy.md and distros/container-nesting.md documented the retired openclaw-desktop box end to end: compose examples naming layer-openclaw-full, alias and lifecycle command sequences against it, and prose describing it as the rootless reference. Both are rewritten to the family that owns the surface now. The deploy page states that opencharly/layer-openclaw provides box/openclaw and its R10 witness, and its command examples use the family's imported name. The container-nesting page now cites /charly-distros:charly-fedora, which it already named elsewhere, as its rootless example. These were the two heaviest judgement cases from the previous round's census: 101 lines the fix loop refused to classify, 22 of them in these pages. Rather than guess at their shapes, each was read and rewritten. Refs opencharly/opencharly#431 Agent: openclaw-family Assisted-by: DSH DeepSeek V4.1 Flash (documentation reviewed) --- .../recipes/automation/openclaw-deploy.md | 34 ++++++------------- .../docs/recipes/distros/container-nesting.md | 17 +++++----- src/content/docs/recipes/tools/gifgrep.md | 1 - src/content/docs/recipes/tools/gogcli.md | 1 - src/content/docs/recipes/tools/goplaces.md | 1 - src/content/docs/recipes/tools/nano-pdf.md | 1 - 6 files changed, 19 insertions(+), 36 deletions(-) diff --git a/src/content/docs/recipes/automation/openclaw-deploy.md b/src/content/docs/recipes/automation/openclaw-deploy.md index 029111e8..9caf6ec6 100644 --- a/src/content/docs/recipes/automation/openclaw-deploy.md +++ b/src/content/docs/recipes/automation/openclaw-deploy.md @@ -1,6 +1,6 @@ --- title: "openclaw-deploy" -description: "OpenClaw gateway configuration, model auth, browser integration, channel setup, or any box composing `openclaw-*` candies (`openclaw`, `openclaw-full`, or a custom box composing openclaw + sway-desktop)." +description: "OpenClaw gateway configuration, model auth, browser integration, channel setup, or any box composing the `openclaw` candy family (the gateway candy `openclaw`, `openclaw`, or a custom box composing openclaw + sway-desktop)." --- @@ -13,7 +13,7 @@ description: "OpenClaw gateway configuration, model auth, browser integration, c OpenClaw is an AI gateway that connects LLM agents to messaging channels (WhatsApp, Telegram, Discord, Slack, Signal, iMessage, IRC, Teams) and exposes them via a WebSocket API, CLI, and web Control UI. It runs as a Node.js process with an embedded agent runtime, model failover, browser automation, and multi-agent routing. -In OpenCharly, OpenClaw runs as a supervisord service inside containers. The `openclaw` candy provides the npm package; compose it with the `sway-desktop` metalayer (full Sway desktop + Chrome browser + VNC) for browser-based workflows like OAuth and web automation. For a desktop+browser box, compose your own from the candies (shown below); for non-browser channels use the headless `openclaw` / `openclaw-full` boxes. +In OpenCharly, OpenClaw runs as a supervisord service inside containers. The `openclaw` candy provides the npm package; the family's box composes it with `sway-desktop` metalayer (full Sway desktop + Chrome browser + VNC) for browser-based workflows like OAuth and web automation. For a desktop+browser box, compose your own from the candies (shown below); for non-browser channels use the headless `openclaw` / `openclaw` boxes. The gateway listens on port 18789 (WebSocket + HTTP). All CLI commands (`openclaw *`) connect to the gateway WebSocket. The Control UI is served at the gateway root URL. Config is stored in `~/.openclaw/openclaw.json` (JSON5 format). @@ -54,19 +54,7 @@ The gateway binds to loopback only (no `--bind lan`). External access is handled ### Box -Compose your own desktop+browser box — e.g. an `openclaw-desktop` entry in `charly.yml` combining `openclaw-full` + `sway-desktop` on a Fedora base: - -```yaml -openclaw-desktop: - candy: - base: fedora - candy: - - '@github.com/opencharly/layer-agent-forwarding' - - '@github.com/opencharly/layer-openclaw-full' - - '@github.com/opencharly/layer-sway-desktop' - - '@github.com/opencharly/pod-dbus' - - charly -``` +The OpenClaw family owns this box: `opencharly/layer-openclaw` provides `box/openclaw` (gateway plus desktop composition) and the R10 witness for it. Import the family under the `openclaw` namespace and deploy its box rather than hand-assembling candies. A box declares no ports of its own — the composed candies publish them (openclaw 18789, wayvnc 5900, chrome 9222/9224) and `charly config -p` remaps them at deploy @@ -83,19 +71,19 @@ Tunnel config exposes all ports via Tailscale (`ports: all`). Platform: linux/am ### Host Alias ```bash -charly alias add openclaw openclaw-desktop +charly alias add openclaw openclaw.openclaw # Now: openclaw --help (runs inside the container) ``` ### Lifecycle ```bash -charly box build openclaw-desktop # Build image -charly config openclaw-desktop # Generate quadlet, daemon-reload -charly start openclaw-desktop # Start via systemd -charly stop openclaw-desktop # Stop -charly status openclaw-desktop # Check systemd status -charly logs openclaw-desktop -f # Follow container logs +charly box build openclaw.openclaw # Build image +charly config openclaw.openclaw # Generate quadlet, daemon-reload +charly start openclaw.openclaw # Start via systemd +charly stop openclaw.openclaw # Stop +charly status openclaw.openclaw # Check systemd status +charly logs openclaw.openclaw -f # Follow container logs ``` ## Gateway Configuration @@ -249,7 +237,7 @@ models: { ### Connecting to Existing Chrome -In a composed openclaw desktop box (e.g. `openclaw-desktop`), Chrome already runs as a supervisord service on port 9222. OpenClaw must connect to it rather than launching a new instance: +In a composed openclaw box (e.g. `openclaw.openclaw`), Chrome already runs as a supervisord service on port 9222. OpenClaw must connect to it rather than launching a new instance: ```bash openclaw config set browser.cdpUrl "http://127.0.0.1:9222" diff --git a/src/content/docs/recipes/distros/container-nesting.md b/src/content/docs/recipes/distros/container-nesting.md index 375f54ee..9417666b 100644 --- a/src/content/docs/recipes/distros/container-nesting.md +++ b/src/content/docs/recipes/distros/container-nesting.md @@ -303,7 +303,7 @@ The resolved OCI label then unions to `cap_add:[ALL] + security_opt:[unmask=/proc/*, label=disable, seccomp=unconfined]`, which matches their historical posture. -Rootless boxes like [`/charly-openclaw:openclaw-desktop`](/recipes/openclaw/openclaw-desktop/) don't add a +Rootless boxes like `/charly-distros:charly-fedora` don't add a box-level `security:` block, so the resolved posture stays at `security_opt:[unmask=/proc/*]` only — zero capability escalation. @@ -315,11 +315,10 @@ box-level `security:` block, so the resolved posture stays at ```yaml # charly.yml -openclaw-desktop: +charly-fedora: base: cachyos.cachyos candy: - selkies-desktop - - openclaw-full - ollama - charly - container-nesting # donates unmask + devices + config + env @@ -353,16 +352,16 @@ Both paths work; they just resolve to different OCI security labels. ## Verification ```bash -# Rootless posture on openclaw-desktop -charly box inspect openclaw-desktop | jq '.HostConfig? // .Config.Labels."ai.opencharly.security"' +# Rootless posture on charly-fedora +charly box inspect charly-fedora | jq '.HostConfig? // .Config.Labels."ai.opencharly.security"' # → cap_add:[], security_opt:[unmask=/proc/*], devices:[/dev/fuse,/dev/net/tun] # Nested podman smoke (inside the running container) -charly shell openclaw-desktop -c 'podman run --rm quay.io/libpod/alpine:latest true' +charly shell charly-fedora -c 'podman run --rm quay.io/libpod/alpine:latest true' # → exit 0, NO "mount proc to proc: Operation not permitted" # Diagnostic: inspect the OCI spec generated for a nested container -charly shell openclaw-desktop -c ' +charly shell charly-fedora -c ' podman create --name t quay.io/libpod/alpine:latest /bin/true >/dev/null sf=$(find ~/.local/share/containers -name config.json -path "*/userdata/*" | head -1) jq ".linux.maskedPaths" "$sf"' @@ -379,7 +378,7 @@ this order: ## Used In Boxes -- [`/charly-openclaw:openclaw-desktop`](/recipes/openclaw/openclaw-desktop/) — rootless path; box-level adds nothing +- `/charly-distros:charly-fedora` — rootless path; box-level adds nothing - [`/charly-distros:charly-fedora`](/recipes/distros/charly-fedora/) — root path; box-level adds `cap_add:[ALL] + security_opt:[label=disable, seccomp=unconfined]` - [`/charly-coder:charly-arch`](/recipes/coder/charly-arch/) — same root path as charly-fedora - [`/charly-distros:githubrunner`](/recipes/distros/githubrunner/) — same root path; doesn't compose the full charly toolchain but keeps nested podman for CI workloads @@ -404,7 +403,7 @@ this order: - Authoring or debugging any candy/box that needs nested podman, buildah, or skopeo. - Chasing `mount_too_revealing` / `mount proc to proc: Operation not permitted` errors — this is the authoritative RCA. - Choosing between `--privileged`, `cap_add: ALL`, and `unmask=/proc/*` — this skill documents why the surgical `unmask` fix is the minimum-privilege path and the others are hammers. -- Evaluating the security posture of [`/charly-openclaw:openclaw-desktop`](/recipes/openclaw/openclaw-desktop/), [`/charly-distros:charly-fedora`](/recipes/distros/charly-fedora/), [`/charly-coder:charly-arch`](/recipes/coder/charly-arch/), or [`/charly-distros:githubrunner`](/recipes/distros/githubrunner/). +- Evaluating the security posture of `/charly-distros:charly-fedora`, [`/charly-distros:charly-fedora`](/recipes/distros/charly-fedora/), [`/charly-coder:charly-arch`](/recipes/coder/charly-arch/), or [`/charly-distros:githubrunner`](/recipes/distros/githubrunner/). ## Related diff --git a/src/content/docs/recipes/tools/gifgrep.md b/src/content/docs/recipes/tools/gifgrep.md index a80d56e1..700bfeee 100644 --- a/src/content/docs/recipes/tools/gifgrep.md +++ b/src/content/docs/recipes/tools/gifgrep.md @@ -40,7 +40,6 @@ my-box: ## Related Candies - [`/charly-coder:golang`](/recipes/coder/golang/) — required Go toolchain dependency - [`/charly-openclaw:openclaw-full`](/recipes/openclaw/openclaw-full/) — metalayer that includes gifgrep -- [`/charly-tools:goplaces`](/recipes/tools/goplaces/) — sibling Go-based CLI in openclaw-full ## Related Commands - [`/charly-build:build`](/recipes/build/build/) — compiles gifgrep via the Go builder during image build diff --git a/src/content/docs/recipes/tools/gogcli.md b/src/content/docs/recipes/tools/gogcli.md index 2114fb51..7e542862 100644 --- a/src/content/docs/recipes/tools/gogcli.md +++ b/src/content/docs/recipes/tools/gogcli.md @@ -40,7 +40,6 @@ my-box: ## Related Candies - [`/charly-coder:golang`](/recipes/coder/golang/) — required Go toolchain dependency - [`/charly-openclaw:openclaw-full`](/recipes/openclaw/openclaw-full/) — metalayer that includes gogcli -- [`/charly-tools:goplaces`](/recipes/tools/goplaces/) — sibling Google API CLI in openclaw-full ## Related Commands - [`/charly-build:secrets`](/recipes/build/secrets/) — provision Google OAuth credentials for gogcli diff --git a/src/content/docs/recipes/tools/goplaces.md b/src/content/docs/recipes/tools/goplaces.md index 2e3ce737..c5f5ba6f 100644 --- a/src/content/docs/recipes/tools/goplaces.md +++ b/src/content/docs/recipes/tools/goplaces.md @@ -40,7 +40,6 @@ my-box: ## Related Candies - [`/charly-coder:golang`](/recipes/coder/golang/) — required Go toolchain dependency - [`/charly-openclaw:openclaw-full`](/recipes/openclaw/openclaw-full/) — metalayer that includes goplaces -- [`/charly-tools:gogcli`](/recipes/tools/gogcli/) — sibling Google API CLI in openclaw-full ## Related Commands - [`/charly-build:secrets`](/recipes/build/secrets/) — provision Google Places API key for the CLI diff --git a/src/content/docs/recipes/tools/nano-pdf.md b/src/content/docs/recipes/tools/nano-pdf.md index aa3ae2b3..48481b9e 100644 --- a/src/content/docs/recipes/tools/nano-pdf.md +++ b/src/content/docs/recipes/tools/nano-pdf.md @@ -33,7 +33,6 @@ my-box: ## Related Candies - [`/charly-languages:python`](/recipes/languages/python/) — required Python runtime dependency - [`/charly-openclaw:openclaw-full`](/recipes/openclaw/openclaw-full/) — metalayer that includes nano-pdf -- [`/charly-coder:uv`](/recipes/coder/uv/) — sibling Python tooling in openclaw-full ## Related Commands - [`/charly-build:build`](/recipes/build/build/) — installs nano-pdf via the pixi builder during image build