ShibaClaw

Latest release (2026-07-19):

• Hybrid RAG for Low-RAM Devices — The RAG Knowledge Base now supports Cloud Embedding providers (Gemini, OpenRouter, OpenAI) with zero local RAM usage and a lighter package installation footprint, making RAG fully accessible on memory-constrained hardware like the Raspberry Pi.
• Channel Config Dropdowns — group_policy fields in channel configuration now use dropdown selectors in the WebUI for a better UX.
• External Package Installation on Modern Linux (PEP 668) — auto-injects --break-system-packages on externally-managed-environment errors during pip operations.
• Sub-agent Session Key Propagation — added session_key to sub-agent metadata for proper context during parallel execution.
• RAG Soft Restart Import Error — fixed NameError for dynamic RAG imports during soft restarts when the Local RAG plugin is installed.
• Transient LLM Error Handling — added 'empty choices' to transient error markers for automatic retry on empty API responses.
• Channel Hot-Reload on Secret Updates — fixed channel hot-reload not triggering when secrets are updated.
• Proactive Learning Tool Choice — gracefully handles unsupported tool_choice parameter in proactive learning.
• Removed Base64 Tool Output Encoding — eliminated Base64 encoding logic for tool outputs to simplify the pipeline.
• Telegram AI / agent Bot API features — Guest Mode (answerGuestQuery), private-chat streaming via sendMessageDraft, bot-to-bot messages, Business / Chat Automation updates, and Managed Bot update tracking. See docs/TELEGRAM_AI_FEATURES.md.
• Telegram config flags — streaming, guestMode, allowBotMessages, businessEnabled, managedBotsEnabled.

See CHANGELOG.md for the full release history.

ShibaClaw is a self-hosted AI agent you run on your own machine or server: a Python engine with a built-in web UI, native SDK support for 28 model providers, and 11 chat-platform integrations (Discord, Telegram, Slack, WhatsApp, Matrix, and more). It's built around three priorities — simplicity, security, and privacy — with defenses like install-time CVE auditing, prompt-injection wrapping, and SSRF protection shipped in the core engine instead of bolted on as external glue.

[!NOTE] Release notes live in CHANGELOG.md.

Features

• Security-first core — encrypted credentials vault, install-time CVE audit, prompt-injection wrapping, SSRF/DNS-rebinding guard
• Three-tier memory — working, semantic (FAISS), and procedural memory with proactive learning and auto-compaction
• 28 providers, native SDKs — OpenAI, Anthropic, Gemini, DeepSeek, and more, no LiteLLM proxy layer
• Web and mobile — expose the WebUI on your LAN and use the same agent from your phone
• Windows desktop app — native launcher with system tray integration
• MCP-ready — connect any MCP server, tools are auto-registered

Quick Start

Requirements: Docker, or Python 3.12+ for the pip route. The Windows auto-installer needs neither — it ships a pre-built desktop app.

Auto-installer (recommended)

One command downloads the latest release, sets up shortcuts, and launches the UI.

[!TIP] Bring your own model: connect to local endpoints (Ollama, LM Studio) or use free API tiers via OpenRouter to start chatting at zero cost.

Windows (PowerShell):

iwr -useb https://github.com/RikyZ90/ShibaClaw/releases/latest/download/install.ps1 | iex

Linux / macOS:

curl -fsSL https://github.com/RikyZ90/ShibaClaw/releases/latest/download/install.sh | bash

[!NOTE] On Windows this downloads the pre-built desktop app from the latest GitHub release — no Python required, with Desktop/Start Menu shortcuts and clean uninstall via Apps & Features. On Linux/macOS the script installs via pip in an isolated virtual environment.

Docker

curl -fsSL https://raw.githubusercontent.com/RikyZ90/ShibaClaw/main/docker-compose.yml -o docker-compose.yml
docker compose up -d     # pulls from Docker Hub
docker exec -it shibaclaw-gateway shibaclaw print-token

Open http://localhost:3000, paste the token, and follow the onboarding wizard. Expose shibaclaw-web on your LAN (e.g. via reverse proxy) to reach it from your phone.

pip

pip install shibaclaw
shibaclaw web --with-gateway   # starts WebUI + agent engine on :3000

Open http://localhost:3000 and follow the onboarding wizard, or run shibaclaw onboard for the CLI version of the same setup.

Security

Defenses that are normally scattered across app glue or external proxies ship in the ShibaClaw core, on by default.

Every tool result is wrapped in a dynamically generated boundary with a randomized nonce (e.g. <tool_output_a1b2c3d4>), so an attacker can't prematurely close the tag or inject fake system instructions through tool output — the boundary is unpredictable per session.

[!TIP] This wrapping mechanism is also available standalone as Muzzle, a zero-dependency Python library you can drop into any agent framework (LangChain, LlamaIndex, CrewAI, AutoGen, or a custom loop).

Memory System

ShibaClaw uses a three-tier memory architecture:

1. Working memory (per session) — rolling context with automatic summarization and token-aware truncation
2. Semantic memory (cross-session) — FAISS + sentence-transformers vector store with automatic fact extraction and semantic search
3. Procedural memory (skills & automations) — learned workflows saved as reusable skills, plus cron-like schedules

Proactive learning extracts and stores useful facts automatically, auto-compaction keeps context from overflowing, and sessions are stored as append-only JSONL for fast, cache-friendly logging.

