LocalMind — AI Without Limits

LocalMind — AI Without Limits

A free, open-source AI platform that lets you run local LLMs, connect cloud AI providers, teach your AI with your own data, and share your AI instance globally — all with full privacy and unlimited usage.

Quick Start • Features • Installation • API Docs • Contributing

🔥 Overview

LocalMind is a free, open-source, self-hosted AI platform designed for students, developers, researchers, and creators who demand powerful AI capabilities without the constraints of subscriptions, usage limits, or privacy compromises.

Why LocalMind?

Traditional AI platforms lock you in with:

💸 Monthly subscription fees
🚫 Message and usage limits
🔍 Privacy concerns with data collection
☁️ Dependency on cloud services
🔒 Vendor lock-in

LocalMind sets you free with:

✅ 100% Free & Open Source — No hidden costs, ever
✅ Unlimited Usage — No message caps or rate limits
✅ Full Privacy — Your data never leaves your machine
✅ Hybrid Architecture — Mix local and cloud models seamlessly
✅ Custom Training — Teach AI with your own datasets
✅ Global Sharing — Expose your AI to the world instantly
✅ Developer-Friendly — RESTful API for easy integration

Perfect For

🎓 Students learning AI and machine learning
👨‍💻 Developers building AI-powered applications
🔬 Researchers conducting experiments with LLMs
🚀 Startups needing custom AI solutions without enterprise costs
🏢 Organizations requiring private AI infrastructure
🎨 Creators experimenting with AI-assisted content generation

✨ Features

🧠 AI Model Support

LocalMind provides a unified interface to interact with both local and cloud-based AI models:

🖥️ Local Models (via Ollama)

Run powerful open-source models completely offline:

Model Family	Description	Use Cases
LLaMA	Meta's flagship open model	General chat, reasoning, coding
Mistral	High-performance 7B model	Fast responses, efficiency
Phi	Microsoft's compact model	Edge devices, quick tasks
Gemma	Google's open model	Balanced performance
Custom Models	Any Ollama-compatible model	Specialized tasks

☁️ Cloud Models

Integrate premium AI services when needed:

Google Gemini — Advanced reasoning and multimodal
OpenAI GPT — Industry-leading language models
Groq — Ultra-fast inference speeds
RouterAI — Intelligent model routing
Coming Soon: Anthropic Claude, Cohere, AI21 Labs

Switch between models instantly — No code changes required!

📚 RAG: Train with Your Own Data

Transform LocalMind into your personal AI expert using Retrieval-Augmented Generation (RAG):

Supported Formats

📊 Excel Files (.xlsx, .xls) — Import spreadsheets directly
📄 CSV Files — Parse comma-separated datasets
❓ Q&A Datasets — Upload question-answer pairs for fine-tuning
🔜 Coming Soon: PDF, TXT, JSON, and more

How It Works

Upload your documents through the UI
Processing — Automatic text extraction and chunking
Vectorization — Converts data to embeddings
Storage — Creates a private vector database
Querying — AI retrieves relevant context for responses

Use Cases

📖 Build a chatbot trained on your company's documentation
🎓 Create a study assistant with your course materials
🔬 Analyze research papers and datasets
💼 Build internal knowledge bases
📊 Query business data using natural language

Your data stays 100% local — No cloud uploads, no external storage.

🌐 Global AI Sharing

Share your LocalMind instance with anyone, anywhere:

Exposure Methods

Method	Speed	Custom Domain	Security
LocalTunnel	Fast	✅	Basic
Ngrok	Fast	✅ Pro	Advanced

Benefits

🌍 Instant Deployment — No server setup required
🔗 Shareable URLs — Send links to teammates or clients
🚀 Perfect for Demos — Showcase your AI projects
👥 Collaborative Testing — Get feedback from users
📱 Access Anywhere — Use your AI from any device

Security Features

🔐 API key authentication
🚦 Rate limiting
🔒 HTTPS encryption
📊 Usage monitoring

🔒 Privacy & Security

Your data is yours — always.

Privacy Guarantees

🏠 Local Processing — RAG data never leaves your machine
🔑 Encrypted Storage — API keys stored securely
🚫 No Telemetry — Zero analytics or tracking
👁️ Open Source — Audit every line of code
🔓 No Vendor Lock-In — Export data anytime

Security Features

🛡️ JWT-based authentication
🔐 Bcrypt password hashing
🔒 CORS protection
🚦 Rate limiting
📝 Request validation
🔍 SQL injection prevention

🚀 Quick Start

Get LocalMind running in under 5 minutes:

# Clone the repository
git clone https://github.com/NexGenStudioDev/LocalMind.git
cd LocalMind

# Install dependencies
cd server && npm install
cd ../client && npm install

# Start the backend
cd server && npm run dev

# Start the frontend (in a new terminal)
cd client && npm run dev

# Open http://localhost:5173

That's it! You're ready to chat with AI. 🎉

For detailed setup instructions, see the Installation Guide below.

