@dotsetlabs/dotclaw 1.1.0

package/.env.example

@@ -0,0 +1,54 @@
+# DotClaw environment variables
+#
+# IMPORTANT: This file should be placed at ~/.dotclaw/.env
+# (or $DOTCLAW_HOME/.env if you've customized the home directory)
+#
+# Note: Only secrets belong in .env for the main app runtime.
+# Some variables below are for one-off scripts and must be set in your shell
+# (they are NOT read from .env unless the script explicitly loads dotenv).
+
+# --- Required (app runtime) ---
+# Telegram bot token from @BotFather
+TELEGRAM_BOT_TOKEN=123456789:replace-with-real-token
+
+# OpenRouter API key
+OPENROUTER_API_KEY=sk-or-replace-with-real-key
+
+# --- Optional (app runtime) ---
+# Brave Search API key (enables WebSearch tool in the agent)
+BRAVE_SEARCH_API_KEY=replace-with-brave-key
+
+# Override host timezone (defaults to system TZ)
+TZ=America/New_York
+
+# --- Optional: System (set in shell before starting) ---
+# Override DotClaw home directory (defaults to ~/.dotclaw)
+# DOTCLAW_HOME=~/.dotclaw
+
+# --- Optional: bootstrap/configure (set in shell when running scripts) ---
+# Non-interactive bootstrap/configure flags
+# DOTCLAW_BOOTSTRAP_NONINTERACTIVE=1
+# DOTCLAW_CONFIGURE_NONINTERACTIVE=1
+
+# Required for non-interactive bootstrap
+# DOTCLAW_BOOTSTRAP_CHAT_ID=123456789
+
+# Optional bootstrap defaults
+# DOTCLAW_BOOTSTRAP_GROUP_NAME=main
+# DOTCLAW_BOOTSTRAP_GROUP_FOLDER=main
+# DOTCLAW_BOOTSTRAP_BUILD=true
+# DOTCLAW_BOOTSTRAP_SELF_CHECK=true
+
+# --- Optional: autotune (advanced) ---
+# Autotune uses dotenv, so these can live in .env if you run `npm run autotune`.
+# AUTOTUNE_TRACE_DIR=~/.dotclaw/traces
+# AUTOTUNE_OUTPUT_DIR=~/.dotclaw/prompts
+# AUTOTUNE_CANARY_FRACTION=0.1
+# AUTOTUNE_BEHAVIOR_CONFIG_PATH=~/.dotclaw/config/behavior.json
+# AUTOTUNE_BEHAVIOR_REPORT_DIR=~/.dotclaw/config
+# AUTOTUNE_BEHAVIOR_ENABLED=1
+
+# --- Internal (do not set) ---
+# Used by container entrypoint logic
+# DOTCLAW_DAEMON=1
+# DOTCLAW_SELF_CHECK=1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gavriel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# DotClaw
+
+Personal OpenRouter-based assistant for Telegram. Each request runs inside an isolated Docker container with long-term memory, scheduling, and tool governance.
+
+## Features
+
+- Telegram bot interface with per-group isolation
+- Containerized agent runtime with strict mounts
+- Long-term memory with embeddings and semantic search
+- Scheduled tasks (cron and one-off)
+- Tool policies and daily budgets
+- Plugin tools and Autotune optimization
+- Prometheus-compatible metrics
+
+## Prerequisites
+
+- Node.js 20+
+- Docker (running)
+- Telegram bot token (from @BotFather)
+- OpenRouter API key
+
+## Quick Start
+
+```bash
+# Clone and install
+git clone <repo-url>
+cd dotclaw
+npm install
+
+# Interactive setup (prompts for API keys, registers your main chat)
+npm run bootstrap
+
+# Build and start
+npm run build
+npm start
+```
+
+The bootstrap will create configuration in `~/.dotclaw/` and optionally build the Docker image.
+
+## CLI Commands
+
+After installation, use the `dotclaw` CLI:
+
+```bash
+dotclaw setup        # Full setup (init + configure + build + install service)
+dotclaw configure    # Re-configure API keys and model
+dotclaw build        # Build the Docker container image
+dotclaw start        # Start the service
+dotclaw stop         # Stop the service
+dotclaw restart      # Restart the service
+dotclaw logs         # View logs (add --follow to tail)
+dotclaw status       # Show service status
+dotclaw doctor       # Run diagnostics
+dotclaw register     # Register a new Telegram chat
+```
+
+## Configuration
+
+All configuration and data is stored in `~/.dotclaw/`:
+
+```
+~/.dotclaw/
+  .env                    # Secrets (Telegram, OpenRouter keys)
+  config/
+    runtime.json          # Runtime overrides
+    model.json            # Model selection
+    behavior.json         # Agent behavior tuning
+    tool-policy.json      # Tool allow/deny rules
+    tool-budgets.json     # Daily tool limits
+  data/
+    registered_groups.json
+    store/                # SQLite databases
+  groups/
+    main/CLAUDE.md        # Main group memory
+    global/CLAUDE.md      # Global memory
+  logs/
+  groups/<group>/logs/    # Per-group container logs
+```
+
+Mount allowlist (for additional container mounts) lives at:
+
+```
+~/.config/dotclaw/mount-allowlist.json
+```
+
+## Documentation
+
+Full documentation lives in `docs/`. View it locally:
+
+```bash
+npm run docs:dev
+```
+
+Or see:
+- Getting started: `docs/getting-started/quickstart.md`
+- Configuration: `docs/configuration/index.md`
+- Operations: `docs/operations/index.md`
+
+## Development
+
+```bash
+npm run dev          # Run with hot reload
+npm run build        # Compile TypeScript
+npm run lint         # Run ESLint
+npm test             # Run tests
+./container/build.sh # Rebuild agent container
+```
+
+## License
+
+MIT

