Your AI Assistant. Your Machine. Your Rules.
100% Private · Runs Locally · Multi-Platform · Zero Cloud
Chat with your own AI on Telegram, Discord, WhatsApp, and Slack — no data ever leaves your machine.
Get Started
git clone https://github.com/DaveSimoes/CrustAI.git cd CrustAI && npm install && npm start
AI assistant running 100% locally — chat on Telegram, fully offline.
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, 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 ≥ 20.0
- Ollama installed and running
- A platform token (e.g., Telegram Bot Token from @BotFather)
Install & Run
# 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.
node scripts/benchmark.js
➡️ Full benchmark documentation
Configuration
Edit config/config.yml:
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 <fact> |
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
- Adapters — Each platform (Telegram, Discord, WhatsApp, Slack) has its own isolated adapter. Messages are normalized into a unified format before reaching the orchestrator.
- Orchestrator — Receives messages, applies personality config, queries the LLM, and manages conversation context.
- Ollama LLM — Runs any compatible model locally. No network calls. No rate limits. No billing.
- Memory Store — Persists user-defined facts in a local SQLite database, available across sessions.
- 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 can be used.
Roadmap
- Telegram integration
- Discord integration
- WhatsApp integration
- Slack integration
- Long-term memory
- REST API
- 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 before opening a PR.
# 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 — you're reading it
- 🇧🇷 Português — 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
# 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
- 💼 LinkedIn: Dave Simoes
License
MIT — see LICENSE for details.