📦 Installation Guide

Prerequisites

Ensure you have the following installed:

Software	Version	Download
Node.js	18.x or higher	nodejs.org
npm	9.x or higher	Included with Node.js
Git	Latest	git-scm.com
Ollama (optional)	Latest	ollama.ai

Verify Installation

node --version  # Should show v18.x.x or higher
npm --version   # Should show 9.x.x or higher
git --version   # Should show git version 2.x.x

1. Backend Setup

# Navigate to server directory
cd server

# Install dependencies
npm install

# Create environment file
cp .env.example .env

# Edit .env with your preferred editor
nano .env

# Start development server
npm run dev

The backend will be available at http://localhost:3000

Available Scripts

npm run dev          # Start development server with hot reload
npm run build        # Compile TypeScript to JavaScript
npm run start        # Run production build
npm run lint         # Check code quality with ESLint
npm run lint:fix     # Fix ESLint errors automatically
npm run format       # Format code with Prettier
npm run format:check # Check code formatting
npm run type-check   # Check TypeScript types without building
npm run test         # Run test suite

2. Frontend Setup

# Navigate to client directory
cd client

# Install dependencies
npm install

# Start development server
npm run dev

The frontend will be available at http://localhost:5173

Available Scripts

npm run dev          # Start Vite dev server
npm run build        # Build for production
npm run preview      # Preview production build
npm run lint         # Check code quality with ESLint
npm run lint:fix     # Fix ESLint errors automatically
npm run format       # Format code with Prettier
npm run format:check # Check code formatting
npm run type-check   # Check TypeScript types without building

3. Docker (Recommended for Production)

Run LocalMind with Docker for simplified deployment and consistent environments.

Prerequisites

Docker (v20.10 or higher) - Install Docker
Docker Compose (v2.0 or higher) - Usually included with Docker Desktop

Verify installation:

docker --version
docker compose version

Quick Start with Docker Compose

Configure environment variables:
```
cp env.example .env
# Edit .env with your preferred editor
nano .env
```
Required variables:
- LOCALMIND_SECRET - Generate with: openssl rand -base64 32
- JWT_SECRET - Same as LOCALMIND_SECRET or generate separately
- Your_Name, YOUR_EMAIL, YOUR_PASSWORD - Admin credentials
- DB_CONNECTION_STRING - MongoDB connection string
- API keys for cloud providers (optional)

Build and start the application:

# Build and run (combined backend + frontend)
docker compose up -d

# View logs
docker compose logs -f localmind

# Check container status
docker compose ps

Access the application:
- Frontend & API: http://localhost:3000
- API endpoints: http://localhost:3000/api/v1

Using Separate Services (Advanced)

For independent scaling of backend and frontend:

# Use separate services configuration
docker compose -f docker-compose.separate.yml up -d

# Access:
# - Frontend: http://localhost:80
# - Backend API: http://localhost:3000

Docker Commands Reference

# Build the image
docker build -t localmind:latest .

# Run container manually
docker run -d \
  --name localmind-app \
  -p 3000:3000 \
  --env-file .env \
  -v localmind-uploads:/app/uploads \
  -v localmind-data:/app/data \
  localmind:latest

# Stop services
docker compose down

# Stop and remove volumes (⚠️ deletes data)
docker compose down -v

# Rebuild after code changes
docker compose up -d --build

# View logs
docker compose logs -f

# Execute commands in container
docker compose exec localmind sh

Docker Features

✅ Multi-stage builds - Optimized image size (~300MB)
✅ Non-root user - Enhanced security
✅ Health checks - Automatic container monitoring
✅ Volume persistence - Data survives container restarts
✅ Environment variables - Easy configuration
✅ Resource limits - Prevent resource exhaustion

Troubleshooting Docker

Container won't start:

# Check logs
docker compose logs localmind

# Verify environment variables
docker compose exec localmind env

Port already in use:

# Change port in docker-compose.yml
ports:
  - '8080:3000'  # Access via localhost:8080

Permission errors:

# Fix volume permissions
docker compose exec localmind chown -R localmind:localmind /app/uploads /app/data

For more Docker details, see the Docker Deployment Guide section below.

⚙️ Configuration

Environment Variables

Create a .env file in the server directory:

# Server Configuration
PORT=3000
NODE_ENV=development
ENVIRONMENT=development

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/localmind
MONGO_URI=mongodb://localhost:27017/localmind

# Authentication
LOCALMIND_SECRET=your-super-secret-jwt-key-change-this
JWT_EXPIRATION=7d
REFRESH_TOKEN_EXPIRATION=30d

# AI Configuration
DEFAULT_MODEL=gemini-pro
OLLAMA_HOST=http://localhost:11434

# Cloud AI Provider Keys
GEMINI_API_KEY=your-gemini-api-key-here
OPENAI_API_KEY=your-openai-api-key-here
GROQ_API_KEY=your-groq-api-key-here
ROUTERAI_API_KEY=your-routerai-api-key-here