package/config-examples/groups/global/CLAUDE.md

@@ -0,0 +1,21 @@
+# Rain (Global)
+
+You are Rain, a personal assistant. This file provides global guidance shared across all groups.
+
+## Guidance
+
+- Be concise and action-oriented when possible.
+- Prefer tool use when it improves accuracy or saves time.
+- Ask clarifying questions if the request is underspecified.
+
+## Long Tasks
+
+If a request requires significant work, send a brief acknowledgement first using `mcp__dotclaw__send_message`.
+
+## Memory
+
+Use long-term memory tools for durable facts or preferences:
+- `mcp__dotclaw__memory_upsert`
+- `mcp__dotclaw__memory_search`
+
+Update this `CLAUDE.md` only for stable, global guidance.

package/config-examples/groups/main/CLAUDE.md

@@ -0,0 +1,47 @@
+# Rain (Main Group)
+
+You are Rain, a personal assistant. You help with tasks, answer questions, and can schedule reminders.
+
+## What You Can Do
+
+- Answer questions and have conversations
+- Search the web and fetch content from URLs
+- Read and write files in your workspace
+- Run bash commands in your sandbox
+- Schedule tasks to run later or on a recurring basis
+- Send messages back to the chat
+
+## Long Tasks
+
+If a request requires significant work (research, multiple steps, file operations), use `mcp__dotclaw__send_message` to acknowledge first:
+
+1. Send a brief message: what you understood and what you'll do
+2. Do the work
+3. Return the final answer
+
+## Main Group Privileges
+
+The main group can manage other groups and change models:
+
+- `mcp__dotclaw__list_groups`
+- `mcp__dotclaw__register_group`
+- `mcp__dotclaw__remove_group`
+- `mcp__dotclaw__set_model`
+
+Available groups are also written to `/workspace/ipc/available_groups.json`.
+
+## Workspace Layout (Container)
+
+- `/workspace/group` is your writable workspace
+- `/workspace/project` is the DotClaw package (read-only)
+- `/workspace/global` is the global group folder (read-only)
+- `/workspace/ipc` is for host IPC files
+- `/workspace/session` is for model sessions
+
+## Memory
+
+Use long-term memory tools for durable facts or preferences:
+- `mcp__dotclaw__memory_upsert`
+- `mcp__dotclaw__memory_search`
+
+You can also update this `CLAUDE.md` for high-level, stable guidance.

package/config-examples/mount-allowlist.json

@@ -0,0 +1,25 @@
+{
+  "allowedRoots": [
+    {
+      "path": "~/projects",
+      "allowReadWrite": true,
+      "description": "Development projects"
+    },
+    {
+      "path": "~/repos",
+      "allowReadWrite": true,
+      "description": "Git repositories"
+    },
+    {
+      "path": "~/Documents/work",
+      "allowReadWrite": false,
+      "description": "Work documents (read-only)"
+    }
+  ],
+  "blockedPatterns": [
+    "password",
+    "secret",
+    "token"
+  ],
+  "nonMainReadOnly": true
+}

package/config-examples/plugin-http.json

@@ -0,0 +1,18 @@
+{
+  "name": "github_search",
+  "description": "Search GitHub repositories",
+  "type": "http",
+  "method": "GET",
+  "url": "https://api.github.com/search/repositories",
+  "headers": {
+    "Authorization": "Bearer ${GITHUB_TOKEN}"
+  },
+  "query_params": {
+    "q": "{{query}}",
+    "per_page": "5"
+  },
+  "input": {
+    "query": "string"
+  },
+  "required": ["query"]
+}

