🐚 ClamBot is a security-focused personal AI assistant that runs all LLM-generated code inside a WASM sandbox (QuickJS inside Wasmtime) — eliminating the arbitrary code execution risks of exec()/subprocess.run() patterns common in other agent frameworks.

✨ Inspired by OpenClaw and nanobot.

[!IMPORTANT]
ClamBot is tested primarily with OpenAI Codex on Linux and this is the recommended provider for the best out-of-the-box reliability.

🔒 Every other agent framework runs LLM-generated code directly on your machine. ClamBot isolates it:

1. 🤖 LLM generates a JavaScript "clam" (named, versioned, reusable script)
2. 📦 The clam runs inside amla-sandbox (WASM/QuickJS) with memory isolation
3. ✅ Tool calls yield back to Python for capability-checked, approval-gated dispatch
4. ♻️ Successful clams are persisted and reused for identical future requests — zero latency, zero cost

✨ Key Features

🔒 WASM Sandbox Execution — all generated code runs in QuickJS/Wasmtime with memory isolation and no ambient network access

🛡️ Interactive Approval Gate — SHA-256 fingerprinted tool approvals with always-grants, turn-scoped grants, and per-tool scope options

♻️ Clam Reuse — successful scripts are promoted and reused for identical requests without any LLM call

🔧 Self-Fix Loop — up to 3 automatic retries with LLM-guided fix instructions on runtime failures

🤖 Multi-Provider LLM — tested path with OpenAI Codex (OAuth, recommended) plus OpenRouter, Anthropic, OpenAI, Gemini, DeepSeek, Ollama, and custom endpoints

💬 Telegram Integration — typing indicators, phase status messages, MarkdownV2 rendering, inline approval keyboards, file uploads

🧠 Long-Term Memory — MEMORY.md (durable facts auto-injected into prompts) + HISTORY.md (searchable interaction summaries)

⏰ Cron Scheduling — persistent timezone-aware jobs with cron, every, and at schedule types

💓 Heartbeat Service — proactive agent wakeup with task-driven execution from HEARTBEAT.md

🔑 Host-Managed Secrets — atomic-write store with 0600 permissions; secrets never appear in tool args, logs, or traces

🌐 SSRF Protection — private IP blocking on all outbound HTTP tools

📝 Session Compaction — automatic LLM-summarized compaction to prevent context window overflow

✅ Out-of-the-Box User Features

After onboarding, users can immediately:

• 💬 Chat in CLI (single-turn and interactive REPL modes)
• 📱 Use Telegram with typing indicators, approvals, status updates, and file uploads
• 🌐 Fetch web pages and call HTTP APIs
• 🎙️ Transcribe YouTube/media audio and summarize/translate the transcript
• 📄 Extract text from PDF files (including uploaded files)
• ⏰ Schedule reminders and recurring jobs (cron, every, at)
• 🧠 Use long-term memory recall + searchable history
• 🔑 Add/store secrets and approve tool access interactively

🏗️ Architecture

┌────────────────────────────────────────────────────────────────┐
│  Inbound Sources                                               │
│  ┌───────────┐  ┌─────────────┐  ┌───────────┐  ┌──────────┐ │
│  │ 💬 Telegram│  │ ⏰ Cron     │  │ 💓 Heartbeat│ │ 🖥️ CLI   │ │
│  └─────┬─────┘  └──────┬──────┘  └─────┬─────┘  └────┬─────┘ │
└────────┼───────────────┼──────────────┼────────────┼──────────┘
         ▼               ▼              ▼            ▼
┌────────────────────────────────────────────────────────────────┐
│  🎛️ Gateway Orchestrator                                       │
│  /approve · /secret · /new command routing                     │
└────────────────────────┬───────────────────────────────────────┘
                         ▼
┌────────────────────────────────────────────────────────────────┐
│  🧠 Agent Pipeline                                             │
│                                                                │
│  1. 📂 Session load + auto-compaction                          │
│  2. 🔀 Clam Selector (pre-selection → LLM routing)             │
│  3. ⚡ Clam Generator (LLM → JavaScript)                       │
│  4. 📦 WASM Runtime (QuickJS sandbox + approval-gated tools)   │
│  5. 🔍 Post-Runtime Analyzer (ACCEPT / SELF_FIX / REJECT)      │
│  6. 🧠 Background memory extraction (fire-and-forget)          │
└────────────────────────┬───────────────────────────────────────┘
                         ▼
