- TypeScript 71%
- Python 17.6%
- JavaScript 6.2%
- Go 4.1%
- Shell 0.7%
- Other 0.4%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| cli | ||
| config | ||
| deploy | ||
| docs | ||
| src | ||
| test | ||
| voice | ||
| .dockerignore | ||
| .env.advanced.example | ||
| .env.example | ||
| .gitignore | ||
| .npmrc | ||
| compose.sqlite.yaml | ||
| compose.whatsapp.yaml | ||
| compose.yaml | ||
| Dockerfile | ||
| identity.json | ||
| package-lock.json | ||
| package.json | ||
| persona.md | ||
| README.md | ||
| tsconfig.json | ||
| update.sh | ||
Kamakura
A self-hosted AI cat for Telegram, with optional WhatsApp and Discord owner DMs.
Features
- Conversation history, facts and reminders.
- Images, voice notes and bounded video inspection with separately configured providers.
- Optional Discord DM voice with GPT Live or xAI Grok Voice 3.0, configured separately. See voice setup.
- Private Linux boxes and an optional paired computer-use CLI.
- Mongo storage by default, or SQLite without Mongo.
Prerequisites
Git and Docker Compose 2.24.4 or newer, a Telegram bot token, and independent main-model and embedding-provider credentials. Docker builds the runtime dependencies.
Use Docker Engine on Linux, OrbStack on macOS, or Docker Desktop with WSL2 on Windows. Follow the platform storage setup before starting; on WSL, keep the checkout in the Linux filesystem.
Quick start
git clone https://github.com/koboshcom/kamakura.git
cd kamakura
cp .env.example .env
# Add credentials and owner IDs; prepare storage using the setup guide.
docker compose --profile build build sandbox-image egress-image
docker compose config --quiet
docker compose up -d --build
Configuration
Channel access in .env: tokens for enabled channels and their owner IDs or allowlists.
Main model in .env: model, base URL and API key.
Embeddings in .env: independent model, base URL and API key.
Storage and timezone in .env: STORAGE and DEFAULT_TIMEZONE.
For optional tuning, copy the root .env.advanced.example to .env.advanced. Tuning has sensible defaults; optional features may require their own credentials. See CONFIGURATION.md for all settings and precedence.
Mongo is the default. For SQLite, set STORAGE=sqlite in .env, then run
docker compose -f compose.yaml -f compose.sqlite.yaml up -d --build
This runs without Mongo. SQLite starts empty; existing data is not migrated.
Updates
Server updates for standard Linux Compose installs use ./update.sh. Update the stopped CLI connector with kamakura-cli update. Auto-updates stay off.
Wait for the chosen commit's CI to publish its GHCR image and CLI release before updating; a pushed commit alone does not mean either artifact is available. See update and rollback details.
Documentation
- Setup, storage, boxes and security
- Configuration reference
- Discord owner DMs
- Images and media settings
- Computer-use CLI
Optional Bing and Mojeek search works with every LLM provider. See search setup.