MCP & Integrations

ShibaClaw speaks the Model Context Protocol, so it can connect to any MCP-compliant server — Google Drive, Slack, GitHub, PostgreSQL, and more — without changing core code. Configure servers from the Settings panel.

For popular SaaS tools (Gmail, Google Drive, Slack, GitHub, Outlook...), ShibaClaw integrates with Klavis: one API key gets you one-click OAuth connections instead of manually registering an OAuth app with each provider. Connected apps are auto-registered as MCP servers in the active session.

Supported Providers

ShibaClaw uses native SDKs — no LiteLLM proxy — and resolves the provider from the selected model or a provider-prefixed model ID. All configured provider catalogs are merged into one searchable list in the WebUI.

API key

¹ Setting GEMINI_API_KEY is sufficient — the OpenAI-compatible endpoint is pre-configured.

Gateway / proxy — OpenRouter, AiHubMix, SiliconFlow, VolcEngine, BytePlus, auto-detected by key prefix or api_base.

Local — Ollama, LM Studio, llama.cpp, vLLM, or any OpenAI-compatible endpoint.

[!NOTE] In Docker, localhost points inside the container. To reach a local server on the host (LM Studio, Ollama), use http://host.docker.internal:PORT on Windows/macOS or http://172.17.0.1:PORT on native Linux.

OAuth

For OpenRouter, the callback reuses the current WebUI URL and port by default, so http://localhost:3000 is not a dedicated OAuth-only port. If you expose the WebUI behind a reverse proxy or need a different public callback origin, set SHIBACLAW_OPENROUTER_CALLBACK_BASE_URL=https://your-public-webui-host before starting the server.

💡 Pro Tip: Cost-Effective & Premium Models

ShibaClaw performs exceptionally well even without expensive API usage:

• Free/Open Models: We highly recommend using OpenRouter to access powerful free models like nvidia/nemotron-3-super-120b-a12b:free or gemma-4-31b-it:free.
• Unlimited Premium: If you use the GitHub Copilot OAuth integration, you gain access to premium models like raptor (oswe-vscode-prime) at zero additional cost, effectively giving you unlimited requests.

📊 How ShibaClaw Compares (Security-First)

[!NOTE] OpenRouter's OAuth callback reuses the current WebUI URL and port. Behind a reverse proxy, set SHIBACLAW_OPENROUTER_CALLBACK_BASE_URL before starting the server.

For zero-cost usage, OpenRouter's free tier (e.g. nvidia/nemotron-3-super-120b-a12b:free) and the GitHub Copilot OAuth integration (unlimited access to models like raptor) both work well without a paid API key.

Architecture

Docker Compose

Both share the ~/.shibaclaw/ volume (config, workspace, memory, automation jobs, media cache). shibaclaw web alone runs agent + WebUI + automations in a single process, no gateway container needed.

Stack — Uvicorn/Starlette (ASGI), native WebSocket, vanilla JS + Marked.js + Highlight.js frontend, JSONL append-only sessions.

Resource usage — ~120 MB idle / ~350 MB peak per component (gateway, WebUI). Docker Compose caps each container at 512 MB / 256 MB reservation; tool output streams with bounded buffers so long-running commands can't blow up memory.

CLI Reference

shibaclaw web               # Start WebUI (agent + automations in-process)
shibaclaw gateway           # Start gateway only (for Docker split)
shibaclaw onboard           # CLI-based first-time setup wizard
shibaclaw agent -m "Hello"  # One-shot message via terminal
shibaclaw agent             # Interactive REPL with history
shibaclaw status            # Provider, workspace, OAuth health check
shibaclaw print-token       # Show WebUI auth token
shibaclaw channels status   # List enabled channels
shibaclaw provider login <p># OAuth login (github-copilot, openai-codex)
shibaclaw desktop           # Launch Windows desktop app

Channels

Each channel is configured independently in WebUI Settings and supports hot-reload on config changes.

Plugin System

ShibaClaw discovers plugins via Python entry points:

• Channel plugins — implement BaseChannel, discoverable via shibaclaw.integrations
• TTS plugins — implement BaseTTS, discoverable via shibaclaw.tts

Built-in: shibaclaw-channel-whatsapp (WhatsApp Web) and shibaclaw-tts-supertonic (free, offline ONNX speech synthesis, 31 languages). Install or remove plugins from WebUI Settings > Plugins, with hot-reload and version pinning. See docs/PLUGINS_DEVELOPMENT_GUIDE.md to build your own.

Text-to-Speech

The built-in Supertonic engine runs offline on ONNX (no PyTorch dependency, CPU-only), supports 31 languages with F1/M1 voice profiles and adjustable speed, and plays back through an in-browser widget. Enable it in WebUI Settings > TTS.

Automation & Scheduling

Background tasks run on cron-like schedules or event triggers (messages, webhooks, system events), in isolated sessions that don't pollute chat history. Manage, monitor, and view logs from the Automations panel; jobs persist across restarts via JSONL storage.

Knowledge Base (RAG)

Local, privacy-first retrieval-augmented generation: organize documents into named collections (PDF, CSV, HTML, TXT, Markdown), upload via drag-and-drop, and search with a FAISS index over all-MiniLM-L6-v2 embeddings. The agent can call knowledge_search during conversation, or you can target a specific collection with @kb:name. It's an optional dependency — install with pip install shibaclaw[rag].

Troubleshooting