🐊 Crocbot — Personal AI Assistant

v0.1.113

Cold-blooded patience, chrome-laced synapses.

Crocbot is a personal AI assistant you run on your own VPS. It answers you on Telegram via a full grammY bot integration, with an always-on Gateway control plane managing sessions, agents, tools, and automation.

Fork of OpenClaw, stripped down to CLI + Telegram for lean, single-user deployment.

Repository · Docs · Getting Started · Docker

---

What is Crocbot?

Crocbot is a Telegram-first personal AI assistant that runs as a background service on your server. The Gateway is the always-on control plane — it manages your Telegram bot connection, agent sessions, cron jobs, webhooks, and tools. You interact with it via Telegram DMs/groups or the crocbot CLI.

---

Quick Start

Runtime: Node >= 22

npm install -g crocbot@latest
# or: pnpm add -g crocbot@latest

crocbot onboard --install-daemon

The onboarding wizard walks through API keys, Telegram bot setup, workspace configuration, and skills. It installs the Gateway as a systemd user service so it stays running.

# Start the gateway manually (if not using the daemon)
crocbot gateway --port 18789 --verbose

# Send a message from the CLI
crocbot agent --message "Ship checklist" --thinking high

Full beginner guide: Getting Started · Upgrading? Update guide + crocbot doctor

---

Install from Source

Prefer pnpm for source builds. Bun is optional for running TypeScript directly.

git clone https://github.com/moshehbenavraham/crocbot.git
cd crocbot

pnpm install
pnpm build

pnpm crocbot onboard --install-daemon

# Dev loop (auto-reload on TS changes)
pnpm gateway:watch

pnpm crocbot ... runs TypeScript directly via tsx. pnpm build produces dist/ for the packaged crocbot binary.

---

Docker

# Build the image (requires dist/ from pnpm build)
pnpm build
docker build -t crocbot:local .

# Start the gateway
docker compose up -d crocbot-gateway

# CLI access
docker compose run --rm crocbot-cli status

Environment variables (ANTHROPIC_API_KEY, TELEGRAM_BOT_TOKEN, etc.) are read from .env or exported. Volumes mount ~/.crocbot (config) and ~/croc (workspace).

See Dockerfile and docker-compose.yml. Full docs: Docker install

---

Architecture

              Telegram
             (grammY bot)
                  |
                  v
     +------------------------+
     |        Gateway         |
     |   (WebSocket + HTTP)   |
     |  ws://127.0.0.1:18789  |
     +------------+-----------+
                  |
     +------+-----+------+---------+
     |      |            |         |
     v      v            v         v
  Agents  Sessions     Cron    MCP Server
  (Pi RT) (Storage)   (Jobs)  (SSE + HTTP)
     |                              ^
     +---> Rate Limiter + KeyPool    |
     |         |                  External AI
     |    LLM Providers           Systems
     |   (Claude, GPT, Gemini)
     +---> MCP Client
          (stdio, SSE, HTTP)

The Gateway is the single control plane. Telegram messages flow in, get routed to agent sessions, and responses stream back. The CLI connects to the same Gateway over WebSocket. The MCP client connects to external tool servers (stdio/SSE/HTTP); MCP server mode exposes crocbot as infrastructure for other AI systems.

Full architecture: Architecture overview

---

Highlights

• Gateway control plane — single WebSocket + HTTP server for sessions, tools, events, presence, and config
• Telegram integration — full grammY bot with groups, DMs, media support, and inline model selection
• Agent runtime — Pi embedded runtime with tool streaming and block streaming (RPC mode)
• Browser automation — dedicated Chrome/Chromium via CDP with snapshots, actions, uploads, and profiles
• Cron scheduler + webhooks — scheduled jobs and external triggers
• Skills platform — 31 bundled skills (weather, GitHub, Spotify, PDF, image gen, transcription, and more)
• Plugin system — extensible runtime with SDK (crocbot/plugin-sdk)
• Multi-model support — Anthropic, OpenAI, Google Gemini, Bedrock, Ollama, OpenRouter, and more
• Media pipeline — image/audio/video processing with AI understanding and transcription
• MCP integration — native MCP client (stdio/SSE/HTTP) and server mode with SSRF-guarded transports
• Memory system — conversation memory with semantic search
• Rate limiting — per-provider RPM/TPM throttling, API key round-robin rotation, transient error retry with backoff
• Security layer — SSRF protection, path traversal validation, exec allowlisting, secrets masking, DM pairing

---

Models

Crocbot supports multiple LLM providers with auth profile rotation and failover:

Provider	Examples
Anthropic	Claude Opus, Sonnet, Haiku
OpenAI	GPT-4o, o3, Codex
Google Gemini	Gemini 2.5 Pro/Flash
AWS Bedrock	Claude via Bedrock
Ollama	Local models
OpenRouter	Multi-provider gateway
+ more	GitHub Copilot, Moonshot, Qwen, Venice, …

