# 🦀 CrustAI ### Your AI Assistant. Your Machine. Your Rules. **100% Private · Runs Locally · Multi-Platform · Zero Cloud** [![npm version](https://img.shields.io/npm/v/crustai.svg)](https://www.npmjs.com/package/crustai) [![Node.js](https://img.shields.io/badge/Node.js-20%2B-brightgreen?logo=node.js)](https://nodejs.org/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Contributions Welcome](https://img.shields.io/badge/Contributions-Welcome-ff69b4)](https://github.com/DaveSimoes/CrustAI/blob/main/CONTRIBUTING.md) [![Self-Hosted](https://img.shields.io/badge/Self--Hosted-100%25-blue)](https://github.com/DaveSimoes/CrustAI) [![Ollama](https://img.shields.io/badge/Ollama-Local%20LLM-orange)](https://ollama.ai) [![Windows](https://img.shields.io/badge/Windows-supported-blue)](#) [![macOS](https://img.shields.io/badge/macOS-supported-blue)](#) [![Linux](https://img.shields.io/badge/Linux-supported-blue)](#) --- > **Chat with your own AI on Telegram, Discord, WhatsApp, and Slack — no data ever leaves your machine.**

--- ## Get Started ```bash git clone https://github.com/DaveSimoes/CrustAI.git cd CrustAI && npm install && npm start ```

**AI assistant running 100% locally — chat on Telegram, fully offline.** ![CrustAI Live Demo](demo/chat.gif) new_video_real_chatonline-video-cutter com-ezgif com-optimize

new_video_real_chatonline-video-cutter com-ezgif com-optimize

