GitHub - fred-terzi/totem-llm: Totem LLM - Your Mind Leads: Private AI agent designed to run on your hardware with your private data leading.
Your Mind Leads
[](https://github.com/fred-terzi/totem-llm#your-mind-leads)
**A sovereign AI solution for consumer hardware. Keep your data private, run locally, stay in control.**
- * *
🚀 Key Features
[](https://github.com/fred-terzi/totem-llm#-key-features) | Feature | Description | | --- | --- | | **Privacy First** | All data stays on your machine. | | **Consumer Hardware** | Optimized for consumer-grade devices. | | **Local & Cloud** | Choose local models via Ollama or use cloud providers (OpenRouter). | | **Easy Setup** | One-line install with automatic dependency resolution. |
- * *
📋 About
[](https://github.com/fred-terzi/totem-llm#-about)
Totem LLM is a sovereign AI solution, aimed at optimizing for consumer hardware and ensuring data privacy. It is designed to run efficiently on consumer-grade hardware, such as laptops and desktops, without the need for cloud-based processing. This allows users to have full control over their data and AI interactions, without relying on third-party services.
While local AI is the core focus, Totem LLM supports both local and cloud-based LLM providers, giving users the flexibility to choose based on their needs and preferences. The system is built with a modular architecture, allowing for easy integration of new features and providers over time.
⚙️ Requirements
[](https://github.com/fred-terzi/totem-llm#%EF%B8%8F-requirements) Before installing Totem LLM, first install the below prerequisites:
- **Node.js** v18 or later
- **Ollama** (recommended for local models) _OR_
- **OpenRouter** API key (for cloud models)
- * *
🎯 Quick Start
[](https://github.com/fred-terzi/totem-llm#-quick-start)
1️⃣ Install the Package
[](https://github.com/fred-terzi/totem-llm#1%EF%B8%8F%E2%83%A3-install-the-package) Open your terminal and run:
npm install -g totem-llm
This automatically downloads Totem LLM and installs all dependencies (server, collector, frontend).
2️⃣ Start Totem LLM
[](https://github.com/fred-terzi/totem-llm#2%EF%B8%8F%E2%83%A3-start-totem-llm)
totem-llm start
**First run:** Creates `~/totem-llm/` directory, migrates database, then launches services.
**Access:** Open http://localhost:8686 in your browser.
3️⃣ Optional: Install as Desktop App
[](https://github.com/fred-terzi/totem-llm#3%EF%B8%8F%E2%83%A3-optional-install-as-desktop-app) In the browser UI, click the **install icon** in the address bar (or use your browser menu) to add Totem LLM to your desktop. This is a link to the web GUI, but with its own window and taskbar/dock icon for easy access.
Model Selection
[](https://github.com/fred-terzi/totem-llm#model-selection) Once first installed, we recommend using qwen3.5:2b as a base model. This is a small model that is excellent to start with. It can help answer questions and provide guidance on if you can use a bigger model.
If qwen3.5:2b does not work well on your machine, it is recommened to move to OpenRouter. While a smaller model will work, there is a performance drop off.
Windows and Linux Model Download:
[](https://github.com/fred-terzi/totem-llm#windows-and-linux-model-download)
``` ollama pull qwen3.5:2b ```
Mac Model Download:
[](https://github.com/fred-terzi/totem-llm#mac-model-download)
``` ollama pull qwen3.5:2b-mlx ```
> Note: The `-mlx` suffix indicates the version optimized for Apple Silicon (M1/M2) Macs. If you are on an Intel-based Mac, use the standard `qwen3.5:2b` model.
- * *
📚 Command Reference
[](https://github.com/fred-terzi/totem-llm#-command-reference)
totem-llm start # Start server and collector totem-llm --no-collector # Start server only (skip document ingestion) totem-llm --port=8080 # Use custom server port totem-llm setup # Run first-time setup without starting totem-llm --help # Show all available commands
Environment Variables
[](https://github.com/fred-terzi/totem-llm#environment-variables)
Override default storage location (default: ~/totem-llm)
export TOTEM_STORAGE_DIR=/your/custom/path totem-llm start
- * *
🛠️ Troubleshooting
[](https://github.com/fred-terzi/totem-llm#%EF%B8%8F-troubleshooting) | Issue | Solution | | --- | --- | | **npm not found** (Windows) | Run `npm.cmd` instead of `npm` | | **totem-llm command not found** | Run `npx.cmd totem-llm start` or add npm global bin to PATH | | **PowerShell script execution error** | Run `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser` once, then retry | | **Alternative on Windows** | Use **Command Prompt** (`cmd.exe`) instead of PowerShell |
🙏 Acknowledgments
[](https://github.com/fred-terzi/totem-llm#-acknowledgments) Totem LLM is built on the foundation of **AnythingLLM** by Mintplex Labs. We are deeply grateful for their excellent work.
- * *
📄 License
[](https://github.com/fred-terzi/totem-llm#-license) Totem LLM is released under the **MIT License** — see LICENSE for details.
📞 Support
[](https://github.com/fred-terzi/totem-llm#-support)
- 🐛 **Report Issues** → GitHub Issues
- 💬 **Discussions** → GitHub Discussions
- * *