# RAG Configuration
VECTOR_DB_PATH=./data/vectordb
MAX_FILE_SIZE=50MB
SUPPORTED_FORMATS=.xlsx,.csv,.xls

# Tunnel Configuration
LOCALTUNNEL_SUBDOMAIN=my-localmind
NGROK_AUTHTOKEN=your-ngrok-token-here

# Security
CORS_ORIGIN=http://localhost:5173
RATE_LIMIT_WINDOW=15m
RATE_LIMIT_MAX=100

# Logging
LOG_LEVEL=info
LOG_FILE=./logs/app.log

⚠️ Security Warning: Never commit .env files to version control. Add .env to your .gitignore.

Frontend Configuration

Create a .env file in the client directory:

VITE_API_URL=http://localhost:3000
VITE_APP_NAME=LocalMind
VITE_ENABLE_ANALYTICS=false

🔧 Code Quality & Linting

LocalMind uses ESLint and Prettier to maintain consistent code style and catch errors early.

Setup

Install dependencies (if not already installed):

# Root directory
pnpm install

# Backend
cd LocalMind-Backend && pnpm install

# Frontend
cd LocalMind-Frontend && pnpm install

Install Husky (for pre-commit hooks):

# From root directory
pnpm install
pnpm prepare

Available Commands

Backend

cd LocalMind-Backend

pnpm lint          # Check for linting errors
pnpm lint:fix      # Automatically fix linting errors
pnpm format        # Format code with Prettier
pnpm format:check  # Check code formatting without changing files
pnpm type-check    # Check TypeScript types

Frontend

cd LocalMind-Frontend

pnpm lint          # Check for linting errors
pnpm lint:fix      # Automatically fix linting errors
pnpm format        # Format code with Prettier
pnpm format:check  # Check code formatting without changing files
pnpm type-check    # Check TypeScript types

Root (Run for both)

# From project root
pnpm lint          # Lint both backend and frontend
pnpm lint:fix      # Fix linting errors in both
pnpm format        # Format both backend and frontend
pnpm format:check  # Check formatting in both

Pre-commit Hooks

Husky automatically runs linting and formatting on staged files before each commit:

✅ Automatically formats code with Prettier
✅ Fixes ESLint errors when possible
✅ Prevents commits with linting errors

To bypass hooks (not recommended):

git commit --no-verify

Editor Integration (VS Code)

Install recommended extensions:
- Prettier - Code formatter
- ESLint
Settings are already configured in .vscode/settings.json:
- Format on save enabled
- ESLint auto-fix on save enabled
- Prettier as default formatter
Reload VS Code after installing extensions

Configuration Files

.prettierrc - Shared Prettier configuration
.prettierignore - Files to ignore when formatting
LocalMind-Backend/eslint.config.js - Backend ESLint config
LocalMind-Frontend/eslint.config.js - Frontend ESLint config

Rules & Standards

TypeScript: Strict mode enabled, no any types (warnings)
Code Style: Single quotes, no semicolons, 2-space indentation
Unused Variables: Allowed if prefixed with _
Console: Only console.warn and console.error allowed

📁 Project Structure

LocalMind/
│

├── server/                      # Backend application
│   ├── src/
│   │   ├── config/             # Configuration files
│   │   ├── controllers/        # Request handlers
│   │   ├── middleware/         # Express middleware
│   │   ├── models/             # Database models
│   │   ├── routes/             # API routes
│   │   ├── services/           # Business logic
│   │   │   ├── ai/            # AI provider integrations
│   │   │   ├── rag/           # RAG implementation
│   │   │   └── tunnel/        # Tunnel services
│   │   ├── utils/              # Helper functions
│   │   ├── validators/         # Input validation
│   │   └── index.ts           # Entry point
│   ├── tests/                  # Test files
│   ├── .env.example           # Environment template
│   ├── package.json
│   └── tsconfig.json
│
├── client/                      # Frontend application
│   ├── public/                 # Static assets
│   ├── src/
│   │   ├── assets/            # Images, fonts, etc.
│   │   ├── components/        # React components
│   │   │   ├── chat/
│   │   │   ├── upload/
│   │   │   └── settings/
│   │   ├── hooks/             # Custom React hooks
│   │   ├── pages/             # Page components
│   │   ├── services/          # API client
│   │   ├── store/             # State management
│   │   ├── styles/            # CSS/SCSS files
│   │   ├── types/             # TypeScript types
│   │   ├── utils/             # Helper functions
│   │   ├── App.tsx            # Root component
│   │   └── main.tsx           # Entry point
│   ├── .env.example
│   ├── package.json
│   ├── tsconfig.json
│   └── vite.config.ts
│
├── docs/                        # Documentation
├── scripts/                     # Utility scripts
├── docker-compose.yml
├── .gitignore
├── LICENSE
└── README.md
=======
├── assets/
│   └── Banner_LocalMind.png
│
├── LocalMind-Backend/
│   ├── src/
│   │   └── ... (backend source code)
│   │
│   ├── types/
│   │   └── ... (TypeScript types)
│   │
│   ├── .env.example
│   ├── .gitignore
│   ├── .prettierignore
│   ├── .prettierrc
│   ├── a.md
│   ├── jest.config.ts
│   ├── package.json
│   ├── pnpm-lock.yaml
│   ├── setup-cloudflare.sh
│   ├── tsconfig.json
│
├── LocalMind-Frontend/
│   ├── public/
│   │   └── ... (static assets)
│   │
│   ├── src/
│   │   └── ... (React code)
│   │
│   ├── .gitignore
│   ├── eslint.config.js
│   ├── index.html
│   ├── package.json
│   ├── pnpm-lock.yaml
│   ├── tsconfig.app.json
│   ├── tsconfig.json
│   ├── tsconfig.node.json
│   ├── vite.config.ts
│
├── Contributing.md
├── LICENSE
└── README.md