package/config-examples/runtime.json

@@ -0,0 +1,30 @@
+{
+  "host": {
+    "logLevel": "info",
+    "container": {
+      "mode": "daemon"
+    },
+    "metrics": {
+      "port": 3001,
+      "enabled": true
+    },
+    "dashboard": {
+      "enabled": true
+    },
+    "memory": {
+      "embeddings": {
+        "enabled": true
+      }
+    }
+  },
+  "agent": {
+    "assistantName": "Rain",
+    "promptPacks": {
+      "enabled": true
+    },
+    "planner": {
+      "enabled": true,
+      "mode": "auto"
+    }
+  }
+}

package/config-examples/tool-budgets.json

@@ -0,0 +1,24 @@
+{
+  "default": {
+    "per_day": {
+      "WebSearch": 50,
+      "WebFetch": 50,
+      "Bash": 20,
+      "Python": 15
+    }
+  },
+  "groups": {
+    "main": {
+      "per_day": {
+        "Bash": 40
+      }
+    }
+  },
+  "users": {
+    "123456789": {
+      "per_day": {
+        "WebFetch": 10
+      }
+    }
+  }
+}

package/config-examples/tool-policy.json

@@ -0,0 +1,51 @@
+{
+  "default": {
+    "allow": [
+      "Read",
+      "Write",
+      "Edit",
+      "Glob",
+      "Grep",
+      "GitClone",
+      "NpmInstall",
+      "WebSearch",
+      "WebFetch",
+      "Bash",
+      "Python",
+      "mcp__dotclaw__send_message",
+      "mcp__dotclaw__schedule_task",
+      "mcp__dotclaw__list_tasks",
+      "mcp__dotclaw__pause_task",
+      "mcp__dotclaw__resume_task",
+      "mcp__dotclaw__cancel_task",
+      "mcp__dotclaw__update_task",
+      "mcp__dotclaw__register_group",
+      "mcp__dotclaw__remove_group",
+      "mcp__dotclaw__list_groups",
+      "mcp__dotclaw__set_model",
+      "mcp__dotclaw__memory_upsert",
+      "mcp__dotclaw__memory_forget",
+      "mcp__dotclaw__memory_list",
+      "mcp__dotclaw__memory_search",
+      "mcp__dotclaw__memory_stats"
+    ],
+    "deny": [],
+    "max_per_run": {
+      "Bash": 4,
+      "Python": 4,
+      "WebSearch": 5,
+      "WebFetch": 6
+    },
+    "default_max_per_run": 32
+  },
+  "groups": {
+    "main": {
+      "allow": ["Bash", "WebSearch", "WebFetch"]
+    }
+  },
+  "users": {
+    "123456789": {
+      "deny": ["Bash"]
+    }
+  }
+}

package/container/.dockerignore

@@ -0,0 +1,6 @@
+agent-runner/node_modules
+agent-runner/dist
+agent-runner/.tsbuildinfo
+agent-runner/*.tsbuildinfo
+**/*.log
+**/.DS_Store

package/container/Dockerfile

