feat: add AGENTS.md and openclaw_dev stack

2026-09-03 18:36:22 +00:00 · 2026-06-27 08:08:36 -07:00
parent 97c93abcd7
commit 5b9680274a
4 changed files with 147 additions and 0 deletions
@@ -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.
@@ -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:<port>`.
+-   CLI commands: `docker compose exec openclaw node dist/index.js <subcommand>`
+-   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
@@ -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
@@ -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