🧩 API Documentation

Base URL

http://localhost:3000/api/v1

Authentication

All protected endpoints require a JWT token in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

🔐 Authentication & User Management

Register User

POST /api/v1/user/register
Content-Type: application/json

{
  "username": "john_doe",
  "email": "john@example.com",
  "password": "SecurePassword123!"
}

Response:

{
  "success": true,
  "message": "User registered successfully",
  "data": {
    "userId": "abc123",
    "username": "john_doe",
    "email": "john@example.com",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Login

POST /api/v1/user/login
Content-Type: application/json

{
  "email": "john@example.com",
  "password": "SecurePassword123!"
}

Get User Profile

GET /api/v1/user/profile
Authorization: Bearer YOUR_JWT_TOKEN

Update Profile

PUT /api/v1/user/profile
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "username": "john_updated",
  "preferences": {
    "defaultModel": "gemini-pro",
    "theme": "dark"
  }
}

⚙️ AI Configuration & API Keys

Generate LocalMind API Key

POST /api/v1/user/local-mind-api-key-generator
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "name": "Production API Key",
  "permissions": ["chat", "upload", "train"]
}

Response:

{
  "success": true,
  "data": {
    "apiKey": "lm_1234567890abcdef",
    "name": "Production API Key",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

List API Keys

GET /api/v1/user/local-mind-api-keys
Authorization: Bearer YOUR_JWT_TOKEN

Delete API Key

DELETE /api/v1/user/local-mind-api-keys/:keyId
Authorization: Bearer YOUR_JWT_TOKEN

Get AI Configuration

GET /api/v1/user/ai-config
Authorization: Bearer YOUR_JWT_TOKEN

Update AI Configuration

PUT /api/v1/user/ai-config
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "providers": {
    "gemini": {
      "enabled": true,
      "apiKey": "your-gemini-key"
    },
    "ollama": {
      "enabled": true,
      "host": "http://localhost:11434"
    }
  },
  "defaultModel": "gemini-pro"
}

💬 Chat & Messaging

Send Message

POST /api/v1/chat/send-message
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "message": "What is quantum computing?",
  "model": "gemini-pro",
  "conversationId": "conv_123",
  "useRAG": true
}

Response:

{
  "success": true,
  "data": {
    "messageId": "msg_456",
    "response": "Quantum computing is...",
    "model": "gemini-pro",
    "timestamp": "2024-01-15T10:30:00Z",
    "tokensUsed": 245
  }
}

Stream Message (SSE)

POST /api/v1/chat/stream
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "message": "Write a poem about AI",
  "model": "gpt-4"
}

Get Chat History

GET /api/v1/chat/history?conversationId=conv_123&limit=50
Authorization: Bearer YOUR_JWT_TOKEN

Create New Conversation

POST /api/v1/chat/conversation
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "title": "Project Discussion",
  "model": "gemini-pro"
}

Delete Conversation

DELETE /api/v1/chat/conversation/:conversationId
Authorization: Bearer YOUR_JWT_TOKEN

📚 File Upload & RAG Training

Upload Excel/CSV

POST /api/v1/upload/excel
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: multipart/form-data

file: [your-file.xlsx]
name: "Sales Data Q4"
description: "Quarterly sales figures"

Response:

{
  "success": true,
  "data": {
    "fileId": "file_789",
    "name": "Sales Data Q4",
    "size": 2048576,
    "rowCount": 1500,
    "status": "processing"
  }
}

Upload Q&A Dataset

POST /api/v1/upload/dataSet
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "name": "FAQ Dataset",
  "questions": [
    {
      "question": "What is LocalMind?",
      "answer": "LocalMind is an open-source AI platform..."
    }
  ]
}

Train Model with Uploaded Data

POST /api/v1/train/upload
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "fileId": "file_789",
  "chunkSize": 500,
  "overlapSize": 50
}

Get Upload Status

GET /api/v1/upload/status/:fileId
Authorization: Bearer YOUR_JWT_TOKEN

List Uploaded Files

