feat: add ZeroClaw AI agent runtime stack - #691
Conversation
📝 WalkthroughWalkthroughAdds a ZeroClaw stack with Devfile metadata, runtime components, gateway endpoint, persistent storage, CLI commands, registry metadata, ownership assignment, and an ODoV3 validation skip. ChangesZeroClaw Stack Addition
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
michael-valdron
left a comment
michael-valdron
left a comment
There was a problem hiding this comment.
Hello @akurinnoy,
Thanks for contributing this new stack entry, will you or the @devfile/che-team be owning this stack?
You'll need to add the official proposed owner(s) of this stack under https://github.com/devfile/registry/blob/main/.github/CODEOWNERS, for example:
# ZeroClaw stacks
/stacks/zeroclaw/ @akurinnoy @devfile/che-team
akurinnoy
left a comment
akurinnoy
left a comment
There was a problem hiding this comment.
Thanks for the review! Added the CODEOWNERS entry - I'll be the owner for now:
/stacks/zeroclaw/ @akurinnoy
30d5147 to
78b09bd
Compare
michael-valdron
left a comment
michael-valdron
left a comment
There was a problem hiding this comment.
Hello @akurinnoy,
Tried testing spinning up this stack and I am encountering an "unknown error" (could not dig up the logs) that is happening with index-generator container. One clue I got is that its to do with the post-Start. I've included the error message down below as well as a screenshot of the DevSpace setup I'm using to test.
|
@michael-valdron Hi, thanks for testing! I tried to reproduce this on the similar cluster. One thing I noticed - the universal-developer-image:ubi9-latest is about 4GB and took about 4 minutes to pull on a cold node. This alone can exhaust DWO's 5-minute startup timeout. Once the image was cached, the workspace started fine with both containers healthy. Could you try creating the workspace again? If the image is already on the node from the first attempt, it should start much faster. If that doesn't help and you still see the index-generator failure, could you share a few details?
oc logs <workspace-pod> -c index-generator -n <namespace>
oc get events -n <namespace> --sort-by='.lastTimestamp' | grep <workspace-id> |
| # First boot: run `zeroclaw quickstart` in the terminal to create | ||
| # your first agent, then restart the workspace. | ||
|
|
||
| schemaVersion: 2.2.2 |
There was a problem hiding this comment.
| schemaVersion: 2.2.2 | |
| schemaVersion: 2.3.0 |
michael-valdron
left a comment
michael-valdron
left a comment
There was a problem hiding this comment.
@akurinnoy Re-tried this stack and lgtm, was able to launch the ZeroClaw stack from my devfile registry build/deployment into DevSpaces.
To get around the odo test failures you'll need to add the stack to the skip list under tests/check_odov3.sh, see example.
@akurinnoy To expand why this is needed is that this stack has no starter project which cannot be tested with odo, as we don't have test automation around DevSpace the reviewer has to verify this manually and stacks such as this shouldn't be included in odo testing. |
Add ZeroClaw - an open-source Rust-based AI agent runtime - as a devfile registry sample. Includes gateway/dashboard on port 42617 with per-workspace storage. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Oleksii Kurinnyi <okurinny@redhat.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Oleksii Kurinnyi <okurinny@redhat.com>
Co-authored-by: Ilya Buziuk <ibuziuk@redhat.com> Signed-off-by: Oleksii Kurinnyi <okurinny@redhat.com>
Signed-off-by: Oleksii Kurinnyi <okurinny@redhat.com>
d5d11d6 to
57edcf8
Compare
|
@michael-valdron thanks for re-testing! Added the odo v3 skip in |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@stacks/zeroclaw/1.0.0/devfile.yaml`:
- Around line 50-55: Make the public-bind override explicit in the devfile’s
daemon container environment: add ZEROCLAW_ALLOW_PUBLIC_BIND with value true
alongside HOME and ZEROCLAW_DATA_DIR, preserving the existing daemon arguments
and environment entries.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: a52c85a8-0cf8-439f-9c95-cbc278f3f3b0
📒 Files selected for processing (4)
.github/CODEOWNERSstacks/zeroclaw/1.0.0/devfile.yamlstacks/zeroclaw/stack.yamltests/check_odov3.sh
| args: ["daemon", "--host", "0.0.0.0"] | ||
| env: | ||
| - name: HOME | ||
| value: /home/user | ||
| - name: ZEROCLAW_DATA_DIR | ||
| value: /home/user/.zeroclaw/data |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
skopeo inspect --config docker://quay.io/che-incubator/zeroclaw-image:latest \
| jq -e '.config.Env[]? | select(. == "ZEROCLAW_ALLOW_PUBLIC_BIND=true")'Repository: devfile/registry
Length of output: 194
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
echo "== devfile references =="
cat -n stacks/zeroclaw/1.0.0/devfile.yaml | sed -n '1,120p'
echo
echo "== repository searches for ZeroClaw env / public bind / image =="
rg -n "ZEROCLAW_ALLOW_PUBLIC_BIND|allow_public_bind|zeroclaw|zhao|quay.io/che-incubator/zeroclaw-image|ZeroClaw" stacks README.md . -g '!vendor' -g '!node_modules' -g '!dist' -g '!build' 2>/dev/null | head -200Repository: devfile/registry
Length of output: 7805
🌐 Web query:
ZeroClaw gateway.allow_public_bind ZEROCLAW_ALLOW_PUBLIC_BIND docker configuration docs
💡 Result:
In ZeroClaw, gateway.allow_public_bind (or the environment variable ZEROCLAW_ALLOW_PUBLIC_BIND) is a security configuration setting that governs whether the gateway is permitted to bind to non-localhost addresses, such as 0.0.0.0 (all interfaces) [1][2]. By default, for security reasons, ZeroClaw restricts the gateway to the localhost (127.0.0.1) to prevent unintended exposure to external networks [1][2]. If you attempt to bind to 0.0.0.0 without this setting explicitly enabled, the gateway will refuse to start [2][3]. Docker Configuration In containerized environments like Docker, it is common to set ZEROCLAW_ALLOW_PUBLIC_BIND=true [4][5]. This is necessary because containers typically need to bind to all interfaces (often represented as [::] or 0.0.0.0) to allow traffic from the host or other containers to reach the service [4]. The security model for containerized deployments relies on Docker's internal network isolation rather than restricting the bind address to localhost [4]. Example Docker Compose configuration: services: zeroclaw: image: ghcr.io/zeroclaw-labs/zeroclaw:latest environment: - ZEROCLAW_ALLOW_PUBLIC_BIND=true - ZEROCLAW_GATEWAY_PORT=42617 ports: - "42617:42617" When setting this to true, be aware that the gateway becomes reachable outside of localhost (e.g., on your local area network) [1][6]. If you require public webhooks, the recommended approach is to use a tunnel (such as Tailscale, ngrok, or Cloudflare) rather than exposing the port directly via a public bind [1][2].
Citations:
- 1: https://github.com/zeroclaw-labs/zeroclaw/blob/master/docs/ops/network-deployment.md
- 2: https://mintlify.wiki/zeroclaw-labs/zeroclaw/guides/gateway-setup
- 3: https://github.com/zeroclaw-labs/zeroclaw/blob/663ff2e4/src/lib.rs
- 4: https://github.com/zeroclaw-labs/zeroclaw/wiki/13-Deployment
- 5: https://zeroclaw-labs-zeroclaw-41.mintlify.app/guides/deployment
- 6: fix(gateway): clarify public-bind warning wording zeroclaw-labs/zeroclaw#2488
🌐 Web query:
quay.io/che-incubator/zeroclaw-image Dockerfile ZEROCLAW_ALLOW_PUBLIC_BIND
💡 Result:
The ZEROCLAW_ALLOW_PUBLIC_BIND environment variable is a configuration setting used in ZeroClaw container deployments to control the gateway's network binding behavior [1][2]. The official ZeroClaw container image typically includes a default configuration file that already sets allow_public_bind = true and binds to [::] (all network interfaces), enabling the gateway to be reachable out of the box when the container's ports are published [3][1]. Key details regarding this variable include: - Purpose: In containerized environments, the ZeroClaw gateway is designed to refuse binding to public interfaces (like 0.0.0.0 or [::]) for security reasons unless explicitly authorized [4][2]. Setting ZEROCLAW_ALLOW_PUBLIC_BIND=true provides this authorization, allowing the gateway to accept connections from outside the container [5][1][6]. - Usage: You generally only need to set this environment variable if you are bind-mounting a custom configuration file that defaults to localhost binding [3]. - Configuration: When used, it is typically passed as an environment variable in a docker-compose.yml or similar deployment manifest [5][1][6]. - Security: It is an opt-in mechanism to move away from the default, safer localhost-only binding [4][2]. Ensure that any public exposure is managed appropriately through network security controls (e.g., firewall, VPC, or tunnels) [4]. For most standard deployments using the official image, the internal defaults are sufficient, and the environment variable can be omitted [3]. If you are experiencing connectivity issues despite publishing ports, or if you are using a custom configuration, ensuring this variable is set to true may be required [1][6].
Citations:
- 1: https://github.com/zeroclaw-labs/zeroclaw/wiki/13-Deployment
- 2: https://git.polymech.info/polymech/zeroclaw/commits/commit/1140a7887d53be95b769fd0637293be35b8c622f/src/config/schema.rs
- 3: https://github.com/zeroclaw-labs/zeroclaw/blob/efe1eb5b/docs/book/src/setup/container.md
- 4: https://mintlify.wiki/zeroclaw-labs/zeroclaw/guides/gateway-setup
- 5: https://github.com/zeroclaw-labs/zeroclaw/blob/bea884c9024a33c781a13afdf8ee0baddc92f5fa/docker-compose.yml
- 6: https://mintlify.wiki/zeroclaw-labs/zeroclaw/guides/deployment
🌐 Web query:
github.com/zeroclaw-labs/zeroclaw config.schema allow_public_bind ZEROCLAW_ALLOW_PUBLIC_BIND
💡 Result:
The configuration parameter allow_public_bind and its corresponding environment variable ZEROCLAW_ALLOW_PUBLIC_BIND in ZeroClaw are security controls designed to prevent accidental exposure of the ZeroClaw HTTP gateway [1][2]. By default, the ZeroClaw gateway binds to the loopback address (127.0.0.1) [3][4]. If you attempt to configure the gateway to bind to a non-loopback address (such as 0.0.0.0) without setting allow_public_bind to true, the application will refuse to start [3][4][5]. This mechanism is intended to block accidental public exposure [2][6]. Key details: - Configuration: In config.toml, this is set under the [gateway] section as allow_public_bind = true or false [3][4]. - Environment Variable: Alternatively, you can use the environment variable ZEROCLAW_ALLOW_PUBLIC_BIND, typically set to 1 or true (e.g., ZEROCLAW_ALLOW_PUBLIC_BIND=true) [7][3][8]. - Use Case: This setting is frequently required when running ZeroClaw inside a container (e.g., Docker or Kubernetes) to allow the service to be reachable within the container network or across a local network [7][8][9]. - Security Recommendation: Documentation strongly advises caution when enabling this, as it makes the gateway reachable outside of localhost. It is recommended to use it only on trusted local networks or in conjunction with a secure tunnel (e.g., Cloudflare, Tailscale, or ngrok) for external access [3][4]. The parameter is defined in the project's gateway configuration schema [1][2].
Citations:
- 1: https://git.polymech.info/polymech/zeroclaw/commits/commit/1140a7887d53be95b769fd0637293be35b8c622f/src/config/schema.rs
- 2: https://github.com/zeroclaw-labs/zeroclaw/blob/1f18bb55cb908823f80dc68daca981448cb4936d/docs/reference/api/config-reference.md
- 3: https://mintlify.wiki/zeroclaw-labs/zeroclaw/guides/gateway-setup
- 4: https://github.com/zeroclaw-labs/zeroclaw/blob/master/docs/ops/network-deployment.md
- 5: fix(gateway): clarify public-bind warning wording zeroclaw-labs/zeroclaw#2488
- 6: https://github.com/zeroclaw-labs/zeroclaw/blob/v0.6.8/docs/reference/api/config-reference.md
- 7: https://github.com/zeroclaw-labs/zeroclaw/blob/master/docs/book/src/setup/container.md
- 8: https://mintlify.wiki/zeroclaw-labs/zeroclaw/guides/deployment
- 9: https://git.polymech.info/polymech/zeroclaw/commit/89bff25c6d0c55af69b73852b7ddc730e11d1b15
🌐 Web query:
site:quay.io/che-incubator/zeroclaw-image Dockerfile ZEROCLAW_ALLOW_PUBLIC_BIND
💡 Result:
I couldn’t find a direct quay.io/che-incubator/zeroclaw-image Dockerfile match, but ZeroClaw’s docs say ZEROCLAW_ALLOW_PUBLIC_BIND=true is used for Docker/container networking because the gateway normally blocks public binds. The config reference also shows gateway.allow_public_bind defaults to false. (github.com)
If you want, I can keep digging specifically for the Quay image/Dockerfile history.
Citations:
Make the public-bind override explicit in the devfile.
The command binds ZeroClaw to 0.0.0.0, but ZeroClaw’s default gateway.allow_public_bind is false, so container deployments are typically run with ZEROCLAW_ALLOW_PUBLIC_BIND=true. Since this devfile does not expose it and the wrapper image’s environment cannot be determined from the repository, set the env var here to avoid the daemon rejecting the bind and losing the public endpoint.
Suggested fix
env:
- name: HOME
value: /home/user
+ - name: ZEROCLAW_ALLOW_PUBLIC_BIND
+ value: "true"
- name: ZEROCLAW_DATA_DIR📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| args: ["daemon", "--host", "0.0.0.0"] | |
| env: | |
| - name: HOME | |
| value: /home/user | |
| - name: ZEROCLAW_DATA_DIR | |
| value: /home/user/.zeroclaw/data | |
| args: ["daemon", "--host", "0.0.0.0"] | |
| env: | |
| - name: HOME | |
| value: /home/user | |
| - name: ZEROCLAW_ALLOW_PUBLIC_BIND | |
| value: "true" | |
| - name: ZEROCLAW_DATA_DIR | |
| value: /home/user/.zeroclaw/data |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@stacks/zeroclaw/1.0.0/devfile.yaml` around lines 50 - 55, Make the
public-bind override explicit in the devfile’s daemon container environment: add
ZEROCLAW_ALLOW_PUBLIC_BIND with value true alongside HOME and ZEROCLAW_DATA_DIR,
preserving the existing daemon arguments and environment entries.
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: akurinnoy, ibuziuk, michael-valdron The full list of commands accepted by this bot can be found here. The pull request process is described here DetailsNeeds approval from an approver in each of these files:
Approvers can indicate their approval by writing |
3 participants
Description of Changes
Add ZeroClaw as a devfile registry sample - an open-source Rust-based AI agent runtime by ZeroClaw Labs.
The stack runs the ZeroClaw daemon in a sidecar container:
The official ZeroClaw image is distroless, so we use a wrapper image (
quay.io/che-incubator/zeroclaw-image) that adds a shell environment on UBI9-minimal. The wrapper is built from che-incubator/zeroclaw-image.The editor (VS Code, ttyd, etc.) is chosen separately in the dashboard and injected into the
toolscontainer.Related Issue(s)
N/A
Acceptance Criteria
Have you read the devfile registry contributing guide and followed its instructions?
Does this repository's tests pass with your changes?
Does any documentation need to be updated with your changes?
Have you tested the changes with existing tools, i.e. Odo, Che, Console? (See devfile registry contributing guide on how to test changes)
Tests Performed
bash tests/validate_devfile_schemas.sh)odo initpassed locally with odo v3.16.1zeroclaw quickstart,zeroclaw status, andzeroclaw doctorfrom the terminal/home/user/.zeroclaw)How To Test
zeroclaw quickstartto create your first agentNotes To Reviewer
bashand coreutils on UBI9-minimalargs: ["daemon", "--host", "0.0.0.0"]to bypass the wrapper's default entrypoint config step (already handled at image build time)cookiesAuthEnabled: truefor authentication through the Che gatewaystarterProjects- the sample is a standalone agent runtime, not a code projectSummary by CodeRabbit