--- ## Why CrustAI? Every AI assistant you use today sends your conversations to a cloud server. Your questions, your context, your data — all stored externally. **CrustAI is different.** It runs entirely on your own machine using [Ollama](https://ollama.ai), meaning: | Without CrustAI | With CrustAI | |---|---| | Conversations logged on cloud servers | Conversations stay on **your machine** | | Data used to train external models | Zero data collection, ever | | Requires paid API keys | 100% free, uses local models | | One platform (e.g., only ChatGPT web) | Works on Telegram, Discord, WhatsApp, Slack | | Internet required | Works fully **offline** | --- ## Key Features | | | |---|---| | 🔒 **100% Private** | Every message stays on your device. No telemetry, no external APIs, no logs | | 🧠 **Powered by Ollama** | Use llama3.2, mistral, phi3, tinyllama and any model you choose | | 📱 **4 Platforms, 1 Bot** | Connect to Telegram, Discord, WhatsApp, and Slack simultaneously | | 🧬 **Long-Term Memory** | Your assistant remembers facts about you across sessions | | 🗣️ **Voice Support** | Speak and listen — fully offline voice mode (pt-BR) | | ⚡ **REST API** | Integrate CrustAI into your own tools and workflows | | 🎭 **Personality Config** | Give your assistant a custom name, tone, and identity | | 🐳 **Docker Ready** | One-command deployment for servers and home labs | | 🌐 **Bilingual** | Full English + Portuguese support out of the box | --- ## Quick Start ### Prerequisites - [Node.js](https://nodejs.org) ≥ 20.0 - [Ollama](https://ollama.ai) installed and running - A platform token (e.g., Telegram Bot Token from [@BotFather](https://t.me/botfather)) ### Install & Run ```bash # 1. Clone the repository git clone https://github.com/DaveSimoes/CrustAI.git cd CrustAI # 2. Install dependencies npm install # 3. Start Ollama and pull a model ollama serve ollama pull tinyllama # lightweight — 600MB, works on any machine # or ollama pull llama3.2 # more powerful — 2GB, recommended 8GB RAM # 4. Configure cp config/config.example.yml config/config.yml # Edit config/config.yml with your platform tokens # 5. Launch CrustAI npm start ``` ## 📊 Model Benchmark Run a full performance comparison across all supported Ollama models — no cloud, no setup, just results. ```bash node scripts/benchmark.js ``` ➡️ [Full benchmark documentation](docs/BENCHMARK.md) --- ## Configuration Edit `config/config.yml`: ```yaml model: tinyllama # or llama3.2, phi3, mistral... ollama_url: http://localhost:11434 language: en # or pt-BR telegram: enabled: true token: YOUR_BOT_TOKEN_HERE allowed_user_ids: [] # leave empty to allow all users discord: enabled: false token: "" whatsapp: enabled: false slack: enabled: false voice: enabled: false port: 8765 ``` --- ## Available Commands | Command | Description | |---|---| | `/ping` | Check if the bot is alive | | `/help` | Show all available commands | | `/model` | Display which AI model is currently running | | `/remember ` | Store a fact in long-term memory | | `/forget` | Erase all stored facts | | `/clear` | Clear conversation history | --- ## Architecture ``` Messaging Platforms (Telegram / Discord / WhatsApp / Slack) │ ▼ ┌─────────────────────┐ │ Message Orchestrator│ └────────┬────────────┘ │ ┌──────────┴──────────┐ ▼ ▼ ┌─────────────┐ ┌──────────────┐ │ Ollama LLM │ │ Memory Store │ │ (local) │ │ (sql.js) │ └─────────────┘ └──────────────┘ │ │ └──────────┬──────────┘ ▼ ┌─────────────┐ │ REST API │ │ (Fastify) │ └─────────────┘ ``` **Design principle:** Adapter boundaries make it trivial to add new messaging platforms without touching the core conversation logic. --- ## How It Works 1. **Adapters** — Each platform (Telegram, Discord, WhatsApp, Slack) has its own isolated adapter. Messages are normalized into a unified format before reaching the orchestrator. 2. **Orchestrator** — Receives messages, applies personality config, queries the LLM, and manages conversation context. 3. **Ollama LLM** — Runs any compatible model locally. No network calls. No rate limits. No billing. 4. **Memory Store** — Persists user-defined facts in a local SQLite database, available across sessions. 5. **REST API** — Exposes endpoints for integrating CrustAI into custom tools, automations, and dashboards. --- ## Tech Stack | Technology | Purpose | |---|---| | **Node.js** | Runtime environment | | **Ollama** | Local LLM inference engine | | **node-telegram-bot-api** | Telegram integration | | **@whiskeysockets/baileys** | WhatsApp integration | | **discord.js** | Discord integration | | **@slack/bolt** | Slack integration | | **Fastify** | REST API server | | **sql.js** | Embedded database for memory | | **yaml** | Configuration management | --- ## Project Structure ``` crustai/ ├── src/ │ ├── core/ │ │ ├── index.js # Main orchestrator │ │ ├── llm.js # Ollama LLM client │ │ └── commands.js # Command handler │ ├── adapters/ │ │ ├── telegram/ # Telegram bot │ │ ├── discord/ # Discord bot │ │ ├── whatsapp/ # WhatsApp bot │ │ └── slack/ # Slack bot │ ├── memory/ │ │ └── store.js # Long-term memory (SQLite) │ ├── personality/ │ │ └── prompt.js # System prompt builder │ ├── voice/ │ │ └── server.js # Offline voice WebSocket server │ └── api/ │ └── server.js # REST API ├── config/ │ ├── config.yml # Your config (git-ignored) │ ├── config.example.yml # Template │ └── personality.yml # Assistant personality ├── demo/ │ ├── terminal.gif │ ├── ping.gif │ └── chat.gif └── data/ # Local database (git-ignored) ``` --- ## Privacy First CrustAI was built with privacy as its core principle — not as a feature, but as a hard technical constraint: - ✅ All conversations stay on **your machine** - ✅ No API keys sent to external AI providers - ✅ No telemetry, usage tracking, or analytics - ✅ No accounts, no sign-up, no terms-of-service surprise - ✅ Fully open source — inspect every single line - ✅ Your data. Your models. Your rules. --- ## Supported Models (via Ollama) | Model | Size | Best For | |---|---|---| | `tinyllama` | ~600MB | Low-end machines, quick replies | | `phi3` | ~2GB | Balanced performance | | `llama3.2` | ~2GB | General purpose, highly capable | | `mistral` | ~4GB | Strong reasoning and coding | | `llama3` | ~4GB | High quality conversations | Any model available on [ollama.ai](https://ollama.ai/library) can be used. --- ## Roadmap - [x] Telegram integration - [x] Discord integration - [x] WhatsApp integration - [x] Slack integration - [x] Long-term memory - [x] REST API - [x] Bilingual support (EN / PT-BR) - [ ] Web UI dashboard - [ ] Docker one-click deployment - [ ] Image understanding (multimodal LLMs) - [ ] Plugin system for custom tools - [ ] Mobile app companion --- ## Contributing Contributions are very welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR. ```bash # Fork the repository, then: git checkout -b feature/your-feature git commit -m "feat: add your feature" git push origin feature/your-feature # Open a Pull Request ``` --- ## Troubleshooting **"Connection refused" on Ollama** — Make sure Ollama is running: `ollama serve` **Bot not responding on Telegram** — Double-check your token in `config/config.yml` and that the bot was started with `/start`. **High memory usage** — Switch to a lighter model like `tinyllama`. Edit `model:` in `config/config.yml`. **WhatsApp keeps disconnecting** — WhatsApp Web sessions expire. Restart CrustAI to regenerate the QR code. --- ## Language / Idioma - 🇺🇸 [English](#-crustai) — you're reading it - 🇧🇷 [Português](#-o-que-é-o-crustai) — role para baixo --- ## 🇧🇷 O que é o CrustAI? **CrustAI** é um assistente de IA totalmente privado e auto-hospedado que roda inteiramente na sua própria máquina — nenhum dado sai do seu computador. Conecta-se ao **Telegram, WhatsApp, Discord e Slack** com o poder de modelos de linguagem locais, sem depender de nenhum provedor externo. ### ✨ Funcionalidades Principais | Funcionalidade | Descrição | |---|---| | 🔒 **100% Privado** | Todos os dados ficam na sua máquina. Sem nuvem, jamais | | 🧠 **LLM Local** | Powered by Ollama — llama3.2, tinyllama, mistral e muito mais | | 📱 **Multi-Plataforma** | Telegram, WhatsApp, Discord, Slack — um só assistente | | 🧬 **Memória Longa** | Lembra fatos sobre você entre conversas | | 🗣️ **Voz Offline** | Fala e escuta sem internet (pt-BR) | | ⚡ **REST API** | Integre o CrustAI em qualquer fluxo de trabalho | | 🎭 **Personalidade** | Configure nome, tom e comportamento do assistente | ### 🚀 Início Rápido ```bash # 1. Clone o repositório git clone https://github.com/DaveSimoes/CrustAI.git cd CrustAI # 2. Instale as dependências npm install # 3. Inicie o Ollama e baixe um modelo ollama serve ollama pull tinyllama # 4. Configure o projeto cp config/config.example.yml config/config.yml # Edite config/config.yml com seu token do Telegram # 5. Inicie o CrustAI npm start ``` --- ## Author **Dave Simoes** — Developer passionate about AI, privacy, and open source. - 🐙 GitHub: [@DaveSimoes](https://github.com/DaveSimoes) - 💼 LinkedIn: [Dave Simoes](https://linkedin.com/in/davesimoes) --- ## License MIT — see [LICENSE](LICENSE) for details. ---

**Made with 🦀 and ❤️ by Dave Simoes** [⭐ Star this repo if CrustAI helped you!](https://github.com/DaveSimoes/CrustAI) [Report Bug](https://github.com/DaveSimoes/CrustAI/issues) · [Request Feature](https://github.com/DaveSimoes/CrustAI/issues) · [Read the Docs](https://documentcrustai.netlify.app/)