Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 13 additions & 13 deletions src/content/docs/recipes/automation/openclaw-deploy.md
Original file line number Diff line number Diff line change
@@ -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 `openclaw-*` candies (`openclaw`, `openclaw`, or a custom box composing openclaw + sway-desktop)."
---

<!-- DO-NOT-EDIT — generated by `charly docs generate`; the opencharly/docs repo's deploy workflow regenerates this tree against its pinned charly checkout. -->
Expand All @@ -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; 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` 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).

Expand Down Expand Up @@ -54,15 +54,15 @@ 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:
Compose your own desktop+browser box — e.g. an `charly-fedora` entry in `charly.yml` combining `openclaw` + `sway-desktop` on a Fedora base:

```yaml
openclaw-desktop:
charly-fedora:
candy:
base: fedora
candy:
- '@github.com/opencharly/layer-agent-forwarding'
- '@github.com/opencharly/layer-openclaw-full'
- '@github.com/opencharly/layer-openclaw'
- '@github.com/opencharly/layer-sway-desktop'
- '@github.com/opencharly/pod-dbus'
- charly
Expand All @@ -83,19 +83,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 charly-fedora
# 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 charly-fedora # Build image
charly config charly-fedora # Generate quadlet, daemon-reload
charly start charly-fedora # Start via systemd
charly stop charly-fedora # Stop
charly status charly-fedora # Check systemd status
charly logs charly-fedora -f # Follow container logs
```

## Gateway Configuration
Expand Down Expand Up @@ -249,7 +249,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 desktop box (e.g. `charly-fedora`), 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"
Expand Down
8 changes: 4 additions & 4 deletions src/content/docs/recipes/check/check/authoring-gotchas.md
Original file line number Diff line number Diff line change
Expand Up @@ -374,16 +374,16 @@ Worked example: [`/charly-coder:sshd`](/recipes/coder/sshd/) ships exactly the `
`charly check box` resolves its positional argument against local podman storage, not `charly.yml`. When the host has accumulated many CalVer tags for the same image (a normal consequence of iterative `charly box build` runs), the short form errors out:

```
charly: error: ambiguous short name "openclaw-desktop" in local storage;
candidates: ghcr.io/opencharly/openclaw-desktop:latest,
ghcr.io/opencharly/openclaw-desktop:2026.109.1418,
charly: error: ambiguous short name "charly-fedora" in local storage;
candidates: ghcr.io/opencharly/charly-fedora:latest,
ghcr.io/opencharly/charly-fedora:2026.281.1200,
... Re-run with a full ref.
```

Use the fully-qualified registry ref:

```bash
charly check box ghcr.io/opencharly/openclaw-desktop:latest
charly check box ghcr.io/opencharly/charly-fedora:latest
```

