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.2 (click to expand)
Latest release v1.0.2 (2026-09-29):
- Faster RAG Startup — RAG dependencies now load only when indexing or searching, reducing unnecessary work during gateway startup.
- OpenAI Codex OAuth Models — The available model list is fetched from the authenticated Codex backend, with a fallback catalog if the endpoint is unavailable.
- More Reliable File Handling — Uploads are streamed in chunks, authorized media files can be retrieved, and credential redaction handles more key-name variations.
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.
Features
- 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.
🪟 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
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.
Memory System
ShibaClaw uses a three-tier memory architecture:
- Working memory (per session) — rolling context with automatic summarization and token-aware truncation
- Semantic memory (cross-session) — FAISS + sentence-transformers vector store with automatic fact extraction and semantic search
- 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.
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:freeorgemma-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)
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 |
| Plugin | Via WhatsApp Web | |
| Slack | Bot | Block kit, threads, app mentions |
| DingTalk | Bot | Enterprise messaging |
| Feishu/Lark | Bot | Rich cards, interactive elements |
| 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 viashibaclaw.integrations - TTS plugins — implement
BaseTTS, discoverable viashibaclaw.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
| 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.
1 maintainer
Metadata
1 maintainer
Release files for shibaclaw 1.0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| shibaclaw-1.0.2.tar.gz | 21.6 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| shibaclaw-1.0.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 43.2 MB
Release files / shibaclaw-1.0.2.tar.gz
| Download URL | shibaclaw-1.0.2.tar.gz |
|---|---|
| Size | 21.6 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a1c08af1a1ac127e23e76f4384e20023eb8889999cb54f50ce6c61245590f4c9
|
|
BLAKE2b-256 checksum How to use checksums |
c7f580c56078da87a21ff777b5886a96c8ab386b2251e06e006893a8ea36bf99
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency logRelease files / shibaclaw-1.0.2-py3-none-any.whl
| Download URL | shibaclaw-1.0.2-py3-none-any.whl |
|---|---|
| Size | 21.7 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9d3438a1d608592b0ee37d31dc38dd9b71941780891e08b474b55986c80d560e
|
|
BLAKE2b-256 checksum How to use checksums |
cbf500b2dd5a1b851fd2d594af8617691373e6ae3baa3f5796c1123e18d4ebf0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency log
