Skip to content
BranchesTags

Repository files navigation

🦀 CrustAI

Your AI Assistant. Your Machine. Your Rules.

100% Private · Runs Locally · Multi-Platform · Zero Cloud

npm version Node.js License: MIT Contributions Welcome Self-Hosted Ollama

Windows macOS Linux

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. CrustAI Live Demo

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, 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

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

  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 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

🇧🇷 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.

License

MIT — see LICENSE for details.

About

Private, local-first AI assistant with Telegram, Discord, WhatsApp and Slack

Topics

aiartificial-intelligenceautomationchatbotdeveloper-toolsdiscorddiscord-jsllmllm-ollamalocal-ailocal-llmollamaopen-sourceportfolioprivacyprivacy-local-llmselfhostedtelegram-bot-ai-assistantwhatsappwhatsapp-bot

Resources

Readme
MIT license

Contributing

Contributing
Activity

Stars

11 stars

Watchers

0 watching

Forks

2 forks
Report repository

Releases

Packages

Contributors

Languages