{"id":47299789,"url":"https://github.com/MarlBurroW/kinbot","last_synced_at":"2026-03-31T04:00:40.355Z","repository":{"id":340440115,"uuid":"1161881152","full_name":"MarlBurroW/kinbot","owner":"MarlBurroW","description":"Self-hosted AI agents with persistent memory, real identity, and collaboration. One process, one SQLite file, zero cloud.","archived":false,"fork":false,"pushed_at":"2026-03-24T10:04:54.000Z","size":31225,"stargazers_count":25,"open_issues_count":11,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-24T19:03:06.727Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"https://marlburrow.github.io/kinbot/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MarlBurroW.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"MarlBurroW"}},"created_at":"2026-02-19T16:16:44.000Z","updated_at":"2026-03-24T10:04:58.000Z","dependencies_parsed_at":"2026-03-07T13:02:43.024Z","dependency_job_id":null,"html_url":"https://github.com/MarlBurroW/kinbot","commit_stats":null,"previous_names":["marlburrow/kinbot"],"tags_count":68,"template":false,"template_full_name":null,"purl":"pkg:github/MarlBurroW/kinbot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarlBurroW%2Fkinbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarlBurroW%2Fkinbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarlBurroW%2Fkinbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarlBurroW%2Fkinbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MarlBurroW","download_url":"https://codeload.github.com/MarlBurroW/kinbot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarlBurroW%2Fkinbot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31218650,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-31T03:44:21.648Z","status":"ssl_error","status_checked_at":"2026-03-31T03:43:51.577Z","response_time":111,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2026-03-17T00:00:30.698Z","updated_at":"2026-03-31T04:00:40.348Z","avatar_url":"https://github.com/MarlBurroW.png","language":"TypeScript","readme":"\u003cdiv align=\"center\"\u003e\n\n# KinBot\n\n**AI agents that actually remember you.**\n\nSelf-hosted. Persistent memory. Real collaboration.\n\n[![CI](https://github.com/MarlBurroW/kinbot/actions/workflows/ci.yml/badge.svg)](https://github.com/MarlBurroW/kinbot/actions/workflows/ci.yml)\n[![E2E Tests](https://github.com/MarlBurroW/kinbot/actions/workflows/e2e.yml/badge.svg)](https://github.com/MarlBurroW/kinbot/actions/workflows/e2e.yml)\n[![CodeQL](https://github.com/MarlBurroW/kinbot/actions/workflows/codeql.yml/badge.svg)](https://github.com/MarlBurroW/kinbot/actions/workflows/codeql.yml)\n[![GitHub Release](https://img.shields.io/github/v/release/MarlBurroW/kinbot?style=flat-square\u0026color=a855f7)](https://github.com/MarlBurroW/kinbot/releases)\n[![GitHub Stars](https://img.shields.io/github/stars/MarlBurroW/kinbot?style=flat-square\u0026color=ec4899)](https://github.com/MarlBurroW/kinbot)\n[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg?style=flat-square)](LICENSE)\n[![Docker](https://img.shields.io/badge/Docker-ready-2496ED?style=flat-square\u0026logo=docker\u0026logoColor=white)](https://github.com/MarlBurroW/kinbot/pkgs/container/kinbot)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://github.com/MarlBurroW/kinbot/pulls)\n\n[Website](https://marlburrow.github.io/kinbot/) · [Documentation](https://marlburrow.github.io/kinbot/docs/) · [Quick Start](#-quick-start) · [Features](#-features) · [Compare](#-how-does-kinbot-compare) · [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)\n\n\u003c/div\u003e\n\n## Why KinBot?\n\nMost AI tools treat every conversation as **disposable**. You explain yourself Monday, they forget by Tuesday.\n\nKinBot is different. You create **Kins** — AI agents with:\n\n| | |\n|---|---|\n| 🧠 **Persistent memory** | They remember every conversation. Forever. Vector search + full-text across months of interactions. |\n| 🎭 **Real identity** | Name, role, personality, avatar. They know who they are and who you are. |\n| 🤝 **Collaboration** | Kins talk to each other, delegate tasks, spawn workers. A team, not a chatbot. |\n| ⚡ **Autonomy** | Cron jobs, webhooks, Telegram. They work while you sleep. |\n| 🏠 **Self-hosted** | One process. One SQLite file. Your data never leaves your server. |\n\n\u003e *\"Like having your own team of AI specialists that live on your server and never forget a thing.\"*\n\n---\n\n\n## ✨ Features\n\n### 🧠 Intelligence\nPersistent memory (vector + full-text) · Knowledge base / RAG · Session compacting · Sub-agents · Inter-Kin communication · Continuous sessions that never reset\n\n### 🔧 Automation \u0026 Extensibility\nCron 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\n\n### 🔒 Security \u0026 Privacy\nAES-256-GCM vault · Auth with roles · Invitation system · 100% self-hosted · Your data never leaves your server\n\n### 🎨 Experience\n8 color palettes · Dark/Light/System themes · English \u0026 French · @mentions with autocomplete · File uploads · Image generation · Real-time SSE streaming\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eFull feature list\u003c/strong\u003e\u003c/summary\u003e\n\n#### Kins\n- **Persistent identity** — each Kin has a name, description, character, expertise domain, model, and avatar\n- **Continuous sessions** — one session per Kin, never resets\n- **Shared Kins** — all users on the instance interact with the same Kins; messages are tagged with sender identity\n\n#### Intelligence\n- **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\n- **Knowledge base / RAG** — upload documents and texts as reference material; hybrid search (vector + full-text) retrieves relevant chunks at query time\n- **Session compacting** — token-aware compaction with multi-summary accumulation and telescopic merge; original messages are always preserved\n- **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\n- **Inter-Kin communication** — request/reply pattern with correlation IDs; rate-limited; replies are always informational (no ping-pong)\n\n#### Automation\n- **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\n- **Webhooks** — inbound webhooks to trigger Kins from external systems; configurable per-Kin\n- **Channels** — 6 platforms: Telegram, Discord, Slack, WhatsApp, Signal, Matrix\n- **Notifications** — Kins can send push notifications to users via the `notify` tool\n- **Human-in-the-loop** — Kins can prompt users for approval before sensitive actions (cron creation, MCP server management, etc.)\n\n#### Security \u0026 Privacy\n- **Vault** — AES-256-GCM encrypted secrets; never exposed in prompts or logs; message redaction prevents leaking into compacted summaries\n- **Authentication** — Better Auth with HTTP-only cookie sessions; admin + member roles; invitation system\n- **Self-hosted** — your data never leaves your server\n\n#### Extensibility\n- **MCP servers** — connect any Model Context Protocol server to extend Kins with external tools; Kins can manage their own MCP connections\n- **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\n- **Custom tools** — Kins can create, register, and run their own scripts from their workspace\n- **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 \u0026 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\n- **Contacts** — manage contacts that Kins can reference and interact with\n- **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\n\n#### Experience\n- **8 color palettes** — Aurora, Ocean, Forest, Sunset, Monochrome, Sakura, Neon, Lavender\n- **Dark / Light / System** theme modes\n- **Internationalization** — English and French\n- **File uploads** — share files with Kins; image generation supported\n- **Real-time streaming** — SSE-based, multiplexed across all Kins on a single connection\n- **@mentions** — mention Kins and users in messages with autocomplete and styled pills; mentioned Kins receive notifications\n- **Responsive UI** — mobile-friendly settings, contextual info tips, suggestion chips in empty chat states\n- **System info** — version, uptime, and stats visible in settings\n\n#### Built-in Tools (120+)\n\nKins have access to a rich set of native tools out of the box, no configuration needed:\n\n**Memory \u0026 Knowledge** — `recall`, `memorize`, `update_memory`, `forget`, `list_memories`, `review_memories`, `search_history`, `search_knowledge`, `list_knowledge_sources`\n\n**Web \u0026 Browsing** — `web_search`, `browse_url`, `extract_links`, `screenshot_url`\n\n**Contacts** — `get_contact`, `search_contacts`, `create_contact`, `update_contact`, `delete_contact`, `find_contact_by_identifier`, `set_contact_note`\n\n**Vault \u0026 Secrets** — `get_secret`, `create_secret`, `update_secret`, `delete_secret`, `search_secrets`, `redact_message`, vault entries \u0026 attachments\n\n**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`\n\n**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)\n\n**Mini Apps** — create, update, delete, read/write files, snapshots, rollback, persistent key-value storage, browse \u0026 clone from the App Gallery, templates, docs, icon generation\n\n**Channels** — `list_channels`, `list_channel_conversations`, `send_channel_message`\n\n**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`\n\n**Custom Tools** — `register_tool`, `run_custom_tool`, `list_custom_tools` (Kins write and run their own scripts)\n\n**Filesystem** — `read_file`, `write_file`, `edit_file`, `list_directory` (read, create, edit, and browse files in the workspace)\n\n**Files \u0026 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`\n\n**System** — `run_shell`, `execute_sql`, `get_platform_logs`, `get_system_info`, user management\n\n**MCP** — `add_mcp_server`, `update_mcp_server`, `remove_mcp_server`, `list_mcp_servers`\n\n**HTTP** — `http_request` (make HTTP requests to external APIs with full method/header/body control)\n\n**Human-in-the-Loop** — `prompt_human` (ask user for approval before sensitive actions), `notify` (push notifications)\n\n\u003c/details\u003e\n\n## 🔍 How does KinBot compare?\n\n| Feature | KinBot | ChatGPT | Open WebUI | LobeChat | AnythingLLM | OpenClaw | CrewAI |\n|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|\n| Self-hosted / your data | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ |\n| Persistent agent identity | ✅ | ⚠️ | ❌ | ⚠️ | ⚠️ | ⚠️ | ❌ |\n| Long-term memory | ✅ | ⚠️ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ |\n| Session compacting | ✅ | ❌ | ❌ | ❌ | ❌ | ⚠️ | ❌ |\n| Multi-agent collaboration | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |\n| Sub-agent delegation | ✅ | ❌ | ❌ | ❌ | ❌ | ⚠️ | ✅ |\n| Cron jobs / autonomy | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |\n| Encrypted secrets vault | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |\n| MCP tool servers | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |\n| Multi-provider (23+) | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ⚠️ |\n| Webhooks | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |\n| Chat integrations (6 platforms) | ✅ | ❌ | ❌ | ❌ | ⚠️ | ✅ | ❌ |\n| Custom tools (agent-created) | ✅ | ❌ | ❌ | ❌ | ❌ | ⚠️ | ⚠️ |\n| Mini Apps (agent-built UIs) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |\n| Plugin system (hot-reload) | ✅ | ❌ | ⚠️ | ✅ | ⚠️ | ⚠️ | ❌ |\n| RAG / document embedding | ✅ | ⚠️ | ✅ | ⚠️ | ✅ | ❌ | ⚠️ |\n| Multi-user with roles | ✅ | ✅ | ✅ | ⚠️ | ✅ | ❌ | ❌ |\n| Web UI | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |\n| Zero-infra (no Postgres/Redis) | ✅ | ❌ | ❌ | ⚠️ | ❌ | ✅ | ✅ |\n| Free \u0026 open source | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ |\n\n✅ Full support · ⚠️ Partial · ❌ Not available · *Based on default capabilities as of March 2026*\n\n**vs ChatGPT:** Great for quick questions, but ephemeral sessions, cloud-only, no self-hosting.\n\n**vs OpenClaw:** Powerful single-agent personal assistant, CLI-first. KinBot is multi-agent, multi-user, web UI, with inter-agent collaboration.\n\n**vs CrewAI / AutoGPT:** Task orchestration frameworks where agents execute a workflow and disappear. No persistence, no memory between runs. KinBot agents live permanently, accumulate knowledge, and work autonomously on schedules. Contractors vs. a team.\n\n👉 [Full comparison with positioning details](https://marlburrow.github.io/kinbot/#comparison)\n\n---\n\n## 🚀 Quick Start\n\n```bash\ndocker run -d --name kinbot -p 3000:3000 -v kinbot-data:/app/data ghcr.io/marlburrow/kinbot:latest\n```\n\nOpen `http://localhost:3000` — done. The onboarding wizard handles the rest.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eOther install methods\u003c/strong\u003e (one-liner script, Docker Compose, manual)\u003c/summary\u003e\n\n### One-liner install (Linux / macOS)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/MarlBurroW/kinbot/main/install.sh | bash\n```\n\nThis script will:\n1. Install [Bun](https://bun.sh) if not already present\n2. Clone the repository to `/opt/kinbot`\n3. Install dependencies and build the frontend\n4. Run database migrations\n5. Create a system service (systemd on Linux, launchd on macOS)\n6. Start KinBot on port **3000**\n\n**Customizable via env vars:**\n```bash\nKINBOT_DIR=/home/me/kinbot \\\nKINBOT_DATA_DIR=/home/me/kinbot-data \\\nKINBOT_PORT=8080 \\\n  bash \u003c(curl -fsSL https://raw.githubusercontent.com/MarlBurroW/kinbot/main/install.sh)\n```\n\n### Docker Compose\n\n```bash\ngit clone https://github.com/MarlBurroW/kinbot.git\ncd kinbot/docker\nENCRYPTION_KEY=$(openssl rand -hex 32) docker compose up -d\n```\n\nSee [`docker/docker-compose.yml`](docker/docker-compose.yml) for full options.\n\n### Manual\n\n```bash\ngit clone https://github.com/MarlBurroW/kinbot.git\ncd kinbot\nbun install\nbun run build\nbun run db:migrate\nNODE_ENV=production bun run start\n```\n\n\u003c/details\u003e\n\n---\n\n## Architecture\n\n```\n                     ┌──────────────────────────────┐\n                     │          Channels             │\n                     │  Telegram · Discord · Slack   │\n                     │  WhatsApp · Signal · Matrix   │\n                     └──────────────┬───────────────┘\n                                    │\n┌───────────────────────────────────┼───────────────────────────┐\n│                   KinBot  (single process)                    │\n│                                    │                          │\n│  ┌──────────────────┐      ┌───────▼───────────────────────┐  │\n│  │  React + Vite    │      │        Hono REST API          │  │\n│  │  Tailwind 4      │◀────▶│        + SSE stream           │  │\n│  │  shadcn/ui       │      └───────┬───────────────────────┘  │\n│  └──────────────────┘              │                          │\n│                                    │                          │\n│    ┌───────────┬───────────┬───────────┬───────────┐          │\n│    │           │           │           │           │          │\n│  ┌─▼────────┐┌─▼────────┐┌─▼────────┐┌─▼────────┐┌─▼──────┐ │\n│  │ Vercel   ││ Queue    ││ Croner   ││ Mini     ││Plugins │ │\n│  │ AI SDK   ││ (FIFO)   ││(Cron     ││ Apps     ││        │ │\n│  │ Kin      ││ per Kin  ││ jobs)    ││ + Tools  ││ tools  │ │\n│  │ Engine   │└──────────┘└──────────┘└──────────┘│ hooks  │ │\n│  └────┬─────┘                                    │providers│ │\n│       │                                          │channels│ │\n│       │                                          └────────┘ │\n│  ┌────▼────────────────────────────────────────────────────┐ │\n│  │           SQLite  (bun:sqlite + Drizzle ORM)            │ │\n│  │           + FTS5 (full-text search)                     │ │\n│  │           + sqlite-vec (vector similarity)              │ │\n│  └─────────────────────────────────────────────────────────┘ │\n└──────────┬───────────────────────────────────┬───────────────┘\n           │                                   │\n   AI Providers (23)                   Integrations\n   Anthropic · OpenAI · Gemini          MCP servers\n   Mistral · DeepSeek · Groq            Webhooks\n   Ollama · OpenRouter · xAI            Custom tools\n   Cohere · Together · Fireworks        Web browsing\n   + embedding, image, search           Plugins (community)\n```\n\n**Key design principles:**\n- **Queue per Kin** — one message processed at a time per Kin; user messages have priority over automated ones\n- **Global SSE** — one SSE connection per browser tab, multiplexed by `kinId`; no per-Kin polling\n- **No message deletion** — compacting compresses older messages into dated summaries that merge telescopically; original messages always preserved\n- **Secrets stay in the vault** — vault secrets are never exposed in prompts; redaction prevents leaking into summaries\n\n---\n\n## Tech Stack\n\n| Layer | Technology |\n|---|---|\n| **Runtime** | [Bun](https://bun.sh) |\n| **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) |\n| **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) |\n| **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 |\n| **Database** | SQLite (single file) + FTS5 + sqlite-vec |\n\n---\n\n## Configuration\n\nCopy `.env.example` to `.env` and adjust as needed. All values have sensible defaults — you can start with an empty `.env`.\n\n| Variable | Default | Description |\n|---|---|---|\n| `PORT` | `3333` | HTTP server port |\n| `HOST` | `127.0.0.1` | Bind address (`0.0.0.0` to expose on all interfaces) |\n| `KINBOT_DATA_DIR` | `./data` | Persistent data directory (DB, uploads, workspaces) |\n| `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. |\n| `LOG_LEVEL` | `info` | `debug` \\| `info` \\| `warn` \\| `error` |\n| `PUBLIC_URL` | `http://localhost:3333` | Public-facing URL (used in webhooks, invitation links) |\n\nSee [`.env.example`](.env.example) for the complete list of all options (compacting thresholds, memory tuning, queue settings, cron limits, web browsing, etc.).\n\n---\n\n## Development\n\n### Prerequisites\n\n- [Bun](https://bun.sh) \u003e= 1.0\n- Git\n\n### Setup\n\n```bash\ngit clone https://github.com/MarlBurroW/kinbot.git\ncd kinbot\nbun install\nbun run dev    # Starts Vite dev server (port 5173) + Hono backend (port 3333)\n```\n\nThe dev server proxies API requests from port 5173 to 3333 automatically.\n\n### Commands\n\n| Command | Description |\n|---|---|\n| `bun run dev` | Start dev servers (Vite + Hono with hot reload) |\n| `bun run build` | Production build (Vite → `dist/client/`) |\n| `bun run start` | Start production server |\n| `bun run db:generate` | Generate a new Drizzle migration from schema changes |\n| `bun run db:migrate` | Apply pending migrations to the SQLite database |\n\n### Project structure\n\n```\nsrc/\n  server/           # Bun + Hono backend\n    routes/         # REST API routes (one file per resource)\n    services/       # Business logic\n    providers/      # AI provider implementations\n    tools/          # Native tools exposed to Kins\n    db/             # SQLite connection, Drizzle schema, migrations\n    auth/           # Better Auth config + middleware\n    sse/            # SSE manager\n    config.ts       # Centralized configuration\n  client/           # React + Vite frontend\n    pages/          # Page components\n    components/     # UI components (shadcn/ui + custom)\n    hooks/          # Custom React hooks\n    locales/        # i18n translation files (en.json, fr.json)\n    styles/         # Design tokens + Tailwind config\n  shared/           # Types and constants shared by client and server\n    types.ts\n    constants.ts\ndata/               # Created at runtime — SQLite DB, uploads, workspaces\nplugins/            # Community \u0026 custom plugins (each with manifest.json + main entry)\ndocker/             # Dockerfile + docker-compose.yml\nsite/               # GitHub Pages landing site\n```\n\n### Adding a new language\n\n1. Copy `src/client/locales/en.json` to `src/client/locales/\u003clang\u003e.json`\n2. Translate all values (keys must remain identical)\n3. Register the language in `src/client/lib/i18n.ts`\n\n---\n\n## ⚙️ Environment Variables\n\nAll settings have sensible defaults. Override only what you need.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eFull configuration reference\u003c/strong\u003e\u003c/summary\u003e\n\n#### Core\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `PORT` | `3333` | HTTP server port |\n| `HOST` | `127.0.0.1` | Bind address (`0.0.0.0` to expose externally) |\n| `NODE_ENV` | `development` | Set to `production` for optimized builds |\n| `PUBLIC_URL` | `http://localhost:{PORT}` | Public-facing URL (for OAuth callbacks, webhooks) |\n| `KINBOT_DATA_DIR` | `./data` | Data directory (DB, uploads, workspaces) |\n| `ENCRYPTION_KEY` | Auto-generated | AES-256 key for vault encryption. Auto-generated and persisted on first run. Must be preserved across restarts. |\n| `LOG_LEVEL` | `info` | Log verbosity: `debug`, `info`, `warn`, `error` |\n| `DB_PATH` | `{dataDir}/kinbot.db` | SQLite database file path |\n\n#### Memory \u0026 Compacting\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `COMPACTING_THRESHOLD_PERCENT` | `75` | Context usage % before compaction triggers |\n| `COMPACTING_KEEP_PERCENT` | `40` | % of context window preserved as raw messages |\n| `COMPACTING_SUMMARY_BUDGET_PERCENT` | `20` | Max % of context for summaries before telescopic merge |\n| `COMPACTING_MAX_SUMMARIES` | `10` | Max active summaries before telescopic merge |\n| `COMPACTING_MAX_SUMMARIES_PER_KIN` | `50` | Total summary retention per Kin (active + archived) |\n| `COMPACTING_MODEL` | Provider default | Override the model used for session compacting |\n| `MEMORY_EXTRACTION_MODEL` | Provider default | Override the model used for memory extraction |\n| `MEMORY_MAX_RELEVANT` | `10` | Max relevant memories injected into context |\n| `MEMORY_SIMILARITY_THRESHOLD` | `0.7` | Minimum cosine similarity for memory retrieval |\n| `MEMORY_EMBEDDING_MODEL` | `text-embedding-3-small` | Embedding model for memory vectors |\n| `MEMORY_EMBEDDING_DIMENSION` | `1536` | Vector dimension for embeddings |\n| `MEMORY_TOKEN_BUDGET` | `0` | Max tokens for memory block in prompt (`0` = unlimited) |\n| `MEMORY_RERANK_MODEL` | Provider default | Cross-encoder rerank model (Cohere, Jina) for memory retrieval |\n| `MEMORY_CONSOLIDATION_MODEL` | Provider default | Model used for memory consolidation |\n| `MEMORY_CONSOLIDATION_SIMILARITY` | `0.85` | Cosine similarity threshold for merging duplicate memories |\n| `MEMORY_CONSOLIDATION_MAX_GEN` | `5` | Max consolidation generations per run |\n| `MEMORY_MULTI_QUERY_MODEL` | Provider default | Model for multi-query expansion during recall |\n| `MEMORY_HYDE_MODEL` | Provider default | Model for HyDE (hypothetical document embedding) queries |\n| `MEMORY_CONTEXTUAL_REWRITE_MODEL` | Provider default | Model for contextual memory rewriting |\n| `MEMORY_CONTEXTUAL_REWRITE_THRESHOLD` | `80` | Token threshold to trigger contextual rewrite |\n| `MEMORY_ADAPTIVE_K` | `true` | Enable adaptive K (dynamic result count based on score distribution) |\n| `MEMORY_ADAPTIVE_K_MIN_SCORE_RATIO` | `0.3` | Minimum score ratio for adaptive K cutoff |\n| `MEMORY_RRF_K` | `60` | Reciprocal Rank Fusion K parameter for hybrid search |\n| `MEMORY_FTS_BOOST` | `0.5` | Full-text search score boost factor |\n| `MEMORY_SUBJECT_BOOST` | `1.3` | Score boost for subject-matching memories |\n| `MEMORY_CATEGORY_BOOST` | `1.25` | Score boost for category-matching memories |\n| `MEMORY_TEMPORAL_DECAY_LAMBDA` | `0.01` | Temporal decay rate (higher = faster decay) |\n| `MEMORY_TEMPORAL_DECAY_FLOOR` | `0.7` | Minimum score multiplier from temporal decay |\n| `HISTORY_TOKEN_BUDGET` | `40000` | Max tokens for conversation history in context |\n\n#### Tasks \u0026 Queues\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `QUEUE_POLL_INTERVAL` | `500` | Queue polling interval in ms |\n| `TASKS_MAX_DEPTH` | `3` | Maximum sub-task nesting depth |\n| `TASKS_MAX_REQUEST_INPUT` | `3` | Max concurrent task requests per input |\n| `TASKS_MAX_CONCURRENT` | `10` | Max concurrent tasks globally |\n| `TOOLS_MAX_STEPS` | `10` | Max tool call steps per LLM turn |\n\n#### Cron \u0026 Automation\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `CRONS_MAX_ACTIVE` | `50` | Max active cron jobs |\n| `CRONS_MAX_CONCURRENT_EXEC` | `5` | Max concurrent cron executions |\n\n#### Inter-Kin Communication\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `INTER_KIN_MAX_CHAIN_DEPTH` | `5` | Max chain depth for Kin-to-Kin messages |\n| `INTER_KIN_RATE_LIMIT` | `20` | Max inter-Kin messages per minute |\n\n#### Channels \u0026 Webhooks\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `CHANNELS_MAX_PER_KIN` | `5` | Max channel connections per Kin |\n| `WEBHOOKS_MAX_PER_KIN` | `20` | Max webhooks per Kin |\n| `WEBHOOKS_MAX_PAYLOAD_BYTES` | `1048576` | Max webhook payload size (1 MB) |\n| `WEBHOOKS_LOG_RETENTION_DAYS` | `30` | Webhook execution log retention period |\n| `WEBHOOKS_MAX_LOGS_PER_WEBHOOK` | `500` | Max stored execution logs per webhook |\n| `WEBHOOKS_RATE_LIMIT_PER_MINUTE` | `60` | Max webhook executions per minute |\n\n#### File Storage \u0026 Uploads\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `UPLOAD_DIR` | `{dataDir}/uploads` | Upload directory |\n| `UPLOAD_MAX_FILE_SIZE` | `50` | Max upload size in MB |\n| `UPLOAD_CHANNEL_RETENTION_DAYS` | `30` | Channel file retention period in days |\n| `UPLOAD_CHANNEL_CLEANUP_INTERVAL` | `60` | Channel file cleanup interval in minutes |\n| `FILE_STORAGE_DIR` | `{dataDir}/storage` | Kin file storage directory |\n| `FILE_STORAGE_MAX_SIZE` | `100` | Max file size in MB |\n| `FILE_STORAGE_CLEANUP_INTERVAL` | `60` | Cleanup interval in minutes |\n\n#### Vault\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `VAULT_ATTACHMENT_DIR` | `{dataDir}/vault` | Vault attachment directory |\n| `VAULT_MAX_ATTACHMENT_SIZE` | `50` | Max attachment size in MB |\n| `VAULT_MAX_ATTACHMENTS_PER_ENTRY` | `10` | Max attachments per vault entry |\n\n#### Workspaces \u0026 Mini Apps\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `WORKSPACE_BASE_DIR` | `{dataDir}/workspaces` | Kin workspace base directory |\n| `MINI_APPS_DIR` | `{dataDir}/mini-apps` | Mini apps storage directory |\n| `MINI_APPS_MAX_PER_KIN` | `20` | Max mini apps per Kin |\n| `MINI_APPS_MAX_FILE_SIZE` | `5` | Max single file size in MB |\n| `MINI_APPS_MAX_TOTAL_SIZE` | `50` | Max total size per app in MB |\n| `MINI_APPS_BACKEND_ENABLED` | `true` | Enable mini app backend execution |\n\n#### Web Browsing\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `WEB_BROWSING_PAGE_TIMEOUT` | `30000` | Page load timeout in ms |\n| `WEB_BROWSING_MAX_CONTENT_LENGTH` | `100000` | Max extracted content length |\n| `WEB_BROWSING_MAX_CONCURRENT` | `5` | Max concurrent fetches |\n| `WEB_BROWSING_USER_AGENT` | KinBot default | Custom User-Agent string |\n| `WEB_BROWSING_BLOCKED_DOMAINS` | *(empty)* | Comma-separated blocked domains |\n| `WEB_BROWSING_PROXY` | *(none)* | HTTP proxy for web requests |\n| `WEB_BROWSING_HEADLESS_ENABLED` | `false` | Enable headless browser (Puppeteer) |\n| `PUPPETEER_EXECUTABLE_PATH` | Auto-detected | Chrome/Chromium path for headless mode |\n| `WEB_BROWSING_MAX_BROWSERS` | `2` | Max concurrent browser instances |\n| `WEB_BROWSING_BROWSER_IDLE_TIMEOUT` | `60000` | Browser idle timeout in ms |\n\n#### MCP \u0026 Human-in-the-Loop\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `MCP_REQUIRE_APPROVAL` | `true` | Require user approval for MCP server management |\n| `HUMAN_PROMPTS_MAX_PENDING` | `5` | Max pending human-in-the-loop prompts per Kin |\n\n#### Sessions \u0026 Invitations\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `QUICK_SESSION_EXPIRATION_HOURS` | `24` | Quick session expiration time |\n| `QUICK_SESSION_MAX_PER_USER_KIN` | `1` | Max active quick sessions per user per Kin |\n| `QUICK_SESSION_RETENTION_DAYS` | `7` | Quick session data retention |\n| `QUICK_SESSION_CLEANUP_INTERVAL` | `60` | Cleanup interval in minutes |\n| `INVITATION_DEFAULT_EXPIRY_DAYS` | `7` | Default invitation link expiry |\n| `INVITATION_MAX_ACTIVE` | `50` | Max active invitations |\n\n#### Notifications\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `NOTIFICATIONS_RETENTION_DAYS` | `30` | Notification retention period |\n| `NOTIFICATIONS_MAX_PER_USER` | `500` | Max stored notifications per user |\n| `NOTIFICATIONS_EXT_MAX_PER_USER` | `5` | Max external notification endpoints per user |\n| `NOTIFICATIONS_EXT_RATE_LIMIT` | `5` | External notification rate limit per minute |\n| `NOTIFICATIONS_EXT_MAX_ERRORS` | `5` | Max consecutive errors before disabling endpoint |\n\n#### Wakeups\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `WAKEUPS_MAX_PENDING_PER_KIN` | `20` | Max pending wakeups per Kin |\n\n#### Version Check\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `VERSION_CHECK_ENABLED` | `false` | Enable automatic version checking |\n| `VERSION_CHECK_REPO` | `MarlBurroW/kinbot` | GitHub repo to check for new releases |\n| `VERSION_CHECK_INTERVAL_HOURS` | `12` | Hours between version checks |\n\n\u003c/details\u003e\n\n---\n\n## 🔧 Troubleshooting\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCommon issues and solutions\u003c/strong\u003e\u003c/summary\u003e\n\n#### Port already in use\n\n```\nError: listen EADDRINUSE :::3000\n```\n\nAnother process is using port 3000. Either stop it or change KinBot's port:\n\n```bash\nPORT=3001 bun src/server/index.ts\n# or with Docker:\ndocker run -d -p 3001:3000 ghcr.io/marlburrow/kinbot:latest\n```\n\n#### Database migration errors after update\n\nIf you see migration errors after updating KinBot:\n\n```bash\n# Backup first\ncp data/kinbot.db data/kinbot.db.bak\n\n# Re-run migrations\nbun run db:migrate\n```\n\n#### Docker container won't start\n\nCheck logs for details:\n\n```bash\ndocker logs kinbot\n```\n\nCommon causes:\n- **Permission issues on volume:** Ensure the data directory is writable (`chmod 777 ./data` or match UID)\n- **Missing encryption key:** If you previously set `ENCRYPTION_KEY`, you must provide it on every restart (vault data is encrypted with it)\n\n#### Provider connection fails\n\n- Verify your API key is correct and has sufficient credits\n- 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`)\n- Check provider status pages for outages\n\n#### Memory search returns no results\n\nMemory extraction runs asynchronously after each LLM turn. If you just started a conversation:\n- Wait a few seconds for the extraction pipeline to complete\n- Check that you have an embedding provider configured in Settings \u003e Providers\n\n#### Blank page / frontend not loading\n\n```bash\n# Rebuild the frontend\nbun run build\n\n# Then restart\nbun src/server/index.ts\n```\n\nFor Docker, pull the latest image which includes pre-built frontend assets.\n\n#### Generate a diagnostic report\n\nIf you're stuck, generate a report to include in bug reports:\n\n```bash\nbash install.sh --doctor\n```\n\n\u003c/details\u003e\n\n---\n\n## 💬 Community \u0026 Support\n\n- **Issues** — [Report bugs or request features](https://github.com/MarlBurroW/kinbot/issues)\n- **Discussions** — [Questions, ideas, and show \u0026 tell](https://github.com/MarlBurroW/kinbot/discussions)\n- **Contributing** — [Read the guide](CONTRIBUTING.md) to get started\n- **Security** — [Report vulnerabilities responsibly](SECURITY.md)\n- **Changelog** — [See what's new](https://marlburrow.github.io/kinbot/changelog)\n\nIf KinBot is useful to you, consider [starring the repo](https://github.com/MarlBurroW/kinbot) — it helps others discover the project.\n\n## Contributing\n\nContributions are welcome! See **[CONTRIBUTING.md](CONTRIBUTING.md)** for the full guide: setup, adding providers/channels, code style, and commit conventions.\n\nQuick version:\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feat/my-feature`\n3. Follow existing code conventions:\n   - Files: `kebab-case.ts` / Components: `PascalCase.tsx`\n   - Shared types in `src/shared/types.ts`; shared constants in `src/shared/constants.ts`\n   - API errors: `{ \"error\": { \"code\": \"ERROR_CODE\", \"message\": \"...\" } }`\n   - Never hardcode user-facing text — always use `useTranslation()` and add keys to both `en.json` and `fr.json`\n4. Open a Pull Request with a clear description\n\n### Design system\n\nThe UI is built on a custom design system with 8 palettes and full dark/light mode support. Before building any new UI:\n- Consult `src/client/pages/design-system/DesignSystemPage.tsx` (live showcase, source of truth)\n- Use semantic CSS variables (`var(--color-*)`) or Tailwind tokens — never hardcode colors\n- Reuse components from `src/client/components/ui/`\n\n---\n\n## License\n\nKinBot is licensed under the [GNU Affero General Public License v3.0](LICENSE) (AGPL-3.0).\n\nYou 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.\n\nFor commercial use cases where the AGPL obligations are not compatible with your business, a commercial license is available — open an issue to discuss.\n\n---\n\n\u003cdiv align=\"center\"\u003e\nMade with care · \u003ca href=\"https://github.com/marlburrow\"\u003emarlburrow\u003c/a\u003e\n\u003c/div\u003e\n","funding_links":["https://github.com/sponsors/MarlBurroW"],"categories":["🏠 Local and Self-Hosted AI","Platforms/API"],"sub_categories":["Self-Hosted Agents and UIs","Tools"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMarlBurroW%2Fkinbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMarlBurroW%2Fkinbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMarlBurroW%2Fkinbot/lists"}