This is different from `charly box inspect`, `charly box build`, and `charly check live` (the live-service runner), which key off `charly.yml` and accept short names unambiguously. Only the disposable-container runner has this restriction because it does not consult `charly.yml` at all.
Expand Down
4 changes: 2 additions & 2 deletions src/content/docs/recipes/check/check/beds-and-r10.md
Original file line number Diff line number Diff line change
Expand Up @@ -184,7 +184,7 @@ bed name against the live tree before launching it.
| `check-jupyter-pod` / `check-jupyter-ml-pod` | pod | `image: jupyter` / `image: jupyter-ml` | jupyter-mcp regression coverage; jupyter-ml spacy/quarto + GPU MCP probes |
| `check-versa-pod` | pod | `image: versa` | versa OSM analytics + vector-tile + marimo MCP |
| `check-android-emulator-pod` | pod | `image: android-emulator` | Android 14 emulator (/dev/kvm) + adb/appium |
| `check-openclaw-pod` / `check-openclaw-full-pod` / `check-openclaw-desktop-pod` | pod | `image: openclaw*` | minimal / maximal / streamed-desktop headless gateway |
| `check-openclaw-pod` / `check-openclaw-pod` / `check-charly-fedora-pod` | pod | `image: openclaw*` | minimal / maximal / streamed-desktop headless gateway |
| `check-cachyos-gpu-vm` / `check-selkies-labwc-nvidia-vm` / `check-selkies-kde-nvidia-vm` | vm | `from: cachyos-gpu-vm` | VFIO GPU-passthrough + nested selkies NVENC streaming (`requires_exclusive: [nvidia-gpu]` — serialized) |
| `check-arch-pacstrap-vm` / `check-arch-vm` / `check-cachyos-vm` / `check-debian-debootstrap-vm` / `check-ubuntu-debootstrap-vm` / `check-fedora-vm` | vm | `from: <distro>-vm` | the distro bootstrap-VM beds (pacstrap / debootstrap) |
| `check-cross-pod-cdp` / `check-cross-vm-http` / `check-cross-local-http` / `check-cross-local-driver` | pod/vm/local | — | cross-deployment probing (pod→pod, host→pod/VM) |
Expand Down Expand Up @@ -257,7 +257,7 @@ construction.
`check-pod` ~110s idle but **842s measured under a concurrent roster** (one build →
deploy → check → fresh-update → teardown cycle covering all four mechanisms) ·
`check-local-vm` ~45s · `check-sidecar-pod` ~180–290s · `check-k3s-vm` ~5–7 min ·
`check-openclaw-full-pod` ~1414s · the heavy feature beds
`check-openclaw-pod` ~1414s · the heavy feature beds
(`check-sway-browser-vnc-pod` ~2477s ≈ 41 min incl. image build) longer.