GET /api/v1/upload/files
Authorization: Bearer YOUR_JWT_TOKEN

Delete Uploaded File

DELETE /api/v1/upload/files/:fileId
Authorization: Bearer YOUR_JWT_TOKEN

🌐 Public Exposure

Expose via LocalTunnel

POST /api/v1/expose/localtunnel
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "subdomain": "my-awesome-ai",
  "port": 3000
}

Response:

{
  "success": true,
  "data": {
    "url": "https://my-awesome-ai.loca.lt",
    "status": "active"
  }
}

Expose via Ngrok

POST /api/v1/expose/ngrok
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "authToken": "your-ngrok-token",
  "domain": "myapp.ngrok.io"
}

Get Exposure Status

GET /api/v1/expose/status
Authorization: Bearer YOUR_JWT_TOKEN

Stop Exposure

DELETE /api/v1/expose/stop
Authorization: Bearer YOUR_JWT_TOKEN

📊 Analytics & Monitoring

Get Usage Statistics

GET /api/v1/analytics/usage
Authorization: Bearer YOUR_JWT_TOKEN

Get Model Performance

GET /api/v1/analytics/models
Authorization: Bearer YOUR_JWT_TOKEN

💡 Usage Examples

Example 1: Basic Chat

// Initialize client
const API_URL = 'http://localhost:3000/api/v1'
const token = 'your-jwt-token'

// Send message
const response = await fetch(`${API_URL}/chat/send-message`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${token}`,
  },
  body: JSON.stringify({
    message: 'Explain machine learning in simple terms',
    model: 'gemini-pro',
  }),
})

const data = await response.json()
console.log(data.data.response)

Example 2: Upload and Train with Custom Data

// Upload Excel file
const formData = new FormData()
formData.append('file', fileInput.files[0])
formData.append('name', 'Company Knowledge Base')

const uploadResponse = await fetch(`${API_URL}/upload/excel`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
  },
  body: formData,
})

const {
  data: { fileId },
} = await uploadResponse.json()

// Train model with uploaded data
const trainResponse = await fetch(`${API_URL}/train/upload`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${token}`,
  },
  body: JSON.stringify({
    fileId,
    chunkSize: 500,
  }),
})

// Use RAG-enhanced chat
const chatResponse = await fetch(`${API_URL}/chat/send-message`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${token}`,
  },
  body: JSON.stringify({
    message: 'What does our policy say about remote work?',
    useRAG: true,
  }),
})

Example 3: Streaming Responses

const eventSource = new EventSource(
  `${API_URL}/chat/stream?token=${token}&message=Write a story about AI`
)

eventSource.onmessage = event => {
  const chunk = JSON.parse(event.data)
  console.log(chunk.content) // Display chunk in real-time
}

eventSource.onerror = () => {
  eventSource.close()
}

Example 4: Expose Your AI Globally

// Start LocalTunnel
const exposeResponse = await fetch(`${API_URL}/expose/localtunnel`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${token}`,
  },
  body: JSON.stringify({
    subdomain: 'my-ai-demo',
  }),
})

const {
  data: { url },
} = await exposeResponse.json()
console.log(`Your AI is now accessible at: ${url}`)

🛠️ Tech Stack

Backend

Technology	Purpose	Version
Node.js	Runtime environment	18+
Express	Web framework	4.x
TypeScript	Type safety	5.x
Prisma / MongoDB	Database ORM	Latest
JWT	Authentication	Latest
Multer	File uploads	Latest
LangChain	RAG implementation	Latest
Ollama SDK	Local LLM integration	Latest

Frontend

Technology	Purpose	Version
React	UI framework	18+
TypeScript	Type safety	5.x
Vite	Build tool	5.x
TailwindCSS	Styling	3.x
Zustand	State management	Latest
React Query	Data fetching	Latest
React Router	Navigation	6.x
Axios	HTTP client	Latest

AI & ML

Ollama — Local LLM runtime
LangChain — RAG framework
Vector Databases — Embeddings storage
Google Gemini SDK
OpenAI SDK
Groq SDK

🔧 Troubleshooting

Common Issues

1. Backend Won't Start

Problem: Error: Cannot find module 'express'

Solution:

cd server
rm -rf node_modules package-lock.json
npm install
npm run dev

2. Ollama Connection Failed

Problem: Error: ECONNREFUSED localhost:11434

Solution:

Ensure Ollama is installed and running: ollama serve
Check Ollama status: ollama list
Verify OLLAMA_HOST in .env

3. File Upload Fails

Problem: Error: File size exceeds limit

Solution:

Check MAX_FILE_SIZE in .env
Increase the limit if needed
Compress large files before uploading

4. RAG Not Working

Problem: AI doesn't use uploaded data

Solution:

Verify file was processed: GET /api/v1/upload/status/:fileId
Ensure useRAG: true in chat request
Check vector database path in .env

5. CORS Errors

Problem: Access-Control-Allow-Origin error

Solution:

Update CORS_ORIGIN in server .env
Restart backend server
Check frontend URL matches CORS_ORIGIN

🗺️ Roadmap

Version 1.1 (Q2 2024)

Version 1.2 (Q3 2024)

Version 2.0 (Q4 2024)

Community Requests

WhatsApp/Telegram bot integration
Markdown export for conversations
Custom model fine-tuning UI
Blockchain-based API key management

Want to suggest a feature? Open an issue or join our Discord community!

🤝 Contributing

We ❤️ contributions! Here's how you can help:

Ways to Contribute

🐛 Report bugs — Found a bug? Open an issue
💡 Suggest features — Have ideas? Share them!
📝 Improve docs — Help others understand LocalMind
🔧 Submit PRs — Fix bugs or add features
🌍 Translate — Make LocalMind accessible worldwide
⭐ Star the repo — Show your support!

Development Workflow

Fork the repository

# Click "Fork" on GitHub, then:
git clone https://github.com/YOUR_USERNAME/LocalMind.git
cd LocalMind

Create a feature branch
```
git checkout -b feature/amazing-feature
```
Make your changes
- Follow TypeScript best practices
- Write clean, documented code
- Add tests for new features
- Update documentation

Test your changes

npm run test
npm run lint
npm run type-check

Commit with conventional commits

git commit -m "feat: add amazing feature"
git commit -m "fix: resolve bug in chat"
git commit -m "docs: update API documentation"

Push and create PR

git push origin feature/amazing-feature
# Then open a Pull Request on GitHub

Commit Message Guidelines

We follow Conventional Commits:

feat: — New feature
fix: — Bug fix
docs: — Documentation changes
style: — Code style changes (formatting, etc.)
refactor: — Code refactoring
test: — Adding or updating tests
chore: — Build process or auxiliary tool changes

Code Style

TypeScript — Use strict typing, avoid any
ESLint — Follow configured rules
Prettier — Auto-format on save
Naming — Use camelCase for variables, PascalCase for components
Comments — Document complex logic

Pull Request Process

Update README.md with details of changes if needed
Update the documentation with new API endpoints
Add tests for new functionality
Ensure all tests pass
Request review from maintainers
Address review feedback
Squash commits before merging

Community Guidelines

Be respectful and inclusive
Provide constructive feedback
Help newcomers get started
Follow our Code of Conduct

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

What This Means

✅ Commercial use — Use LocalMind in commercial projects
✅ Modification — Modify the code as you see fit
✅ Distribution — Share LocalMind with others
✅ Private use — Use it privately in your organization

⚠️ Limitation of liability — Use at your own risk
⚠️ No warranty — Provided "as is"

Attribution appreciated but not required! If you build something cool with LocalMind, let us know — we'd love to feature it!

🙏 Acknowledgments

LocalMind stands on the shoulders of giants. Huge thanks to:

Open Source Projects

Ollama — Making local LLMs accessible
LangChain — Powering our RAG implementation
React — Building amazing UIs
Vite — Lightning-fast build tool
Express — Reliable backend framework

AI Providers

Google — Gemini API
OpenAI — GPT models
Meta — LLaMA models
Mistral AI — Open models
Groq — Fast inference

Community

All our contributors
Everyone who reported bugs and suggested features
The open-source community for inspiration

Special Thanks

Students and educators using LocalMind for learning
Developers building amazing apps with our API
Contributors who helped improve the codebase
You for choosing LocalMind! 🎉

👤 Author

NexGenStudioDev

Connect With Us

🌐 Website: [Coming Soon]
💼 GitHub: @NexGenStudioDev
🐦 Twitter: [Coming Soon]
💬 Discord: Join our community
📧 Email: support@localmind.ai

Support the Project

If LocalMind has been helpful to you:

⭐ Star this repository on GitHub
🐦 Share it on social media
📝 Write about it on your blog
💰 Sponsor development (Coming Soon)
🤝 Contribute code or documentation

📊 Project Stats

🎯 Support

Getting Help

📖 Documentation: Read our full docs
💬 Discord: Join our community server
🐛 Bug Reports: Open an issue
💡 Feature Requests: Suggest features
📧 Email: support@localmind.ai

FAQ

Q: Is LocalMind really free?
A: Yes! 100% free and open-source. No hidden costs, no premium tiers, no subscriptions.

Q: Can I use LocalMind commercially?
A: Absolutely! The MIT license allows commercial use.

Q: Do I need a GPU for local models?
A: Recommended but not required. Ollama works on CPU, but GPU speeds things up significantly.

Q: How much disk space do I need?
A: Base installation: ~500MB. Each Ollama model: 2-7GB depending on size.

Q: Can I deploy LocalMind to production?
A: Yes! Use Docker for easy deployment. See our deployment guide.

Q: Is my data secure?
A: Yes. RAG data stays on your machine. API keys are encrypted. No telemetry or tracking.

Q: Can I contribute without coding?
A: Yes! Help with documentation, translations, bug reports, or spread the word.