┌────────────────────────────────────────────────────────────────┐
│  📤 Outbound → Telegram / CLI                                  │
└────────────────────────────────────────────────────────────────┘

📦 Install

git clone https://github.com/clamguy/clambot.git
cd clambot

🚀 Quick Start

[!TIP]
Recommended: OpenAI Codex (OAuth, tested path) via uv run clambot provider login openai-codex.
API-key providers are also supported: OpenRouter · Anthropic · OpenAI

1. 🎬 Initialize — auto-detects configured providers (API keys and Codex OAuth) and sets up workspace:

# Recommended: OpenAI Codex (OAuth)
uv run clambot provider login openai-codex

# Initialize workspace + config
uv run clambot onboard

uv run clambot onboard scans your environment variables, probes local Ollama, and generates ~/.clambot/config.json with everything it finds. No manual editing needed.

2. ✅ Verify

uv run clambot status

3. 💬 Chat

uv run clambot agent

That's it! You have a working sandboxed AI assistant in under a minute. 🎉

[!NOTE]
If you need to tweak settings later, edit ~/.clambot/config.json — see ⚙️ Configuration below.

💬 Telegram

Connect ClamBot to Telegram for a full mobile experience with inline approval buttons, typing indicators, and phase status messages.

1. 🤖 Create a bot — Open Telegram, search @BotFather, send /newbot, follow prompts, copy the token.

2. 🔗 Connect — the interactive command handles everything:

uv run clambot channels connect telegram
# Enter bot token → press "Connect" in bot → user ID auto-added → done!

3. 🚀 Run the gateway

uv run clambot gateway

That's it — message your bot on Telegram and ClamBot responds! 🎉

If you prefer to configure manually, add the following to ~/.clambot/config.json:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["YOUR_USER_ID"]
    }
  }
}

allowFrom: Leave empty to allow all users, or add user IDs/usernames to restrict access.

🤖 Providers

ClamBot supports multiple LLM backends through a registry-driven provider layer. Use Codex OAuth or set provider API keys, then run uv run clambot onboard — provider/model selection is auto-detected.

# Example: set up with OpenAI Codex (recommended)
uv run clambot provider login openai-codex
uv run clambot onboard    # auto-detects provider + model
uv run clambot status     # verify provider is ready ✅
uv run clambot agent      # start chatting 💬

Codex uses OAuth instead of API keys. Requires a ChatGPT Plus or Pro account.

# 1. Login (opens browser)
uv run clambot provider login openai-codex

# 2. Chat — model auto-configured
uv run clambot agent -m "Hello!"

Connects directly to any OpenAI-compatible endpoint — LM Studio, llama.cpp, Together AI, Fireworks, Azure OpenAI, or any self-hosted server. Add to ~/.clambot/config.json:

{
  "providers": {
    "custom": {
      "apiKey": "your-api-key",
      "apiBase": "https://api.your-provider.com/v1"
    }
  },
  "agents": {
    "defaults": {
      "model": "your-model-name"
    }
  }
}

For local servers that don't require a key, set apiKey to any non-empty string (e.g. "no-key").

Start Ollama and let onboard auto-detect it:

# 1. Start Ollama
ollama serve

# 2. Onboard auto-probes Ollama and discovers available models
uv run clambot onboard

# 3. Chat
uv run clambot agent

⚙️ Configuration

Config file: ~/.clambot/config.json (auto-generated by uv run clambot onboard)

📖 See docs/configuration.md for the full schema reference.

🔒 Security

[!TIP]
For production deployments, set "restrictToWorkspace": true in your tools config to sandbox file access.

🛡️ Tool Approvals

Every tool call from generated code goes through an approval gate:

