ShibaClaw

Self-hosted, security-first AI agent with a built-in web UI

Features · Quick Start · Security · Memory · Providers · Architecture · Channels · Troubleshooting

🌐 简体中文 · Español · Português (BR) · 日本語 · Deutsch · Français · Italiano

---

🚀 What's new — v1.0.5 (click to expand)

Version v1.0.5 (2026-10-16):

• Specialist profiles and library — Adds owner-only agent_send, a profile graph, and editable soul and people documents. Agent sessions cannot chain messages; private sessions cannot use agent_send.
• Safer agent runs — Adds tool-call preflight checks, observation masking, artifact-preserving compaction, circuit breakers, subagent context modes, resource guards, and a CI gate for evolution merges.
• Subscription login and model selection — Adds subscription OAuth flows and model pickers to the WebUI.
• Reliability fixes — Corrects privacy and concurrent context handling, tool-call protocol, Windows frontmatter, approval fingerprints, profile model allowlists, OAuth handling, and packaged frontend assets.
• Gemini endpoint validation — Requires an exact hostname match, blocking lookalike domains from being treated as Google's model catalog.

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

• Advanced Safety & Resilience (SRE) — StuckDetector, Cost Circuit Breakers, Context Overflow Guard, Agentic SRE, CheckpointManager, IdempotentSaga, SelfRepair, HardStepCap, SREMonitor, and LayeredDefense
• Security-first core — encrypted credentials vault, install-time CVE audit, prompt-injection wrapping, SSRF/DNS-rebinding guard
• Three-tier memory & WebUI Manager — working, semantic (FAISS), and procedural memory with interactive WebUI management, live editing, dream diary, and safe quarantine
• Human-in-the-loop interactive UX — structured in-turn prompts (ask_user), masked vault credentials, progress cards, and dynamic permission sandboxing
• 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):

irm 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.

Layer	What it does
Install-time audit	Audits pip and npm before execution — blocks critical/high CVEs
Prompt-injection wrap & pre-scan	Wraps every tool result in a randomized <tool_output_...> boundary; regex pre-scanning for jailbreaks
Shell hardening	20+ deny patterns, escape normalization, internal URL detection
Local-first engine	Native command emulator (ls, cat) bypasses subprocess overhead; offline tiktoken fallback
Network guard	SSRF filtering, redirect revalidation, DNS-rebinding-safe resolution
Workspace sandbox	File tools and file browser locked to the configured workspace
Access control	Bearer token auth, constant-time checks, channel allowlists, optional rate limiting
Distributed engine	UI (~128 MB) decoupled from agent brain (~256 MB+)

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

Provider	Env variable
OpenAI	OPENAI_API_KEY
Anthropic	ANTHROPIC_API_KEY
DeepSeek	DEEPSEEK_API_KEY
Google Gemini	GEMINI_API_KEY¹
Groq	GROQ_API_KEY
Moonshot	MOONSHOT_API_KEY
MiniMax	MINIMAX_API_KEY
Zhipu AI	ZAI_API_KEY
DashScope	DASHSCOPE_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

Provider	Flow	Setup
OpenRouter	PKCE browser flow, stores returned API key in provider config	WebUI Settings
GitHub Copilot	Device flow, auto token refresh	shibaclaw provider login github-copilot or WebUI Settings
OpenAI Codex	PKCE browser flow	shibaclaw provider login openai-codex or WebUI Settings
Google Gemini CLI	PKCE browser flow, requires SHIBACLAW_GEMINI_OAUTH_CLIENT_ID and SHIBACLAW_GEMINI_OAUTH_CLIENT_SECRET env vars. Note: Unofficial third-party integration, Google may apply account restrictions. Use a separate account if this is a concern.	WebUI Settings

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

Service	Role	Default port
shibaclaw-gateway	Core agent loop, message bus, channel integrations	19999 (HTTP) · 19998 (WS)
shibaclaw-web	WebUI (Starlette + WebSocket), automations service	3000

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

Channel	Type	Notes
WebUI	Built-in	Primary interface, full feature access
Discord	Bot	Rich embeds, slash commands, attachments
Telegram	Bot	Inline keyboards, media, reply markup
WhatsApp	Plugin	Via WhatsApp Web
Slack	Bot	Block kit, threads, app mentions
DingTalk	Bot	Enterprise messaging
Feishu/Lark	Bot	Rich cards, interactive elements
QQ	Bot	Group & private messages
WeCom	Bot	Workplace communication
Matrix	Bot	Decentralized, E2E encryption
MoChat	Bot	WeChat ecosystem

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].

Safety & Resilience (SRE)

ShibaClaw includes a suite of advanced, production-grade safety and resilience features to ensure reliable and cost-effective execution:

• StuckDetector: Monitors agent progress to detect repetitive actions, tool-call loops, or lack of progress, automatically triggering goal reassessment and recovery prompts.
• Cost Circuit Breakers: Prevents runaway API costs by enforcing strict budget limits per session and automatically halting execution when thresholds are exceeded.
• Context Overflow Guard: A three-threshold guardrail (Warning, Critical, Hard Limit) that manages context window limits with automatic summarization, token compression, and emergency checkpointing.
• Agentic SRE: Specialized Monitor, Recovery, and Audit agents that continuously track liveness, progress, and quality, ensuring autonomous self-healing, system stability, and continuous improvement of the core agent loop.
• CheckpointManager: Saves and restores agent state to allow seamless resumption of long-running tasks, preventing progress loss, ensuring state consistency, and enabling robust recovery of the execution context, state, memory, and progress tracking capabilities of the core agent loop system architecture design pattern implementation framework library module package bundle component element unit system architecture design pattern architecture design pattern architecture design pattern framework library module package bundle component pattern implementation.
• IdempotentSaga: Ensures safe, transactional execution of multi-step tasks with side effects, automatic rollback capabilities, and strict idempotency guarantees.
• Self-Repair: Automatically diagnoses and repairs internal control mechanisms upon failure to maintain operational continuity, system integrity, and self-healing capabilities.
• Hard Step Caps: Enforces strict limits on the number of execution steps to prevent infinite loops, runaway token consumption, and execution stalls.
• LayeredDefense: Integrates all safety and resilience mechanisms into a unified, multi-layered defense system to guarantee robust, fault-tolerant execution and system reliability.

Troubleshooting

Problem	Try
General status check	shibaclaw status
Container logs	docker logs shibaclaw-gateway / docker logs shibaclaw-web
WebUI won't connect	Check token with shibaclaw print-token, verify port binding
Provider errors	shibaclaw status shows API key and OAuth state
Login fails after upgrading from v0.9.5	Run shibaclaw reset-admin
Security policy	SECURITY.md

---

See CONTRIBUTING.md to contribute and CHANGELOG.md for release history.