https://github.com/marlburrow/kinbot
Self-hosted AI agents with persistent memory, real identity, and collaboration. One process, one SQLite file, zero cloud.
https://github.com/marlburrow/kinbot
agent-framework ai ai-agents artificial-intelligence automation bun chatbot docker llm mcp memory multi-agent ollama open-source react self-hosted selfhosted sqlite typescript vector-search
Last synced: 24 days ago
JSON representation
Self-hosted AI agents with persistent memory, real identity, and collaboration. One process, one SQLite file, zero cloud.
- Host: GitHub
- URL: https://github.com/marlburrow/kinbot
- Owner: MarlBurroW
- License: agpl-3.0
- Created: 2026-02-19T16:16:44.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-04T23:41:17.000Z (3 months ago)
- Last Synced: 2026-03-04T23:48:50.785Z (3 months ago)
- Topics: agent-framework, ai, ai-agents, artificial-intelligence, automation, bun, chatbot, docker, llm, mcp, memory, multi-agent, ollama, open-source, react, self-hosted, selfhosted, sqlite, typescript, vector-search
- Language: TypeScript
- Homepage: https://marlburrow.github.io/kinbot/
- Size: 25.6 MB
- Stars: 8
- Watchers: 1
- Forks: 1
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# KinBot
**AI agents that actually remember you.**
Self-hosted. Persistent memory. Real collaboration.
[](https://github.com/MarlBurroW/kinbot/actions/workflows/ci.yml)
[](https://github.com/MarlBurroW/kinbot/actions/workflows/e2e.yml)
[](https://github.com/MarlBurroW/kinbot/actions/workflows/codeql.yml)
[](https://github.com/MarlBurroW/kinbot/releases)
[](https://github.com/MarlBurroW/kinbot)
[](LICENSE)
[](https://github.com/MarlBurroW/kinbot/pkgs/container/kinbot)
[](https://github.com/MarlBurroW/kinbot/pulls)
[Website](https://marlburrow.github.io/kinbot/) · [Documentation](https://marlburrow.github.io/kinbot/docs/) · [Quick Start](#-quick-start) · [Features](#-features) · [Use Cases](#-what-people-build-with-kinbot) · [Architecture](#-architecture) · [E2E Report](https://marlburrow.github.io/kinbot/e2e-report/) · [Discussions](https://github.com/MarlBurroW/kinbot/discussions) · [Troubleshooting](TROUBLESHOOTING.md) · [Changelog](https://marlburrow.github.io/kinbot/changelog) · [Contributing](#contributing)
## Why KinBot?
Most AI tools treat every conversation as **disposable**. You explain yourself Monday, they forget by Tuesday.
KinBot is different. You create **Kins** — AI agents with:
| | |
|---|---|
| 🧠 **Persistent memory** | They remember every conversation. Forever. Vector search + full-text across months of interactions. |
| 🎭 **Real identity** | Name, role, personality, avatar. They know who they are and who you are. |
| 🤝 **Collaboration** | Kins talk to each other, delegate tasks, spawn workers. A team, not a chatbot. |
| ⚡ **Autonomy** | Cron jobs, webhooks, Telegram. They work while you sleep. |
| 🏠 **Self-hosted** | One process. One SQLite file. Your data never leaves your server. |
> *"Like having your own team of AI specialists that live on your server and never forget a thing."*
---
## ✨ Features
### 🧠 Intelligence
Persistent memory (vector + full-text) · Knowledge base / RAG · Session compacting · Sub-agents · Inter-Kin communication · Continuous sessions that never reset
### 🔧 Automation & Extensibility
Cron jobs · Webhooks · HTTP requests · 6 channels (Telegram, Discord, Slack, WhatsApp, Signal, Matrix) · MCP servers · Custom tools · Mini Apps · **Plugin system** · Contacts · Notifications · Human-in-the-loop prompts · 23 AI providers (incl. Ollama) · Multi-provider auto-detection
### 🔒 Security & Privacy
AES-256-GCM vault · Auth with roles · Invitation system · 100% self-hosted · Your data never leaves your server
### 🎨 Experience
8 color palettes · Dark/Light/System themes · English & French · @mentions with autocomplete · File uploads · Image generation · Real-time SSE streaming
Full feature list
#### Kins
- **Persistent identity** — each Kin has a name, description, character, expertise domain, model, and avatar
- **Continuous sessions** — one session per Kin, never resets
- **Shared Kins** — all users on the instance interact with the same Kins; messages are tagged with sender identity
#### Intelligence
- **Long-term memory** — dual-channel: automatic extraction pipeline on every LLM turn + explicit `remember()` tool; hybrid search (vector similarity + full-text); query intent detection with category-aware score boosting; token-budgeted memory block in prompt
- **Knowledge base / RAG** — upload documents and texts as reference material; hybrid search (vector + full-text) retrieves relevant chunks at query time
- **Session compacting** — token-aware compaction with multi-summary accumulation and telescopic merge; original messages are always preserved
- **Sub-Kins (tasks)** — Kins can delegate work to ephemeral sub-agents; `await` mode re-enters the parent queue with the result, `async` mode deposits it as informational
- **Inter-Kin communication** — request/reply pattern with correlation IDs; rate-limited; replies are always informational (no ping-pong)
#### Automation
- **Cron jobs** — in-process scheduler (croner); Kins can create their own crons (with user approval); searchable/filterable cron list; cron results appear in the main session
- **Webhooks** — inbound webhooks to trigger Kins from external systems; configurable per-Kin
- **Channels** — 6 platforms: Telegram, Discord, Slack, WhatsApp, Signal, Matrix
- **Notifications** — Kins can send push notifications to users via the `notify` tool
- **Human-in-the-loop** — Kins can prompt users for approval before sensitive actions (cron creation, MCP server management, etc.)
#### Security & Privacy
- **Vault** — AES-256-GCM encrypted secrets; never exposed in prompts or logs; message redaction prevents leaking into compacted summaries
- **Authentication** — Better Auth with HTTP-only cookie sessions; admin + member roles; invitation system
- **Self-hosted** — your data never leaves your server
#### Extensibility
- **MCP servers** — connect any Model Context Protocol server to extend Kins with external tools; Kins can manage their own MCP connections
- **Plugin system** — extend KinBot with community or custom plugins; plugins can register tools, hooks, AI providers, and channels; install from Git repos or npm packages; hot reload during development; community registry with a built-in marketplace UI for discovering and installing plugins; managed via the UI with per-plugin configuration, encrypted secret storage, and enable/disable toggles; health monitoring with circuit breaker auto-disable; dependency management between plugins; version compatibility checking
- **Custom tools** — Kins can create, register, and run their own scripts from their workspace
- **Mini Apps** — Kins can build and deploy interactive web apps (HTML/CSS/JS) that live in the sidebar; auto-injected design system + JavaScript SDK with theme sync, toasts, inter-app navigation (`openApp`), dialogs (`confirm`/`prompt`), window title & badge control, persistent key-value storage (`get`/`set`/`delete`/`list`/`clear`), starter templates, parent-child event communication, and an App Gallery to browse and clone community apps
- **Contacts** — manage contacts that Kins can reference and interact with
- **Multi-provider** — 23 providers: Anthropic, Anthropic OAuth, OpenAI, Gemini, Mistral, DeepSeek, Groq, Together AI, Fireworks AI, Ollama, OpenRouter, Cohere, xAI, Voyage AI, Jina AI, Nomic, Tavily, Serper, Perplexity, Replicate, Stability AI, FAL AI, Brave Search
#### Experience
- **8 color palettes** — Aurora, Ocean, Forest, Sunset, Monochrome, Sakura, Neon, Lavender
- **Dark / Light / System** theme modes
- **Internationalization** — English and French
- **File uploads** — share files with Kins; image generation supported
- **Real-time streaming** — SSE-based, multiplexed across all Kins on a single connection
- **@mentions** — mention Kins and users in messages with autocomplete and styled pills; mentioned Kins receive notifications
- **Responsive UI** — mobile-friendly settings, contextual info tips, suggestion chips in empty chat states
- **System info** — version, uptime, and stats visible in settings
#### Built-in Tools (120+)
Kins have access to a rich set of native tools out of the box, no configuration needed:
**Memory & Knowledge** — `recall`, `memorize`, `update_memory`, `forget`, `list_memories`, `review_memories`, `search_history`, `search_knowledge`, `list_knowledge_sources`
**Web & Browsing** — `web_search`, `browse_url`, `extract_links`, `screenshot_url`
**Contacts** — `get_contact`, `search_contacts`, `create_contact`, `update_contact`, `delete_contact`, `find_contact_by_identifier`, `set_contact_note`
**Vault & Secrets** — `get_secret`, `create_secret`, `update_secret`, `delete_secret`, `search_secrets`, `redact_message`, vault entries & attachments
**Multi-Agent** — `spawn_self`, `spawn_kin`, `send_message`, `reply`, `list_kins`, `report_to_parent`, `request_input`, task management, `create_kin`, `update_kin`, `delete_kin`, `get_kin_details`
**Automation** — `create_cron`, `update_cron`, `delete_cron`, `list_crons`, `trigger_cron`, `get_cron_journal`, `wake_me_in`, `wake_me_every`, `cancel_wakeup`, `list_wakeups`, webhooks (CRUD)
**Mini Apps** — create, update, delete, read/write files, snapshots, rollback, persistent key-value storage, browse & clone from the App Gallery, templates, docs, icon generation
**Channels** — `list_channels`, `list_channel_conversations`, `send_channel_message`
**Plugins** — `list_installed_plugins`, `browse_plugin_store`, `install_plugin`, `uninstall_plugin`, `enable_plugin`, `disable_plugin`, `configure_plugin`, `get_plugin_details`, `check_plugin_updates`, `update_plugin`
**Custom Tools** — `register_tool`, `run_custom_tool`, `list_custom_tools` (Kins write and run their own scripts)
**Filesystem** — `read_file`, `write_file`, `edit_file`, `list_directory` (read, create, edit, and browse files in the workspace)
**Files & Images** — `store_file`, `get_stored_file`, `list_stored_files`, `search_stored_files`, `update_stored_file`, `delete_stored_file`, `attach_file`, `generate_image`, `list_image_models`
**System** — `run_shell`, `execute_sql`, `get_platform_logs`, `get_system_info`, user management
**MCP** — `add_mcp_server`, `update_mcp_server`, `remove_mcp_server`, `list_mcp_servers`
**HTTP** — `http_request` (make HTTP requests to external APIs with full method/header/body control)
**Human-in-the-Loop** — `prompt_human` (ask user for approval before sensitive actions), `notify` (push notifications)
## 💡 What people build with KinBot
**DevOps copilot** — A Kin connected to GitHub webhooks triages new issues, reviews PRs, runs CI checks, and creates releases. It remembers your codebase conventions and past decisions. Cron jobs monitor infrastructure and alert you on Telegram.
**Home automation brain** — A Kin talks to Home Assistant via MCP, learns your routines over time, and adjusts lighting/heating based on context. Ask it "why was the heating on last night?" and it remembers.
**Personal knowledge base** — Upload docs, meeting notes, project specs. A Kin indexes everything with RAG and answers questions across months of accumulated context. Unlike ChatGPT, it never forgets previous conversations.
**Multi-agent team** — A dispatcher Kin receives requests and delegates to specialists (one for code, one for sysadmin, one for writing). They collaborate, share context through memories, and report back.
**Business monitoring** — Webhooks feed sales data, support tickets, or server metrics into a Kin. It builds mini-app dashboards, sends daily Slack summaries, and flags anomalies before you notice them.
**Family assistant** — Multiple users share the same instance. One Kin manages groceries via Telegram, another handles kids' schedules, another tracks household tasks. Each remembers everyone's preferences.
---
## 🚀 Quick Start
```bash
docker run -d --name kinbot -p 3000:3000 -v kinbot-data:/app/data ghcr.io/marlburrow/kinbot:latest
```
Open `http://localhost:3000` — done. The onboarding wizard handles the rest.
Other install methods (one-liner script, Docker Compose, manual)
### One-liner install (Linux / macOS)
```bash
curl -fsSL https://raw.githubusercontent.com/MarlBurroW/kinbot/main/install.sh | bash
```
This script will:
1. Install [Bun](https://bun.sh) if not already present
2. Clone the repository to `/opt/kinbot`
3. Install dependencies and build the frontend
4. Run database migrations
5. Create a system service (systemd on Linux, launchd on macOS)
6. Start KinBot on port **3000**
**Customizable via env vars:**
```bash
KINBOT_DIR=/home/me/kinbot \
KINBOT_DATA_DIR=/home/me/kinbot-data \
KINBOT_PORT=8080 \
bash <(curl -fsSL https://raw.githubusercontent.com/MarlBurroW/kinbot/main/install.sh)
```
### Docker Compose
```bash
git clone https://github.com/MarlBurroW/kinbot.git
cd kinbot/docker
ENCRYPTION_KEY=$(openssl rand -hex 32) docker compose up -d
```
See [`docker/docker-compose.yml`](docker/docker-compose.yml) for full options.
### Manual
```bash
git clone https://github.com/MarlBurroW/kinbot.git
cd kinbot
bun install
bun run build
bun run db:migrate
NODE_ENV=production bun run start
```
---
## Architecture
```
┌──────────────────────────────┐
│ Channels │
│ Telegram · Discord · Slack │
│ WhatsApp · Signal · Matrix │
└──────────────┬───────────────┘
│
┌───────────────────────────────────┼───────────────────────────┐
│ KinBot (single process) │
│ │ │
│ ┌──────────────────┐ ┌───────▼───────────────────────┐ │
│ │ React + Vite │ │ Hono REST API │ │
│ │ Tailwind 4 │◀────▶│ + SSE stream │ │
│ │ shadcn/ui │ └───────┬───────────────────────┘ │
│ └──────────────────┘ │ │
│ │ │
│ ┌───────────┬───────────┬───────────┬───────────┐ │
│ │ │ │ │ │ │
│ ┌─▼────────┐┌─▼────────┐┌─▼────────┐┌─▼────────┐┌─▼──────┐ │
│ │ Vercel ││ Queue ││ Croner ││ Mini ││Plugins │ │
│ │ AI SDK ││ (FIFO) ││(Cron ││ Apps ││ │ │
│ │ Kin ││ per Kin ││ jobs) ││ + Tools ││ tools │ │
│ │ Engine │└──────────┘└──────────┘└──────────┘│ hooks │ │
│ └────┬─────┘ │providers│ │
│ │ │channels│ │
│ │ └────────┘ │
│ ┌────▼────────────────────────────────────────────────────┐ │
│ │ SQLite (bun:sqlite + Drizzle ORM) │ │
│ │ + FTS5 (full-text search) │ │
│ │ + sqlite-vec (vector similarity) │ │
│ └─────────────────────────────────────────────────────────┘ │
└──────────┬───────────────────────────────────┬───────────────┘
│ │
AI Providers (23) Integrations
Anthropic · OpenAI · Gemini MCP servers
Mistral · DeepSeek · Groq Webhooks
Ollama · OpenRouter · xAI Custom tools
Cohere · Together · Fireworks Web browsing
+ embedding, image, search Plugins (community)
```
**Key design principles:**
- **Queue per Kin** — one message processed at a time per Kin; user messages have priority over automated ones
- **Global SSE** — one SSE connection per browser tab, multiplexed by `kinId`; no per-Kin polling
- **No message deletion** — compacting compresses older messages into dated summaries that merge telescopically; original messages always preserved
- **Secrets stay in the vault** — vault secrets are never exposed in prompts; redaction prevents leaking into summaries
---
## Tech Stack
| Layer | Technology |
|---|---|
| **Runtime** | [Bun](https://bun.sh) |
| **Backend** | [Hono](https://hono.dev), [Drizzle ORM](https://orm.drizzle.team), bun:sqlite, [sqlite-vec](https://github.com/asg017/sqlite-vec), [Vercel AI SDK](https://sdk.vercel.ai), [Better Auth](https://www.better-auth.com), [croner](https://github.com/Hexagon/croner) |
| **Frontend** | [React 19](https://react.dev), [Vite](https://vite.dev), [Tailwind CSS 4](https://tailwindcss.com), [shadcn/ui](https://ui.shadcn.com), [i18next](https://www.i18next.com) |
| **AI Providers** | Anthropic, OpenAI, Gemini, Mistral, DeepSeek, Groq, Together AI, Fireworks AI, Ollama, OpenRouter, Cohere, xAI, Voyage AI, Jina AI, Nomic, Tavily, Serper, Perplexity, Replicate, Stability AI, FAL AI, Brave Search |
| **Database** | SQLite (single file) + FTS5 + sqlite-vec |
---
## Configuration
Copy `.env.example` to `.env` and adjust as needed. All values have sensible defaults — you can start with an empty `.env`.
| Variable | Default | Description |
|---|---|---|
| `PORT` | `3333` | HTTP server port |
| `HOST` | `127.0.0.1` | Bind address (`0.0.0.0` to expose on all interfaces) |
| `KINBOT_DATA_DIR` | `./data` | Persistent data directory (DB, uploads, workspaces) |
| `ENCRYPTION_KEY` | *(auto-generated)* | 64-char hex key for AES-256-GCM vault encryption. Auto-generated and persisted to `data/.encryption-key` on first run. |
| `LOG_LEVEL` | `info` | `debug` \| `info` \| `warn` \| `error` |
| `PUBLIC_URL` | `http://localhost:3333` | Public-facing URL (used in webhooks, invitation links) |
See [`.env.example`](.env.example) for the complete list of all options (compacting thresholds, memory tuning, queue settings, cron limits, web browsing, etc.).
---
## Development
### Prerequisites
- [Bun](https://bun.sh) >= 1.0
- Git
### Setup
```bash
git clone https://github.com/MarlBurroW/kinbot.git
cd kinbot
bun install
bun run dev # Starts Vite dev server (port 5173) + Hono backend (port 3333)
```
The dev server proxies API requests from port 5173 to 3333 automatically.
### Commands
| Command | Description |
|---|---|
| `bun run dev` | Start dev servers (Vite + Hono with hot reload) |
| `bun run build` | Production build (Vite → `dist/client/`) |
| `bun run start` | Start production server |
| `bun run db:generate` | Generate a new Drizzle migration from schema changes |
| `bun run db:migrate` | Apply pending migrations to the SQLite database |
### Project structure
```
src/
server/ # Bun + Hono backend
routes/ # REST API routes (one file per resource)
services/ # Business logic
providers/ # AI provider implementations
tools/ # Native tools exposed to Kins
db/ # SQLite connection, Drizzle schema, migrations
auth/ # Better Auth config + middleware
sse/ # SSE manager
config.ts # Centralized configuration
client/ # React + Vite frontend
pages/ # Page components
components/ # UI components (shadcn/ui + custom)
hooks/ # Custom React hooks
locales/ # i18n translation files (en.json, fr.json)
styles/ # Design tokens + Tailwind config
shared/ # Types and constants shared by client and server
types.ts
constants.ts
data/ # Created at runtime — SQLite DB, uploads, workspaces
plugins/ # Community & custom plugins (each with manifest.json + main entry)
docker/ # Dockerfile + docker-compose.yml
site/ # GitHub Pages landing site
```
### Adding a new language
1. Copy `src/client/locales/en.json` to `src/client/locales/.json`
2. Translate all values (keys must remain identical)
3. Register the language in `src/client/lib/i18n.ts`
---
## ⚙️ Environment Variables
All settings have sensible defaults. Override only what you need.
Full configuration reference
#### Core
| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `3333` | HTTP server port |
| `HOST` | `127.0.0.1` | Bind address (`0.0.0.0` to expose externally) |
| `NODE_ENV` | `development` | Set to `production` for optimized builds |
| `PUBLIC_URL` | `http://localhost:{PORT}` | Public-facing URL (for OAuth callbacks, webhooks) |
| `KINBOT_DATA_DIR` | `./data` | Data directory (DB, uploads, workspaces) |
| `ENCRYPTION_KEY` | Auto-generated | AES-256 key for vault encryption. Auto-generated and persisted on first run. Must be preserved across restarts. |
| `LOG_LEVEL` | `info` | Log verbosity: `debug`, `info`, `warn`, `error` |
| `DB_PATH` | `{dataDir}/kinbot.db` | SQLite database file path |
#### Memory & Compacting
| Variable | Default | Description |
|----------|---------|-------------|
| `COMPACTING_THRESHOLD_PERCENT` | `75` | Context usage % before compaction triggers |
| `COMPACTING_KEEP_PERCENT` | `40` | % of context window preserved as raw messages |
| `COMPACTING_SUMMARY_BUDGET_PERCENT` | `20` | Max % of context for summaries before telescopic merge |
| `COMPACTING_MAX_SUMMARIES` | `10` | Max active summaries before telescopic merge |
| `COMPACTING_MAX_SUMMARIES_PER_KIN` | `50` | Total summary retention per Kin (active + archived) |
| `COMPACTING_MODEL` | Provider default | Override the model used for session compacting |
| `MEMORY_EXTRACTION_MODEL` | Provider default | Override the model used for memory extraction |
| `MEMORY_MAX_RELEVANT` | `10` | Max relevant memories injected into context |
| `MEMORY_SIMILARITY_THRESHOLD` | `0.7` | Minimum cosine similarity for memory retrieval |
| `MEMORY_EMBEDDING_MODEL` | `text-embedding-3-small` | Embedding model for memory vectors |
| `MEMORY_EMBEDDING_DIMENSION` | `1536` | Vector dimension for embeddings |
| `MEMORY_TOKEN_BUDGET` | `0` | Max tokens for memory block in prompt (`0` = unlimited) |
| `MEMORY_RERANK_MODEL` | Provider default | Cross-encoder rerank model (Cohere, Jina) for memory retrieval |
| `MEMORY_CONSOLIDATION_MODEL` | Provider default | Model used for memory consolidation |
| `MEMORY_CONSOLIDATION_SIMILARITY` | `0.85` | Cosine similarity threshold for merging duplicate memories |
| `MEMORY_CONSOLIDATION_MAX_GEN` | `5` | Max consolidation generations per run |
| `MEMORY_MULTI_QUERY_MODEL` | Provider default | Model for multi-query expansion during recall |
| `MEMORY_HYDE_MODEL` | Provider default | Model for HyDE (hypothetical document embedding) queries |
| `MEMORY_CONTEXTUAL_REWRITE_MODEL` | Provider default | Model for contextual memory rewriting |
| `MEMORY_CONTEXTUAL_REWRITE_THRESHOLD` | `80` | Token threshold to trigger contextual rewrite |
| `MEMORY_ADAPTIVE_K` | `true` | Enable adaptive K (dynamic result count based on score distribution) |
| `MEMORY_ADAPTIVE_K_MIN_SCORE_RATIO` | `0.3` | Minimum score ratio for adaptive K cutoff |
| `MEMORY_RRF_K` | `60` | Reciprocal Rank Fusion K parameter for hybrid search |
| `MEMORY_FTS_BOOST` | `0.5` | Full-text search score boost factor |
| `MEMORY_SUBJECT_BOOST` | `1.3` | Score boost for subject-matching memories |
| `MEMORY_CATEGORY_BOOST` | `1.25` | Score boost for category-matching memories |
| `MEMORY_TEMPORAL_DECAY_LAMBDA` | `0.01` | Temporal decay rate (higher = faster decay) |
| `MEMORY_TEMPORAL_DECAY_FLOOR` | `0.7` | Minimum score multiplier from temporal decay |
| `HISTORY_TOKEN_BUDGET` | `40000` | Max tokens for conversation history in context |
#### Tasks & Queues
| Variable | Default | Description |
|----------|---------|-------------|
| `QUEUE_POLL_INTERVAL` | `500` | Queue polling interval in ms |
| `TASKS_MAX_DEPTH` | `3` | Maximum sub-task nesting depth |
| `TASKS_MAX_REQUEST_INPUT` | `3` | Max concurrent task requests per input |
| `TASKS_MAX_CONCURRENT` | `10` | Max concurrent tasks globally |
| `TOOLS_MAX_STEPS` | `10` | Max tool call steps per LLM turn |
#### Cron & Automation
| Variable | Default | Description |
|----------|---------|-------------|
| `CRONS_MAX_ACTIVE` | `50` | Max active cron jobs |
| `CRONS_MAX_CONCURRENT_EXEC` | `5` | Max concurrent cron executions |
#### Inter-Kin Communication
| Variable | Default | Description |
|----------|---------|-------------|
| `INTER_KIN_MAX_CHAIN_DEPTH` | `5` | Max chain depth for Kin-to-Kin messages |
| `INTER_KIN_RATE_LIMIT` | `20` | Max inter-Kin messages per minute |
#### Channels & Webhooks
| Variable | Default | Description |
|----------|---------|-------------|
| `CHANNELS_MAX_PER_KIN` | `5` | Max channel connections per Kin |
| `WEBHOOKS_MAX_PER_KIN` | `20` | Max webhooks per Kin |
| `WEBHOOKS_MAX_PAYLOAD_BYTES` | `1048576` | Max webhook payload size (1 MB) |
| `WEBHOOKS_LOG_RETENTION_DAYS` | `30` | Webhook execution log retention period |
| `WEBHOOKS_MAX_LOGS_PER_WEBHOOK` | `500` | Max stored execution logs per webhook |
| `WEBHOOKS_RATE_LIMIT_PER_MINUTE` | `60` | Max webhook executions per minute |
#### File Storage & Uploads
| Variable | Default | Description |
|----------|---------|-------------|
| `UPLOAD_DIR` | `{dataDir}/uploads` | Upload directory |
| `UPLOAD_MAX_FILE_SIZE` | `50` | Max upload size in MB |
| `UPLOAD_CHANNEL_RETENTION_DAYS` | `30` | Channel file retention period in days |
| `UPLOAD_CHANNEL_CLEANUP_INTERVAL` | `60` | Channel file cleanup interval in minutes |
| `FILE_STORAGE_DIR` | `{dataDir}/storage` | Kin file storage directory |
| `FILE_STORAGE_MAX_SIZE` | `100` | Max file size in MB |
| `FILE_STORAGE_CLEANUP_INTERVAL` | `60` | Cleanup interval in minutes |
#### Vault
| Variable | Default | Description |
|----------|---------|-------------|
| `VAULT_ATTACHMENT_DIR` | `{dataDir}/vault` | Vault attachment directory |
| `VAULT_MAX_ATTACHMENT_SIZE` | `50` | Max attachment size in MB |
| `VAULT_MAX_ATTACHMENTS_PER_ENTRY` | `10` | Max attachments per vault entry |
#### Workspaces & Mini Apps
| Variable | Default | Description |
|----------|---------|-------------|
| `WORKSPACE_BASE_DIR` | `{dataDir}/workspaces` | Kin workspace base directory |
| `MINI_APPS_DIR` | `{dataDir}/mini-apps` | Mini apps storage directory |
| `MINI_APPS_MAX_PER_KIN` | `20` | Max mini apps per Kin |
| `MINI_APPS_MAX_FILE_SIZE` | `5` | Max single file size in MB |
| `MINI_APPS_MAX_TOTAL_SIZE` | `50` | Max total size per app in MB |
| `MINI_APPS_BACKEND_ENABLED` | `true` | Enable mini app backend execution |
#### Web Browsing
| Variable | Default | Description |
|----------|---------|-------------|
| `WEB_BROWSING_PAGE_TIMEOUT` | `30000` | Page load timeout in ms |
| `WEB_BROWSING_MAX_CONTENT_LENGTH` | `100000` | Max extracted content length |
| `WEB_BROWSING_MAX_CONCURRENT` | `5` | Max concurrent fetches |
| `WEB_BROWSING_USER_AGENT` | KinBot default | Custom User-Agent string |
| `WEB_BROWSING_BLOCKED_DOMAINS` | *(empty)* | Comma-separated blocked domains |
| `WEB_BROWSING_PROXY` | *(none)* | HTTP proxy for web requests |
| `WEB_BROWSING_HEADLESS_ENABLED` | `false` | Enable headless browser (Puppeteer) |
| `PUPPETEER_EXECUTABLE_PATH` | Auto-detected | Chrome/Chromium path for headless mode |
| `WEB_BROWSING_MAX_BROWSERS` | `2` | Max concurrent browser instances |
| `WEB_BROWSING_BROWSER_IDLE_TIMEOUT` | `60000` | Browser idle timeout in ms |
#### MCP & Human-in-the-Loop
| Variable | Default | Description |
|----------|---------|-------------|
| `MCP_REQUIRE_APPROVAL` | `true` | Require user approval for MCP server management |
| `HUMAN_PROMPTS_MAX_PENDING` | `5` | Max pending human-in-the-loop prompts per Kin |
#### Sessions & Invitations
| Variable | Default | Description |
|----------|---------|-------------|
| `QUICK_SESSION_EXPIRATION_HOURS` | `24` | Quick session expiration time |
| `QUICK_SESSION_MAX_PER_USER_KIN` | `1` | Max active quick sessions per user per Kin |
| `QUICK_SESSION_RETENTION_DAYS` | `7` | Quick session data retention |
| `QUICK_SESSION_CLEANUP_INTERVAL` | `60` | Cleanup interval in minutes |
| `INVITATION_DEFAULT_EXPIRY_DAYS` | `7` | Default invitation link expiry |
| `INVITATION_MAX_ACTIVE` | `50` | Max active invitations |
#### Notifications
| Variable | Default | Description |
|----------|---------|-------------|
| `NOTIFICATIONS_RETENTION_DAYS` | `30` | Notification retention period |
| `NOTIFICATIONS_MAX_PER_USER` | `500` | Max stored notifications per user |
| `NOTIFICATIONS_EXT_MAX_PER_USER` | `5` | Max external notification endpoints per user |
| `NOTIFICATIONS_EXT_RATE_LIMIT` | `5` | External notification rate limit per minute |
| `NOTIFICATIONS_EXT_MAX_ERRORS` | `5` | Max consecutive errors before disabling endpoint |
#### Wakeups
| Variable | Default | Description |
|----------|---------|-------------|
| `WAKEUPS_MAX_PENDING_PER_KIN` | `20` | Max pending wakeups per Kin |
#### Version Check
| Variable | Default | Description |
|----------|---------|-------------|
| `VERSION_CHECK_ENABLED` | `false` | Enable automatic version checking |
| `VERSION_CHECK_REPO` | `MarlBurroW/kinbot` | GitHub repo to check for new releases |
| `VERSION_CHECK_INTERVAL_HOURS` | `12` | Hours between version checks |
---
## 🔧 Troubleshooting
Common issues and solutions
#### Port already in use
```
Error: listen EADDRINUSE :::3000
```
Another process is using port 3000. Either stop it or change KinBot's port:
```bash
PORT=3001 bun src/server/index.ts
# or with Docker:
docker run -d -p 3001:3000 ghcr.io/marlburrow/kinbot:latest
```
#### Database migration errors after update
If you see migration errors after updating KinBot:
```bash
# Backup first
cp data/kinbot.db data/kinbot.db.bak
# Re-run migrations
bun run db:migrate
```
#### Docker container won't start
Check logs for details:
```bash
docker logs kinbot
```
Common causes:
- **Permission issues on volume:** Ensure the data directory is writable (`chmod 777 ./data` or match UID)
- **Missing encryption key:** If you previously set `ENCRYPTION_KEY`, you must provide it on every restart (vault data is encrypted with it)
#### Provider connection fails
- Verify your API key is correct and has sufficient credits
- For self-hosted providers (Ollama), ensure the base URL is reachable from the KinBot container (use `host.docker.internal` or the host's LAN IP, not `localhost`)
- Check provider status pages for outages
#### Memory search returns no results
Memory extraction runs asynchronously after each LLM turn. If you just started a conversation:
- Wait a few seconds for the extraction pipeline to complete
- Check that you have an embedding provider configured in Settings > Providers
#### Blank page / frontend not loading
```bash
# Rebuild the frontend
bun run build
# Then restart
bun src/server/index.ts
```
For Docker, pull the latest image which includes pre-built frontend assets.
#### Generate a diagnostic report
If you're stuck, generate a report to include in bug reports:
```bash
bash install.sh --doctor
```
---
## 💬 Community & Support
- **Issues** — [Report bugs or request features](https://github.com/MarlBurroW/kinbot/issues)
- **Discussions** — [Questions, ideas, and show & tell](https://github.com/MarlBurroW/kinbot/discussions)
- **Contributing** — [Read the guide](CONTRIBUTING.md) to get started
- **Security** — [Report vulnerabilities responsibly](SECURITY.md)
- **Changelog** — [See what's new](https://marlburrow.github.io/kinbot/changelog)
If KinBot is useful to you, consider [starring the repo](https://github.com/MarlBurroW/kinbot) — it helps others discover the project.
## Contributing
Contributions are welcome! See **[CONTRIBUTING.md](CONTRIBUTING.md)** for the full guide: setup, adding providers/channels, code style, and commit conventions.
Quick version:
1. Fork the repository
2. Create a feature branch: `git checkout -b feat/my-feature`
3. Follow existing code conventions:
- Files: `kebab-case.ts` / Components: `PascalCase.tsx`
- Shared types in `src/shared/types.ts`; shared constants in `src/shared/constants.ts`
- API errors: `{ "error": { "code": "ERROR_CODE", "message": "..." } }`
- Never hardcode user-facing text — always use `useTranslation()` and add keys to both `en.json` and `fr.json`
4. Open a Pull Request with a clear description
### Design system
The UI is built on a custom design system with 8 palettes and full dark/light mode support. Before building any new UI:
- Consult `src/client/pages/design-system/DesignSystemPage.tsx` (live showcase, source of truth)
- Use semantic CSS variables (`var(--color-*)`) or Tailwind tokens — never hardcode colors
- Reuse components from `src/client/components/ui/`
---
## License
KinBot is licensed under the [GNU Affero General Public License v3.0](LICENSE) (AGPL-3.0).
You are free to use, modify, and distribute KinBot. However, if you deploy a modified version as a network service, you must also make your source code available under the same license. This protects against cloud-washing while keeping the project fully open.
For commercial use cases where the AGPL obligations are not compatible with your business, a commercial license is available — open an issue to discuss.
---