🚀 LocalMind — Free, Private, Limitless AI for Everyone

Built with ❤️ by the open-source community

Get Started • Documentation • Join Community • Report Bug

_{If you find LocalMind useful, please consider giving it a ⭐️ on GitHub!}

🐳 Docker Deployment Guide

This guide will help you deploy LocalMind using Docker for a consistent, portable, and production-ready setup.

📋 Prerequisites

Before you begin, ensure you have installed:

Docker (v20.10 or higher) - Install Docker
Docker Compose (v2.0 or higher) - Usually included with Docker Desktop

Verify installation:

docker --version
docker compose version

🚀 Quick Start

Option 1: Using Docker Compose (Recommended)

Clone the repository:

git clone https://github.com/your-username/LocalMind.git
cd LocalMind

Configure environment variables:
```
cp .env.example .env
nano .env  # Edit with your preferred editor
```
Required variables to set:
- LOCALMIND_SECRET - Generate with: openssl rand -base64 32
- Add API keys for cloud providers (optional)
Start the application:
```
docker compose up -d
```
Access LocalMind:
- Open your browser: http://localhost:3000
- The application will serve both backend API and frontend
View logs:
```
docker compose logs -f localmind
```

Option 2: Using Docker CLI

Build the image:
```
docker build -t localmind:latest .
```

Run the container:

docker run -d \
  --name localmind-app \
  -p 3000:3000 \
  -e LOCALMIND_SECRET="your-secret-key" \
  -e API_KEY="your-api-key" \
  -e OLLAMA_HOST="http://host.docker.internal:11434" \
  -v localmind-uploads:/app/uploads \
  -v localmind-data:/app/data \
  localmind:latest

Access the application:
- http://localhost:3000

⚙️ Configuration

Environment Variables

Create a .env file in the project root with the following variables:

Variable	Description	Required	Default
`NODE_ENV`	Environment mode	No	`production`
`PORT`	Application port	No	`3000`
`LOCALMIND_SECRET`	JWT secret key	Yes	-
`API_KEY`	Generic API key	No	-
`OPENAI_API_KEY`	OpenAI API key	No	-
`GEMINI_API_KEY`	Google Gemini key	No	-
`GROQ_API_KEY`	Groq API key	No	-
`OLLAMA_HOST`	Ollama server URL	No	`http://host.docker.internal:11434`

Generate a secure secret:

openssl rand -base64 32

Connecting to Ollama

If Ollama runs on your host machine:

OLLAMA_HOST=http://host.docker.internal:11434

If Ollama runs in Docker (uncomment the ollama service in docker-compose.yml):

OLLAMA_HOST=http://ollama:11434

📦 Docker Commands Reference

Building & Running

# Build the image
docker build -t localmind:latest .

# Run container (basic)
docker run -d -p 3000:3000 --name localmind-app localmind:latest

# Run with environment variables
docker run -d -p 3000:3000 \
  --env-file .env \
  --name localmind-app \
  localmind:latest

# Run with volumes (persist data)
docker run -d -p 3000:3000 \
  -v localmind-uploads:/app/uploads \
  -v localmind-data:/app/data \
  --name localmind-app \
  localmind:latest

Managing Containers

# Start container
docker start localmind-app

# Stop container
docker stop localmind-app

# Restart container
docker restart localmind-app

# View logs
docker logs localmind-app
docker logs -f localmind-app  # Follow logs

# Check container status
docker ps -a

# Execute commands in running container
docker exec -it localmind-app sh

Docker Compose Commands

# Start services
docker compose up -d

# Stop services
docker compose down

# Stop and remove volumes (⚠️ deletes data)
docker compose down -v

# View logs
docker compose logs -f

# Rebuild and restart
docker compose up -d --build

# Scale services (if needed)
docker compose up -d --scale localmind=3

Cleanup

# Remove container
docker rm -f localmind-app

# Remove image
docker rmi localmind:latest

# Remove volumes (⚠️ permanent data loss)
docker volume rm localmind-uploads localmind-data

# Clean up all unused resources
docker system prune -a --volumes

🔍 Troubleshooting

Container won't start

Check logs:

docker logs localmind-app

Common issues:

Missing required environment variables
Port 3000 already in use
Insufficient permissions

Port already in use

# Find process using port 3000
lsof -i :3000  # macOS/Linux
netstat -ano | findstr :3000  # Windows

# Change port in docker-compose.yml
ports:
  - "8080:3000"  # Access via localhost:8080

Can't connect to Ollama

Verify Ollama is running:
```
curl http://localhost:11434/api/version
```

Check Docker network:

docker network inspect localmind-network

Use correct host:
- Host machine: http://host.docker.internal:11434
- Docker container: http://ollama:11434

Permission denied errors

# Fix volume permissions
docker exec -it localmind-app chown -R localmind:localmind /app/uploads /app/data

Out of memory

Increase Docker resources:

Docker Desktop → Settings → Resources → Memory (increase to 4GB+)

Or limit container memory:

docker run -d -p 3000:3000 \
  --memory="2g" \
  --name localmind-app \
  localmind:latest

🔒 Security Best Practices

Never commit .env files:

# Ensure .env is in .gitignore
echo ".env" >> .gitignore

Use strong secrets:

# Generate secure random secret
openssl rand -base64 32

Run as non-root user:
- The Dockerfile already implements this
- User localmind (UID 1001) is used

Keep images updated:

docker pull node:20-alpine
docker compose build --no-cache

Scan for vulnerabilities:
```
docker scan localmind:latest
```

🚢 Production Deployment

Using Docker Compose (Production)

Create production docker-compose:

cp docker-compose.yml docker-compose.prod.yml

Update production settings:

environment:
  - NODE_ENV=production
  - LOG_LEVEL=error

Deploy:

docker compose -f docker-compose.prod.yml up -d

Behind a Reverse Proxy (Nginx/Traefik)

Example Nginx configuration:

server {
    listen 80;
    server_name yourdomain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

📊 Health Checks

The container includes a health check endpoint:

# Check container health
docker inspect --format='{{.State.Health.Status}}' localmind-app

# Manual health check
curl http://localhost:3000/health

🎯 Performance Optimization

Multi-stage Build Benefits

The Dockerfile uses multi-stage builds to:

Reduce final image size by ~60%
Separate build and runtime dependencies
Improve build caching

Image Size Comparison

Without optimization: ~800MB
With multi-stage build: ~300MB

Build with BuildKit (faster builds)

DOCKER_BUILDKIT=1 docker build -t localmind:latest .

🆘 Getting Help

If you encounter issues:

Check logs: docker logs localmind-app
Verify environment: docker exec localmind-app env
Open an issue: GitHub Issues
Community support: [Discord/Forum link]

📝 Additional Resources

🎉 You're all set! Your LocalMind instance is now running in Docker.

📝 Changelog

[v1.0.0] - 2024-01-15

Added

🎉 Initial release of LocalMind
🧠 Support for Ollama local models
☁️ Cloud AI integrations (Gemini, OpenAI, Groq, RouterAI)
📚 RAG with Excel/CSV uploads
🌐 LocalTunnel and Ngrok support
🔐 JWT authentication
💬 Real-time chat interface
📊 Usage analytics
🎨 Modern React UI with Tailwind CSS

Security

Implemented bcrypt password hashing
Added CORS protection
Rate limiting for API endpoints
Input validation and sanitization

Made with ⚡ by NexGenStudioDev

Back to top ↑

Name		Name	Last commit message	Last commit date
Latest commit History 48 Commits
.github		.github
.husky		.husky
.vscode		.vscode
LocalMind-Backend		LocalMind-Backend
LocalMind-Frontend		LocalMind-Frontend
assets		assets
.dockerignore		.dockerignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
Contributing.md		Contributing.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
contributing.md		contributing.md
docker-compose.separate.yml		docker-compose.separate.yml
docker-compose.yml		docker-compose.yml
dockerfile.md		dockerfile.md
env.example		env.example
package-lock.json		package-lock.json
package.json		package.json

License

kraayush952-dotcom/LocalMind

Folders and files

Latest commit

History

Repository files navigation

LocalMind — AI Without Limits

📖 Table of Contents

🔥 Overview

Why LocalMind?

Perfect For

✨ Features

🧠 AI Model Support

🖥️ Local Models (via Ollama)

☁️ Cloud Models

📚 RAG: Train with Your Own Data

Supported Formats

How It Works

Use Cases

🌐 Global AI Sharing

Exposure Methods

Benefits

Security Features

🔒 Privacy & Security

Privacy Guarantees

Security Features

🚀 Quick Start

📦 Installation Guide

Prerequisites

Verify Installation

1. Backend Setup

Available Scripts

2. Frontend Setup

Available Scripts

3. Docker (Recommended for Production)

Prerequisites

Quick Start with Docker Compose

Using Separate Services (Advanced)

Docker Commands Reference

Docker Features

Troubleshooting Docker

⚙️ Configuration

Environment Variables

Frontend Configuration

🔧 Code Quality & Linting

Setup

Available Commands

Backend

Frontend

Root (Run for both)

Pre-commit Hooks

Editor Integration (VS Code)

Configuration Files

Rules & Standards

📁 Project Structure

🧩 API Documentation

Base URL

Authentication

🔐 Authentication & User Management

Register User

Login

Get User Profile

Update Profile

⚙️ AI Configuration & API Keys

Generate LocalMind API Key

List API Keys

Delete API Key

Get AI Configuration

Update AI Configuration

💬 Chat & Messaging

Send Message

Stream Message (SSE)

Get Chat History

Create New Conversation

Delete Conversation

📚 File Upload & RAG Training

Upload Excel/CSV

Upload Q&A Dataset

Train Model with Uploaded Data

Get Upload Status