Recommended: Anthropic Pro/Max subscription + Opus for long-context strength and prompt-injection resistance.

Docs: Models · Model failover · Onboarding

---

Configuration

Minimal ~/.crocbot/crocbot.json:

{
  agent: {
    model: "anthropic/claude-opus-4-5"
  }
}

Key environment variables:

Variable	Purpose
CROCBOT_STATE_DIR	Runtime state directory (config, credentials, logs, memory)
CROCBOT_CONFIG_PATH	Path to main config file
CROCBOT_WORKSPACE	Agent working directory (prompts, skills, hooks)
ANTHROPIC_API_KEY	Anthropic API key
TELEGRAM_BOT_TOKEN	Telegram bot token

Full reference: Configuration

---

Telegram Setup

Set your bot token via environment or config:

{
  channels: {
    telegram: {
      botToken: "123456:ABCDEF"
    }
  }
}

Or set TELEGRAM_BOT_TOKEN in your environment (env takes precedence).

DM security

Default: pairing mode — unknown senders receive a pairing code. Approve with:

crocbot pairing approve telegram <code>

Chat commands

Command	Description
/status	Session status (model, tokens, cost)
/new / /reset	Reset the session
/compact	Compact session context (summary)
/think <level>	Set thinking level (off/minimal/low/medium/high/xhigh)
/verbose on|off	Toggle verbose output
/usage off|tokens|full	Per-response usage footer
/tts on|off	Control text-to-speech
/skill <name>	Run a skill by name
/whoami	Show your sender ID
/help	Show available commands

Groups: configure channels.telegram.groups for allowlisting, mention gating, and activation modes.

Docs: Telegram · Groups

---

Security Defaults

Crocbot connects to real messaging surfaces — treat inbound DMs as untrusted input.

• DM pairing (dmPolicy="pairing") — unknown senders must pair before the bot responds
• Exec allowlisting — shell commands are gated by an allowlist
• SSRF protection — private IP/hostname blocking on all outbound fetches
• Secrets masking — credentials never appear in logs, LLM context, or Telegram output
• Sandbox mode — run non-main sessions (groups) in per-session Docker sandboxes
• crocbot doctor — audit tool that surfaces risky or misconfigured policies

Details: Security · Sandboxing

---

Agent Workspace & Skills

• Workspace root: ~/croc (configurable via agents.defaults.workspace)
• Prompt files: AGENTS.md, SOUL.md, USER.md, MEMORY.md, TOOLS.md
• Skills: ~/croc/skills/<skill>/SKILL.md
• 31 bundled skills including weather, GitHub, Spotify, Notion, Trello, Obsidian, PDF generation, image generation, transcription, browser automation, and more

Docs: Skills · Skills config

---

Tech Stack

Technology	Purpose
Node.js 22+	Runtime (ESM)
TypeScript (ES2023)	Strict mode, NodeNext modules
tsdown (rolldown)	Bundler (~5s builds)
pnpm	Package manager
grammY	Telegram SDK
@modelcontextprotocol/sdk	MCP client and server
Vitest	Testing
oxlint + oxfmt	Lint + format (Rust-based, fast)

---

Development

Command	Description
pnpm install	Install dependencies
pnpm build	Production build (~5s via tsdown)
pnpm gateway:watch	Dev loop with auto-reload
pnpm check	Type check + lint + format
pnpm lint	Lint (oxlint, type-aware)
pnpm lint:fix	Auto-fix lint issues
pnpm format	Check formatting (oxfmt)
pnpm format:fix	Auto-fix formatting
pnpm test	Run all tests (Vitest, parallel)
pnpm test:e2e	End-to-end tests
pnpm test:coverage	Coverage report
pnpm docs:dev	Local Mintlify docs server

Commit convention

Use conventional commits (feat:, fix:, docs:, refactor:, test:, chore:). The repo provides a scoped staging helper:

scripts/committer "feat: add cron retry logic" src/cron/retry.ts

Deploy

# Local
pnpm build && node dist/index.js gateway

# Docker
pnpm build && docker build -t crocbot:local . && docker compose up -d

Docs: Development reference

---

Documentation

• Getting started — onboarding flow
• Architecture — gateway + protocol model
• Configuration — full reference (all keys + examples)
• Telegram — bot setup, groups, media
• Security — DM policies, sandboxing, exec guards
• Models — provider setup, failover, rotation
• Skills — bundled, managed, and workspace skills
• Browser — CDP automation
• Cron & webhooks — scheduled jobs, triggers
• Docker — container deployment
• Troubleshooting — common failures
• Doctor — health audit tool
• Platform: Linux — VPS deployment guide

---

Contributing

See CONTRIBUTING.md for guidelines, branch conventions, and how to submit PRs.

AI-assisted PRs welcome.

---

License & Attribution

MIT License — Copyright (c) 2025 Peter Steinberger

Forked from OpenClaw (github.com/openclaw/openclaw). Crocbot is an independent fork stripped down for single-user Telegram deployment.