**These are load-dependent, and the idle figures mislead.** A bed's own newest
Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/recipes/coder/arch-coder.md
Original file line number Diff line number Diff line change
Expand Up @@ -162,7 +162,7 @@ Conflicts with [`/charly-coder:fedora-coder`](/recipes/coder/fedora-coder/) / [`
- [`/charly-coder:debian-coder`](/recipes/coder/debian-coder/) — deb-family sibling on Debian 13.
- [`/charly-coder:ubuntu-coder`](/recipes/coder/ubuntu-coder/) — deb-family sibling on Ubuntu 24.04 (adopt mode).
- [`/charly-coder:charly-arch`](/recipes/coder/charly-arch/) — slimmer Arch alternative with just the charly toolchain (no AI CLIs or DevOps tooling).
- [`/charly-openclaw:openclaw-desktop`](/recipes/openclaw/openclaw-desktop/) — adds a browser-streamed Wayland desktop (plus the openclaw gateway, AI CLIs, and a CPU ollama) with the same rootless charly toolchain.
- `/charly-distros:charly-fedora` — adds a browser-streamed Wayland desktop (plus the openclaw gateway, AI CLIs, and a CPU ollama) with the same rootless charly toolchain.

## Related layers

Expand Down
6 changes: 3 additions & 3 deletions src/content/docs/recipes/coder/charly-arch.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ Resolved OCI security label:
| `devices` | `[/dev/fuse, /dev/net/tun]` (from [`/charly-distros:container-nesting`](/recipes/distros/container-nesting/)) |
| `privileged` | `false` |

See [`/charly-openclaw:openclaw-desktop`](/recipes/openclaw/openclaw-desktop/) for the sibling rootless-first
See `/charly-distros:charly-fedora` for the sibling rootless-first
box that proves this posture works under streaming-desktop +
nested-VM load, and [`/charly-distros:container-nesting`](/recipes/distros/container-nesting/) for the kernel
`mount_too_revealing()` RCA.
Expand All @@ -73,7 +73,7 @@ mappings to work with. (That leg also handles host-networked containers
via `HostConfig.NetworkMode` detection — `ContainerInspection.IsHostNetworked()` in
`sdk/kit/checkvars.go` — so the bridge isn't strictly required
— but it remains the portable default.) If host-port 2222 is already taken by
another running box (canonical conflict: [`/charly-openclaw:openclaw-desktop`](/recipes/openclaw/openclaw-desktop/)
another running box (canonical conflict: `/charly-distros:charly-fedora`
or any `selkies-desktop-*` variant), remap at config time:
`charly config charly-arch -p 2223:2222`.

Expand Down Expand Up @@ -199,7 +199,7 @@ packages and scripts per distro.
- [`/charly-distros:arch`](/recipes/distros/arch/) — parent base image
- [`/charly-distros:charly-fedora`](/recipes/distros/charly-fedora/) — Fedora counterpart, same candies, same rootless posture
- [`/charly-coder:fedora-coder`](/recipes/coder/fedora-coder/) — kitchen-sink dev sibling (adds coding CLIs + DevOps)
- [`/charly-openclaw:openclaw-desktop`](/recipes/openclaw/openclaw-desktop/) — streaming-desktop counterpart (charly toolchain + browser-accessible Wayland); shares the rootless-first posture
- `/charly-distros:charly-fedora` — streaming-desktop counterpart (charly toolchain + browser-accessible Wayland); shares the rootless-first posture
- [`/charly-distros:githubrunner`](/recipes/distros/githubrunner/) — self-hosted GitHub Actions runner; same uid=1000 posture

## Related Commands
Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/recipes/coder/charly-mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -124,7 +124,7 @@ Six deploy-scope tests ship with the candy:

All `mcp:` checks pass `mcp_name: charly` so they stay unambiguous on
boxes that also expose `jupyter` or `chrome-devtools` servers
(e.g. [`/charly-openclaw:openclaw-desktop`](/recipes/openclaw/openclaw-desktop/)).
(e.g. `/charly-distros:charly-fedora`).

## Host networking caveat

Expand Down
3 changes: 0 additions & 3 deletions src/content/docs/recipes/coder/codex.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,6 @@ my-box:
```

## Used In Boxes

- `openclaw-full` (via `openclaw-full` metalayer)

## Related Candies
- [`/charly-coder:nodejs`](/recipes/coder/nodejs/) — Required Node.js runtime parent dependency
- [`/charly-coder:claude-code`](/recipes/coder/claude-code/) — Sibling AI coding agent CLI bundled in same metalayers
Expand Down
8 changes: 4 additions & 4 deletions src/content/docs/recipes/coder/fedora-coder.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ description: "Kitchen-sink development box: coding + AI-coding CLIs + DevOps too

The everyday-development counterpart to [`/charly-distros:charly-fedora`](/recipes/distros/charly-fedora/): all the
coding + AI + DevOps tooling a developer needs in one box, no desktop,
no streaming. Distinct from `openclaw-desktop` (which adds the
no streaming. Distinct from `charly-fedora` (which adds the
browser-streamed Wayland desktop) — `fedora-coder` is headless and
meant to be accessed via `ssh -p 2222` or `charly shell`.

Expand Down Expand Up @@ -86,7 +86,7 @@ normal `-p host:container` remapping (e.g. running `arch-coder` alongside
No `uid:` / `gid:` / `user:` / `security:` override — inherits
`1000/1000/user` from `defaults` and the candy-level security from
[`/charly-distros:container-nesting`](/recipes/distros/container-nesting/). Rootless-first by design (shares this
posture with [`/charly-openclaw:openclaw-desktop`](/recipes/openclaw/openclaw-desktop/)).
posture with `/charly-distros:charly-fedora`).

## Resolved security posture (OCI label)

Expand Down Expand Up @@ -251,7 +251,7 @@ All four produce the same daily-dev surface (sshd on 2222, charly-mcp on 18765,

## Related Boxes

- [`/charly-openclaw:openclaw-desktop`](/recipes/openclaw/openclaw-desktop/) — sibling rootless-first power-user box; same security posture + container-nesting, but adds the streaming desktop. Prefer when you want browser-accessible GUI + dev tools.
- `/charly-distros:charly-fedora` — sibling rootless-first power-user box; same security posture + container-nesting, but adds the streaming desktop. Prefer when you want browser-accessible GUI + dev tools.
- [`/charly-distros:charly-fedora`](/recipes/distros/charly-fedora/) — minimal charly toolchain (no coding CLIs, no DevOps), also uid=1000 with sudo.
- [`/charly-coder:charly-arch`](/recipes/coder/charly-arch/) — Arch Linux counterpart of charly-fedora.
- [`/charly-distros:githubrunner`](/recipes/distros/githubrunner/) — self-hosted GitHub Actions runner; same uid=1000 posture.
Expand All @@ -273,7 +273,7 @@ All four produce the same daily-dev surface (sshd on 2222, charly-mcp on 18765,

- Building, deploying, or troubleshooting the `fedora-coder` box.
- Picking the right power-user base image for a coding/dev workload (this
vs. `charly-fedora` vs. `charly-arch` vs. `openclaw-desktop`).
vs. `charly-fedora` vs. `charly-arch` vs. `charly-fedora`).
- Understanding the rootless-first architectural pattern shared by the
four power-user boxes (kernel RCA belongs in
[`/charly-distros:container-nesting`](/recipes/distros/container-nesting/); the composition that proves it works
Expand Down
5 changes: 2 additions & 3 deletions src/content/docs/recipes/coder/gemini.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,12 +28,11 @@ my-box:

## Used In Boxes

- `openclaw-full` (via `openclaw-full` metalayer)

## Related Candies
- [`/charly-coder:nodejs`](/recipes/coder/nodejs/) — required runtime dependency
- [`/charly-coder:claude-code`](/recipes/coder/claude-code/) — sibling AI CLI in openclaw-full and hermes-full
- [`/charly-coder:codex`](/recipes/coder/codex/) — sibling AI CLI in openclaw-full and hermes-full
- [`/charly-coder:claude-code`](/recipes/coder/claude-code/) — sibling AI CLI in hermes-full
- [`/charly-coder:codex`](/recipes/coder/codex/) — sibling AI CLI in hermes-full

## Related Commands
- [`/charly-build:secrets`](/recipes/build/secrets/) — provision Gemini API credentials for the CLI
Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/recipes/coder/gh.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ my-box:
## Used In Boxes

- [`/charly-coder:charly-arch`](/recipes/coder/charly-arch/), [`/charly-distros:charly-fedora`](/recipes/distros/charly-fedora/), [`/charly-coder:fedora-coder`](/recipes/coder/fedora-coder/) — power-user boxes that compose gh explicitly
- [`/charly-openclaw:openclaw-desktop`](/recipes/openclaw/openclaw-desktop/) — streaming-desktop sibling
- `/charly-distros:charly-fedora` — streaming-desktop sibling
- Any box composing `hermes-full`

## Related Candies
Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/recipes/coder/kimi.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ my-dev:
## Used In Boxes

- No enabled boxes use this candy yet — composition into the AI-CLI metalayers
(`hermes-full`, `openclaw-full`) and the coder boxes is the named
(`hermes-full`, `openclaw`) and the coder boxes is the named
`@github`-pin follow-up once the candy carries a published tag (see
[`/charly-build:reconcile`](/recipes/build/reconcile/))

Expand Down
5 changes: 1 addition & 4 deletions src/content/docs/recipes/coder/oracle.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,12 +27,9 @@ my-box:
```

## Used In Boxes

- `openclaw-full` (via `openclaw-full` metalayer)

## Related Candies
- [`/charly-coder:nodejs`](/recipes/coder/nodejs/) -- runtime dependency
- [`/charly-openclaw:openclaw-full`](/recipes/openclaw/openclaw-full/) -- parent metalayer that bundles oracle
- `/charly-openclaw:openclaw-layer` -- parent metalayer that bundles oracle

## Related Commands
- [`/charly-automation:openclaw-deploy`](/recipes/automation/openclaw-deploy/) -- gateway/skill configuration
Expand Down
4 changes: 2 additions & 2 deletions src/content/docs/recipes/core/charly-config.md
Original file line number Diff line number Diff line change
Expand Up @@ -260,11 +260,11 @@ When a `-p HOST:CONTAINER` flag publishes onto a host port that another listener
Warning: port conflicts detected:
Port 13000 is in use
Fix: find and stop the process using port 13000
Or remap: charly start openclaw-desktop --port 13001:3000
Or remap: charly start charly-fedora --port 13001:3000
Wrote /home/user/.config/containers/systemd/charly-<image>-<instance>.container
```

The quadlet is still written with the conflicting port, so `charly start` will fail at bind time unless you either free the port, re-run `charly config` with a remap, or edit `charly.yml`. Detection uses a local `net.Listen` probe per published port at configure time. Handy for multi-instance deployments alongside a production fleet (e.g., running [`/charly-openclaw:openclaw-desktop`](/recipes/openclaw/openclaw-desktop/) as a test instance while [`/charly-selkies:selkies-labwc`](/recipes/selkies/selkies-labwc/) holds the canonical 3000/9222/9224/2222 range).
The quadlet is still written with the conflicting port, so `charly start` will fail at bind time unless you either free the port, re-run `charly config` with a remap, or edit `charly.yml`. Detection uses a local `net.Listen` probe per published port at configure time. Handy for multi-instance deployments alongside a production fleet (e.g., running `/charly-distros:charly-fedora` as a test instance while [`/charly-selkies:selkies-labwc`](/recipes/selkies/selkies-labwc/) holds the canonical 3000/9222/9224/2222 range).

## Deploy State

Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/recipes/distros/agent-forwarding.md
Original file line number Diff line number Diff line change
Expand Up @@ -124,7 +124,7 @@ Resolution chain: charly.yml per-box > global setting > default (true).

## Used In Boxes

charly-arch, arch-test, comfyui, charly-fedora, fedora-test, githubrunner, immich, immich-ml, jupyter, nvidia, ollama, openclaw, openclaw-full, python-ml, selkies-desktop, selkies-labwc-nvidia, sway-browser-vnc, unsloth-studio, valkey-test
charly-arch, arch-test, comfyui, charly-fedora, fedora-test, githubrunner, immich, immich-ml, jupyter, nvidia, ollama, openclaw, openclaw, python-ml, selkies-desktop, selkies-labwc-nvidia, sway-browser-vnc, unsloth-studio, valkey-test

## Related Candies

Expand Down
4 changes: 2 additions & 2 deletions src/content/docs/recipes/distros/charly-fedora.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ Resolved OCI security label:
| `devices` | `[/dev/fuse, /dev/net/tun]` (from [`/charly-distros:container-nesting`](/recipes/distros/container-nesting/)) |
| `privileged` | `false` |

See [`/charly-openclaw:openclaw-desktop`](/recipes/openclaw/openclaw-desktop/) (streaming-desktop sibling) and
See `/charly-distros:charly-fedora` (streaming-desktop sibling) and
[`/charly-coder:fedora-coder`](/recipes/coder/fedora-coder/) (kitchen-sink dev sibling) for other boxes
sharing this posture, and [`/charly-distros:container-nesting`](/recipes/distros/container-nesting/) for the
kernel `mount_too_revealing()` RCA.
Expand Down Expand Up @@ -168,7 +168,7 @@ and scripts per distro.
- [`/charly-distros:fedora`](/recipes/distros/fedora/) — parent base image
- [`/charly-coder:charly-arch`](/recipes/coder/charly-arch/) — Arch counterpart, same layers, same rootless posture
- [`/charly-coder:fedora-coder`](/recipes/coder/fedora-coder/) — kitchen-sink dev sibling (adds coding CLIs + DevOps)
- [`/charly-openclaw:openclaw-desktop`](/recipes/openclaw/openclaw-desktop/) — streaming-desktop counterpart (charly toolchain + browser-accessible Wayland); shares the rootless-first posture
- `/charly-distros:charly-fedora` — streaming-desktop counterpart (charly toolchain + browser-accessible Wayland); shares the rootless-first posture
- [`/charly-distros:githubrunner`](/recipes/distros/githubrunner/) — self-hosted GitHub Actions runner; same uid=1000 posture

## Related Commands
Expand Down
Loading
Loading