@@ -0,0 +1,74 @@
+# DotClaw Agent Container
+# Runs OpenRouter-based agent runtime in isolated Linux VM with browser automation
+
+FROM node:22-slim
+
+# Install system dependencies for Chromium and Python
+RUN apt-get update && apt-get install -y \
+    chromium \
+    fonts-liberation \
+    fonts-noto-color-emoji \
+    libgbm1 \
+    libnss3 \
+    libatk-bridge2.0-0 \
+    libgtk-3-0 \
+    libx11-xcb1 \
+    libxcomposite1 \
+    libxdamage1 \
+    libxrandr2 \
+    libasound2 \
+    libpangocairo-1.0-0 \
+    libcups2 \
+    libdrm2 \
+    libxshmfence1 \
+    curl \
+    git \
+    python3 \
+    python3-pip \
+    python3-venv \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install common Python packages
+RUN pip3 install --break-system-packages pandas numpy requests beautifulsoup4 matplotlib
+
+# Set Chromium path for agent-browser
+ENV AGENT_BROWSER_EXECUTABLE_PATH=/usr/bin/chromium
+ENV PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH=/usr/bin/chromium
+
+# Install agent-browser globally
+RUN npm install -g agent-browser
+
+# Create app directory
+WORKDIR /app
+
+# Copy package files first for better caching
+COPY agent-runner/package*.json ./
+
+# Install dependencies (include dev deps for TypeScript build)
+RUN npm ci
+
+# Copy source code (avoid host node_modules via .dockerignore)
+COPY agent-runner/tsconfig.json ./tsconfig.json
+COPY agent-runner/src ./src
+
+# Build TypeScript and trim dev deps
+RUN npm run build && npm prune --omit=dev
+
+# Create workspace directories
+RUN mkdir -p /workspace/group /workspace/global /workspace/extra /workspace/ipc/messages /workspace/ipc/tasks /workspace/ipc/requests /workspace/ipc/responses /workspace/ipc/agent_requests /workspace/ipc/agent_responses
+
+# Create entrypoint script
+# Sources env from mounted /workspace/env-dir/env if it exists
+RUN printf '#!/bin/bash\nset -e\n[ -f /workspace/env-dir/env ] && export $(cat /workspace/env-dir/env | xargs)\nif [ \"${DOTCLAW_DAEMON}\" = \"1\" ]; then\n  node /app/dist/daemon.js\nelse\n  cat > /tmp/input.json\n  node /app/dist/index.js < /tmp/input.json\nfi\n' > /app/entrypoint.sh && chmod +x /app/entrypoint.sh
+
+# Set ownership to node user (non-root) for writable directories
+RUN chown -R node:node /workspace
+
+# Switch to non-root user (required for --dangerously-skip-permissions)
+USER node
+
+# Set working directory to group workspace
+WORKDIR /workspace/group
+
+# Entry point reads JSON from stdin, outputs JSON to stdout
+ENTRYPOINT ["/app/entrypoint.sh"]

package/container/agent-runner/package-lock.json

@@ -0,0 +1,92 @@
+{
+  "name": "dotclaw-agent-runner",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "dotclaw-agent-runner",
+      "version": "1.0.0",
+      "dependencies": {
+        "@openrouter/sdk": "^0.3.0",
+        "cron-parser": "^5.0.0",
+        "zod": "^4.0.0"
+      },
+      "devDependencies": {
+        "@types/node": "^22.10.7",
+        "typescript": "^5.7.3"
+      }
+    },
+    "node_modules/@openrouter/sdk": {
+      "version": "0.3.16",
+      "resolved": "https://registry.npmjs.org/@openrouter/sdk/-/sdk-0.3.16.tgz",
+      "integrity": "sha512-WEBlrXdc5R8I7o2temkMV65tIRGkzg9ct4DMNZ/FHS/hiRscLRS5EpcuORnAgjzZAh9X2dSsBpgygM8T7KiNAw==",
+      "hasInstallScript": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "zod": "^3.25.0 || ^4.0.0"
+      }
+    },
+    "node_modules/@types/node": {
+      "version": "22.19.7",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-22.19.7.tgz",
+      "integrity": "sha512-MciR4AKGHWl7xwxkBa6xUGxQJ4VBOmPTF7sL+iGzuahOFaO0jHCsuEfS80pan1ef4gWId1oWOweIhrDEYLuaOw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~6.21.0"
+      }
+    },
+    "node_modules/cron-parser": {
+      "version": "5.5.0",
+      "resolved": "https://registry.npmjs.org/cron-parser/-/cron-parser-5.5.0.tgz",
+      "integrity": "sha512-oML4lKUXxizYswqmxuOCpgFS8BNUJpIu6k/2HVHyaL8Ynnf3wdf9tkns0yRdJLSIjkJ+b0DXHMZEHGpMwjnPww==",
+      "license": "MIT",
+      "dependencies": {
+        "luxon": "^3.7.1"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/luxon": {
+      "version": "3.7.2",
+      "resolved": "https://registry.npmjs.org/luxon/-/luxon-3.7.2.tgz",
+      "integrity": "sha512-vtEhXh/gNjI9Yg1u4jX/0YVPMvxzHuGgCm6tC5kZyb08yjGWGnqAjGJvcXbqQR2P3MyMEFnRbpcdFS6PBcLqew==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
+    "node_modules/undici-types": {
+      "version": "6.21.0",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",
+      "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/zod": {
+      "version": "4.3.6",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-4.3.6.tgz",
+      "integrity": "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/colinhacks"
+      }
+    }
+  }
+}

package/container/agent-runner/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "dotclaw-agent-runner",
+  "version": "1.1.0",
+  "type": "module",
+  "description": "Container-side agent runner for DotClaw",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@openrouter/sdk": "^0.3.0",
+    "cron-parser": "^5.0.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.7",
+    "typescript": "^5.7.3"
+  }
+}