From 5b9680274a08ddda19e1d265fa6a718ae5dbf1ab Mon Sep 17 00:00:00 2001 From: Nick Yeoman Date: Sat, 27 Jun 2026 08:08:25 -0700 Subject: [PATCH] feat: add AGENTS.md and openclaw_dev stack --- AGENTS.md | 37 ++++++++++++++++++++++++++ openclaw_dev/README.md | 56 +++++++++++++++++++++++++++++++++++++++ openclaw_dev/compose.yaml | 46 ++++++++++++++++++++++++++++++++ openclaw_dev/sample.env | 8 ++++++ 4 files changed, 147 insertions(+) create mode 100644 AGENTS.md create mode 100644 openclaw_dev/README.md create mode 100644 openclaw_dev/compose.yaml create mode 100644 openclaw_dev/sample.env diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..99f7489 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,37 @@ +# AGENTS.md + +## Stack conventions + +- Every stack has exactly 3 files: `compose.yaml` (or `docker-compose.yml`), `sample.env`, `README.md` +- `_dev` = experimental, `_notes` = docs/minimal examples, no suffix = production-ready +- Always references an external `proxy` network (`docker network create proxy` once) +- Volumes use `${VOL_PATH:-/data}` as the base path +- Timezone defaults to `America/Vancouver` +- Restart policy, image tag, and port are configurable via env vars with sensible defaults +- `deploy.bash` at root emulates Dockhand CLI for local testing (uses `fzf`) +- New stacks: copy from `_docs/template-compose.md` and `_docs/template-readme.md` +- Compose section order: `image` → `restart` → `volumes` → `environment` → `ports` → `networks` → `depends_on` → `healthcheck` → `labels` → `command` → `user` + +## Test a single stack + +```sh +# From the stack directory: +docker compose --env-file sample.env up -d +``` + +Note: `deploy.bash` only looks for `compose.yaml`, not `docker-compose.yml`. + +## Environment loading + +`--env-file` supports multiple files, applied in order (last wins): +```sh +docker compose --env-file sample.env --env-file /data/test.env up -d +``` + +## No CI/CD, no dependency management + +This is a Docker Compose file collection, not a code project. No tests, no build tools, no lockfiles. + +## OpenCode + +The `opencode/` stack runs OpenCode with a local ollama backend. Config is at `opencode/config/config.json`. Requires `ollama/` stack to be running and `OPENCODE_SERVER_PASSWORD` to be set. diff --git a/openclaw_dev/README.md b/openclaw_dev/README.md new file mode 100644 index 0000000..d57ddce --- /dev/null +++ b/openclaw_dev/README.md @@ -0,0 +1,56 @@ +# OpenClaw + +## Overview + +OpenClaw is an open-source AI coding assistant gateway with multi-model +support, agent sandboxing, and extensible plugin system. + +## Project Details + +- **Project Repository:** [github.com/openclaw/openclaw](https://github.com/openclaw/openclaw) +- **Container Image:** [ghcr.io/openclaw/openclaw](https://github.com/openclaw/openclaw/pkgs/container/openclaw) +- **Documentation:** [docs.openclaw.ai](https://docs.openclaw.ai) +- **Reverse Proxy Port:** `18789` + +## Environment Variable Notes + +- `OPENCLAW_GATEWAY_TOKEN` — required shared secret for Control UI access. + Generate with `openssl rand -hex 32`. +- `OPENCLAW_GATEWAY_BIND` — `lan` (default, reachable from host) or `loopback`. +- `OPENCLAW_DISABLE_BONJOUR` — set to `1` (default) for Docker bridge; + `0` only on host/macvlan networks. +- `OTEL_EXPORTER_OTLP_ENDPOINT` — optional OpenTelemetry collector URL. + +## Volume Notes + +- `/home/node/.openclaw` — config, state, and installed plugins +- `/home/node/.openclaw/workspace` — agent workspace files +- `/home/node/.config/openclaw` — auth-profile secret encryption keys + +All three use `${VOL_PATH:-/data}/openclaw/` as the host base path. + +## Network Notes + +Requires proxy network + +## Additional Notes / Gotchas + +- This is a `_dev` stack — experimental, not yet production-ready. +- The container runs as `node` (uid 1000). Ensure host bind-mount + directories are owned by uid 1000 or set `user: "0:0"`. +- Host-side AI providers (Ollama, LM Studio) are reachable at + `http://host.docker.internal:`. +- CLI commands: `docker compose exec openclaw node dist/index.js ` +- Image includes built-in `HEALTHCHECK`; the compose file adds an explicit + `curl`-based check. + +## Dockhand Stack, Deploy from Git + +- Cookbooks Repository +- stackname: openclaw_dev +- Compose file path: openclaw_dev/compose.yaml +- Additional env file (optional): openclaw_dev/sample.env + +Then "Load" openclaw_dev/sample.env into the Environment variables in dockhand. + +Create the Stack diff --git a/openclaw_dev/compose.yaml b/openclaw_dev/compose.yaml new file mode 100644 index 0000000..7531c1e --- /dev/null +++ b/openclaw_dev/compose.yaml @@ -0,0 +1,46 @@ +# OpenClaw AI Coding Assistant Gateway + +services: + openclaw: + image: ${OPENCLAW_IMAGE:-ghcr.io/openclaw/openclaw:latest} + restart: ${OPENCLAW_RESTART:-unless-stopped} + + volumes: + - ${VOL_PATH:-/data}/openclaw/config:/home/node/.openclaw + - ${VOL_PATH:-/data}/openclaw/workspace:/home/node/.openclaw/workspace + - ${VOL_PATH:-/data}/openclaw/auth-secrets:/home/node/.config/openclaw + - /etc/localtime:/etc/localtime:ro + + environment: + - TZ=${TZ:-America/Vancouver} + - OPENCLAW_DISABLE_BONJOUR=${OPENCLAW_DISABLE_BONJOUR:-1} + - OPENCLAW_GATEWAY_BIND=${OPENCLAW_GATEWAY_BIND:-lan} + - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN} + - OTEL_EXPORTER_OTLP_ENDPOINT=${OTEL_EXPORTER_OTLP_ENDPOINT} + + ports: + - "${OPENCLAW_PORT:-18789}:18789" + + networks: + - proxy + - internal + + extra_hosts: + - "host.docker.internal:host-gateway" + + command: + [ + "node", + "dist/index.js", + "gateway", + "--bind", + "${OPENCLAW_GATEWAY_BIND:-lan}", + "--port", + "18789", + ] + +networks: + proxy: + external: true + internal: + driver: bridge diff --git a/openclaw_dev/sample.env b/openclaw_dev/sample.env new file mode 100644 index 0000000..ab99924 --- /dev/null +++ b/openclaw_dev/sample.env @@ -0,0 +1,8 @@ +OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:latest +OPENCLAW_RESTART=unless-stopped +VOL_PATH=/data +OPENCLAW_PORT=18789 +OPENCLAW_GATEWAY_BIND=lan +OPENCLAW_DISABLE_BONJOUR=1 +OPENCLAW_GATEWAY_TOKEN=change-me-to-a-random-secret +TZ=America/Vancouver