🔍 Tool call arrives
├─ ✅ Check always_grants → ALLOW immediately
├─ 🔄 Check turn-scoped grants → ALLOW if same resource
└─ 🙋 Interactive prompt → Allow Once / Allow Always (scoped) / Reject

Configure pre-approved patterns in ~/.clambot/config.json:

{
  "agents": {
    "approvals": {
      "enabled": true,
      "interactive": true,
      "alwaysGrants": [
        {"tool": "web_fetch", "scope": "host:api.coinbase.com"},
        {"tool": "fs", "scope": "workspace"}
      ]
    }
  }
}

🧰 Built-In Tools

All tools below are available out of the box and callable from generated JavaScript clams via await tool_name({...}).

🖥️ CLI Reference

Interactive mode exits: exit, quit, /exit, /quit, :q, or Ctrl+D.

📁 Project Structure

clambot/
├── agent/             # 🧠 Core agent logic (loop, selector, generator, runtime, approvals)
│   ├── loop.py        #    Agent pipeline orchestration
│   ├── selector.py    #    Two-stage clam routing (pre-selection + LLM)
│   ├── generator.py   #    LLM-based JavaScript generation
│   ├── runtime.py     #    WASM execution wrapper + timeout/cancellation
│   ├── approvals.py   #    Capability-gated approval gate
│   └── tools/         #    Built-in tool implementations
├── bus/               # 🚌 Async message routing (inbound + outbound queues)
├── channels/          # 💬 Chat channel integrations (Telegram)
├── cli/               # 🖥️ Typer CLI commands
├── config/            # ⚙️ Config schema (Pydantic) + loader
├── cron/              # ⏰ Persistent timezone-aware job scheduling
├── gateway/           # 🎛️ Gateway orchestrator (connects all subsystems)
├── heartbeat/         # 💓 Proactive scheduled agent wakeup
├── memory/            # 🧠 Long-term memory (MEMORY.md + HISTORY.md)
├── providers/         # 🤖 LLM provider layer (LiteLLM, Codex, custom)
├── session/           # 💬 Conversation session management (JSONL)
├── tools/             # 🧰 Built-in tool implementations
├── utils/             # 🔧 Shared utilities (tracked tasks, text processing)
└── workspace/         # 📂 Workspace bootstrap + onboarding

🔬 How It Works

🐚 The Clam Lifecycle

User request: "What is the price of BTC?"
│
├─ ♻️ Pre-selection: exact match against existing clams? → YES → reuse (zero LLM cost)
│                                                         → NO  ↓
├─ 🔀 Selector LLM: generate_new / select_existing / chat
│
├─ ⚡ Generator LLM → JavaScript clam:
│   async function run(args) {
│     const res = await http_request({
│       method: "GET",
│       url: "https://api.coinbase.com/v2/prices/BTC-USD/spot"
│     });
│     return JSON.parse(res.content).data;
│   }
│
├─ 📦 WASM Sandbox executes clam
│   └─ http_request → 🛡️ Approval Gate → Python host dispatch → result
│
├─ 🔍 Post-Runtime Analyzer: ACCEPT → promote to clams/ for future reuse
│                             SELF_FIX → retry with fix instructions (up to 3×)
│                             REJECT → return error
│
└─ 📤 Response delivered → 🧠 background memory extraction (fire-and-forget)

📦 WASM Sandbox Model

All LLM-generated code runs inside amla-sandbox:

• 🏗️ QuickJS JavaScript engine compiled to WebAssembly via Wasmtime
• 🔒 Memory isolation — sandbox cannot access host memory
• 🚫 No ambient network — all HTTP goes through approved tool calls
• ✅ Capability-gated tools — each tool call yields to Python for approval
• ⏱️ Timeout + cancellation — configurable limits with graceful shutdown

📚 Documentation

🤝 Contributing

PRs welcome! See CONTRIBUTING.md for dev setup, testing, and code conventions. 🤗

# Dev setup
uv venv && uv pip install -e ".[dev]"

# Run tests
uv run pytest tests/ -x -v

# Lint
ruff check . && ruff format --check .

📄 License

MIT — ClamBot Contributors 2026

_{🐚 ClamBot is for educational, research, and technical exchange purposes.}