Ingat Setup Guide

Complete installation and configuration guide for all users

This guide covers everything from installation to IDE integration, including the new multi-client remote mode that allows simultaneous UI and IDE usage without database conflicts.

Installation
Quick Start
Multi-Client Setup (Recommended)
IDE Integration
Configuration
Troubleshooting
Advanced Usage

Installation

Prerequisites

Required:

Node.js v18+ or Bun (recommended)
Rust latest stable toolchain
Git

Platform-specific:

Windows: Microsoft Visual C++ Build Tools
macOS: Xcode Command Line Tools (xcode-select --install)
Linux: Build essentials (sudo apt install build-essential libwebkit2gtk-4.0-dev)

Download and Install

Option 1: From Source (Development)

# Clone the repository
git clone https://github.com/sutantodadang/Ingat.git
cd Ingat

# Install frontend dependencies
bun install  # or: npm install

# Build all MCP binaries
cd src-tauri
cargo build --release --bin mcp-stdio --features mcp-server
cargo build --release --bin mcp-bridge --features mcp-server
cargo build --release --bin mcp-service --features mcp-server,tauri-plugin
cd ..

Option 2: Pre-built Installer (Coming Soon)

Download the installer for your platform from the Releases page.

Windows: ingat-setup.exe
macOS: ingat.dmg
Linux: ingat.AppImage or ingat.deb

The installer includes:

Tauri desktop application
All MCP server binaries (mcp-stdio, mcp-bridge, mcp-service)
Helper scripts
Documentation

Quick Start

Single Client Mode (Simplest)

Use this if: You only want to use ONE client at a time (either UI OR an IDE, but not both).

# Just run the UI
bun run dev

# Or use an IDE alone (configure it first - see IDE Integration section)

This mode opens the database directly. It's simple but doesn't support simultaneous access.

Multi-Client Mode (Recommended)

Use this if: You want to use the UI AND your IDE(s) at the same time.

Windows PowerShell:

# Automatic setup
.\start-with-service.ps1

Manual steps:

# 1. Start the service (keep this terminal open)
.\src-tauri\target\release\mcp-service.exe

# 2. In a new terminal, start the UI
bun run dev

# 3. Connect your IDE(s) - see IDE Integration section

What happens:

mcp-service holds the database lock
UI and IDEs connect via HTTP (remote mode)
No database conflicts!

✅ Important (Windsurf/Cascade): If you keep mcp-service running as a background process, configure Windsurf to spawn mcp-stdio. The stdio MCP server will detect the running service and proxy all context operations to it, making “store / retrieve context” reliable.

Multi-Client Setup (Recommended)

Architecture Overview

┌─────────────┐
│  Tauri UI   │────┐
└─────────────┘    │
                   ├───► mcp-service ───► Local Database
┌─────────────┐    │     (Single lock)     (sled)
│  VS Code    │────┤
└─────────────┘    │
                   │
┌─────────────┐    │
│    Zed      │────┘
└─────────────┘

Step 1: Build the Service

If you haven't already:

cd src-tauri
cargo build --release --bin mcp-service --features mcp-server,tauri-plugin
cd ..

Binary location: src-tauri/target/release/mcp-service.exe (Windows) or mcp-service (Unix)

Step 2: Start the Service

Windows:

.\src-tauri\target\release\mcp-service.exe

macOS/Linux:

./src-tauri/target/release/mcp-service

Expected output:

Starting Ingat Backend Service v0.1.0
Initializing application environment...
Data directory: [your data path]
Application initialized successfully
🚀 Ingat Backend Service listening on http://127.0.0.1:3200
📊 Health check: http://127.0.0.1:3200/health
🔌 MCP SSE endpoint: http://127.0.0.1:3200/sse
💾 REST API: http://127.0.0.1:3200/api/*

Verify it's running:

curl http://localhost:3200/health
# Expected: {"status":"healthy","service":"ingat-backend"}

Step 3: Start the UI

In a NEW terminal:

bun run dev

Look for these logs:

[ingat] Checking for mcp-service at 127.0.0.1:3200...
[ingat] ✓ Detected running mcp-service at 127.0.0.1:3200
[ingat] ✓ Using REMOTE MODE - all operations will proxy to the service
[ingat] ✓ No local database lock will be acquired

✅ Success! The UI is now connected to the service.

Step 4: Connect IDEs

Now you can connect any number of IDEs. They will all automatically detect the running service and use remote mode.

See IDE Integration section below.

IDE Integration

Supported IDEs

IDE	Transport	Configuration File	Details
VS Code	stdio	`.vscode/settings.json`	Link
Cursor	stdio	`.cursor/mcp.json`	Link
Windsurf	stdio	`.windsurf/mcp.json`	Link
Sublime Text	stdio	Codeium settings	Link
Zed	SSE	`settings.json`	Link
Claude Desktop	SSE	`claude_desktop_config.json`	Link

VS Code

Requirements: MCP extension

Configuration:

Open your project in VS Code
Create/edit .vscode/settings.json:

{
  "mcp.servers": {
    "ingat": {
      "command": "C:\\path\\to\\ingat\\src-tauri\\target\\release\\mcp-stdio.exe",
      "args": []
    }
  }
}

On macOS/Linux:

{
  "mcp.servers": {
    "ingat": {
      "command": "/path/to/ingat/src-tauri/target/release/mcp-stdio",
      "args": []
    }
  }
}

Restart VS Code or reload window
Open the MCP panel to verify connection

Logs: Check Output panel > Select "MCP" from dropdown

Windsurf

This is the recommended setup when you want Windsurf (Cascade) to store and retrieve Ingat context while mcp-service is already running.

Prerequisite: Start mcp-service first (background or separate terminal).

Configure Windsurf to run mcp-stdio:

Create/edit .windsurf/mcp.json (path may vary by Windsurf version):

Windows example:

{
  "mcpServers": {
    "ingat": {
      "command": "C:\\path\\to\\ingat\\src-tauri\\target\\release\\mcp-stdio.exe",
      "args": []
    }
  }
}

macOS/Linux example:

{
  "mcpServers": {
    "ingat": {
      "command": "/path/to/ingat/src-tauri/target/release/mcp-stdio",
      "args": []
    }
  }
}

How it works:

mcp-stdio starts and checks http://INGAT_SERVICE_HOST:INGAT_SERVICE_PORT/health
If mcp-service is up, Ingat uses REMOTE MODE and proxies:
- ingest_context → POST /api/contexts
- search_contexts → POST /api/search
- history/projects → GET /api/contexts, GET /api/projects

If the service is not running, mcp-stdio falls back to local mode (which can conflict with other running clients).

Cursor

Requirements: Built-in MCP support (v0.40+)

Configuration:

Create .cursor/mcp.json in your project:

{
  "mcpServers": {
    "ingat": {
      "command": "C:\\path\\to\\ingat\\src-tauri\\target\\release\\mcp-stdio.exe",
      "args": []
    }
  }
}

On macOS/Linux:

{
  "mcpServers": {
    "ingat": {
      "command": "/path/to/ingat/src-tauri/target/release/mcp-stdio",
      "args": []
    }
  }
}

Restart Cursor
Verify connection in MCP panel

Windsurf

Requirements: Built-in MCP support

Configuration:

Create .windsurf/mcp.json in your project:

{
  "mcpServers": {
    "ingat": {
      "command": "C:\\path\\to\\ingat\\src-tauri\\target\\release\\mcp-stdio.exe",
      "args": []
    }
  }
}

Restart Windsurf

Sublime Text

Requirements: Codeium plugin with MCP support

Configuration:

Open Sublime Text
Go to Preferences > Package Settings > Codeium > Settings
Add to your settings:

{
  "mcp_servers": {
    "ingat": {
      "command": "C:\\path\\to\\ingat\\src-tauri\\target\\release\\mcp-stdio.exe",
      "args": []
    }
  }
}

Restart Sublime Text

Zed

Requirements: Zed editor with MCP support

Configuration:

Open Zed settings: Cmd/Ctrl + ,
Add to your settings.json:

{
  "context_servers": {
    "ingat": {
      "settings": {
        "url": "http://localhost:3200"
      }
    }
  }
}

Note: Zed uses SSE transport and connects to mcp-service directly. Make sure the service is running first!

Claude Desktop

Requirements: Claude Desktop app with MCP support

Configuration:

Windows: Edit %APPDATA%\Claude\claude_desktop_config.json
macOS: Edit ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ingat": {
      "url": "http://localhost:3200"
    }
  }
}

Restart Claude Desktop.

Configuration

Environment Variables

You can customize Ingat using environment variables:

# Service host and port
export INGAT_SERVICE_HOST="127.0.0.1"  # Default: 127.0.0.1
export INGAT_SERVICE_PORT="3200"        # Default: 3200

# Custom data directory
export INGAT_DATA_DIR="/custom/path"

# Logging level
export INGAT_LOG="info"  # Options: trace, debug, info, warn, error

# MCP server settings (for mcp-bridge)
export INGAT_MCP_BIND_ADDR="127.0.0.1:5210"
export INGAT_MCP_SSE_PATH="/sse"
export INGAT_MCP_POST_PATH="/message"

Windows PowerShell:

$env:INGAT_SERVICE_PORT = "3200"
$env:INGAT_LOG = "debug"

Data Storage Locations

Default locations:

Windows: %APPDATA%\ingat\Ingat\data
macOS: ~/Library/Application Support/ingat/Ingat/data
Linux: ~/.config/ingat/Ingat/data

Contents:

store/ - Database files (sled)
config.json - User configuration
embeddings/ - Cached embeddings (if using FastEmbed)

Configuration File

Edit config.json in your data directory:

{
  "embedding": {
    "backend": "simple",
    "model": "ingat/simple-hash",
    "dimensions": 384
  },
  "search": {
    "default_limit": 8,
    "max_results": 50
  }
}

Embedding backends:

"simple" - Lightweight deterministic hash (default)
"fastembed" - High-quality semantic embeddings (requires FastEmbed feature)

Troubleshooting

Database Lock Errors

Symptom:

storage failure: failed to open sled db: IO error: could not acquire lock

Cause: Multiple processes trying to open the database directly.

Solution:

Stop everything:

# Windows
Get-Process | Where-Object {$_.ProcessName -match "ingat|mcp"} | Stop-Process -Force

# macOS/Linux
pkill -f "ingat|mcp"

Use multi-client mode:
- Start mcp-service first
- Then start UI and IDEs
- See Multi-Client Setup

Quick fix: .\start-with-service.ps1 (Windows)

Service Won't Start

Symptom: Service exits immediately or shows "could not acquire lock"

Cause: UI or another process has the database open

Solution:

Check for running processes:

# Windows
Get-Process | Where-Object {$_.ProcessName -match "ingat|mcp"}

# macOS/Linux
ps aux | grep -i ingat

Kill all Ingat processes:

# Windows
Get-Process -Name ingat,mcp-* | Stop-Process -Force

# macOS/Linux
killall ingat mcp-stdio mcp-bridge mcp-service

Start service first, THEN UI

IDE Connection Fails

Symptom: VS Code/Cursor shows "Connection state: Error"

Causes & Solutions:

Service not running

# Check service health
curl http://localhost:3200/health

# If fails, start the service
.\src-tauri\target\release\mcp-service.exe

Wrong binary path
- Verify path in IDE config is correct
- Use absolute paths: C:\full\path\to\mcp-stdio.exe

Binary not built

# Rebuild
cd src-tauri
cargo build --release --bin mcp-stdio --features mcp-server

Check IDE logs
- VS Code: Output panel > Select "MCP"
- Look for error messages

UI Uses Local Mode Instead of Remote

Symptom: UI logs show "using local database mode"

Cause: Service isn't running or not accessible

Solution:

Verify service is running:
```
curl http://localhost:3200/health
```
Check for firewall blocking port 3200

Start service manually:

.\src-tauri\target\release\mcp-service.exe

Restart UI - it will detect the service

Port Already in Use

Symptom: "Address already in use: 127.0.0.1:3200"

Cause: Another process is using port 3200

Solution:

Find what's using the port:

# Windows
netstat -ano | findstr :3200

# macOS/Linux
lsof -i :3200

Kill the process or use a different port:

export INGAT_SERVICE_PORT=3201
.\src-tauri\target\release\mcp-service.exe

Binary Not Found

Symptom: IDE can't find mcp-stdio.exe

Solution:

Check file exists:
```
ls src-tauri/target/release/mcp-stdio*
```

Build it:

cd src-tauri
cargo build --release --bin mcp-stdio --features mcp-server

Update IDE config with correct path

Advanced Usage

Remote Service Access

⚠️ Security Warning: Only expose the service over a network with proper security measures!

To allow remote connections:

Bind to all interfaces:

export INGAT_SERVICE_HOST="0.0.0.0"
.\src-tauri\target\release\mcp-service.exe

Set up reverse proxy with TLS (recommended):

nginx example:

server {
    listen 443 ssl;
    server_name ingat.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:3200;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

Configure clients to use remote URL:

export INGAT_SERVICE_HOST="ingat.example.com"
export INGAT_SERVICE_PORT="443"

TODO: Future versions will include authentication and API keys.

Using FastEmbed

For higher quality semantic embeddings:

Build with FastEmbed:

cd src-tauri
cargo build --release --features fastembed-engine,mcp-server,tauri-plugin

Update config: Edit your data directory's config.json:

{
  "embedding": {
    "backend": "fastembed",
    "model": "BAAI/bge-small-en-v1.5",
    "dimensions": 384
  }
}

Restart service/UI

Note: FastEmbed downloads ONNX models (~100MB) on first run.

Running as System Service

Linux (systemd):

Create /etc/systemd/system/ingat-service.service:

[Unit]
Description=Ingat MCP Service
After=network.target

[Service]
Type=simple
User=youruser
ExecStart=/path/to/mcp-service
Restart=on-failure
Environment="INGAT_LOG=info"

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable ingat-service
sudo systemctl start ingat-service
sudo systemctl status ingat-service

macOS (launchd):

Create ~/Library/LaunchAgents/com.ingat.service.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.ingat.service</string>
    <key>ProgramArguments</key>
    <array>
        <string>/path/to/mcp-service</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

Load:

launchctl load ~/Library/LaunchAgents/com.ingat.service.plist

Windows (NSSM):

Download NSSM

Install service:

nssm install ingat-service "C:\path\to\mcp-service.exe"
nssm start ingat-service

Multiple Instances

Run multiple isolated instances with different data directories:

# Instance 1 (default)
INGAT_DATA_DIR=~/.ingat/personal INGAT_SERVICE_PORT=3200 ./mcp-service &

# Instance 2 (work)
INGAT_DATA_DIR=~/.ingat/work INGAT_SERVICE_PORT=3201 ./mcp-service &

Configure clients to point to specific ports.

Helper Scripts

Windows PowerShell

Start everything:

.\start-with-service.ps1

Check service status:

.\scripts\check-service.ps1

Stop service:

.\scripts\stop-service.ps1

Unix/macOS

Check service:

./scripts/check-service.sh

Stop service:

./scripts/stop-service.sh

Getting Help

Documentation

This Guide: Complete setup instructions
START_HERE.md - Quick troubleshooting
QUICK_FIX.md - Fix database lock issues
docs/REMOTE_MODE.md - Technical details on remote mode
MCP_INTEGRATION.md - MCP protocol documentation
IDE_MCP_SETUP.md - IDE-specific guides

Support Channels

🐛 Bug Reports: GitHub Issues
💬 Discussions: GitHub Discussions
📖 Wiki: GitHub Wiki

Common Questions

Q: Can I use the UI without the service?
A: Yes! Just run bun run dev. The UI will use local mode (direct DB access). However, you can't connect IDEs at the same time in local mode.

Q: Do I always need to start the service manually?
A: No. The UI tries to auto-start the service. But if you prefer manual control, start the service first, then the UI will detect it automatically.

Q: Can multiple people use the same service?
A: Yes! Run mcp-service on a shared server and have team members connect their IDEs to it. See Remote Service Access.

Q: Which embedding backend should I use?
A: Start with simple (default). It's fast and works offline. Upgrade to fastembed if you need better semantic search quality.

Q: How do I backup my data?
A: Copy your entire data directory (see Data Storage Locations). The database is in the store/ subdirectory.

Next Steps

✅ Install Ingat - Follow Installation
✅ Run the UI - Use Quick Start
✅ Connect your IDE - See IDE Integration
✅ Enable multi-client - Set up Multi-Client Mode
📖 Read the docs - Explore Documentation

Summary

✅ Single Client: Just run bun run dev (simple, but one client at a time)
✅ Multi-Client: Use mcp-service + UI + IDEs (recommended, no conflicts)
✅ Automatic Detection: Everything detects the service automatically
✅ Zero Config: Default settings work for 99% of users

Get started now with: .\start-with-service.ps1 (Windows) 🚀

Last updated: 2024-11-15

FilesExpand file tree

SETUP_GUIDE.md

Latest commit

History

SETUP_GUIDE.md

File metadata and controls

Ingat Setup Guide

Table of Contents

Installation

Prerequisites

Download and Install

Option 1: From Source (Development)

Option 2: Pre-built Installer (Coming Soon)

Quick Start

Single Client Mode (Simplest)

Multi-Client Mode (Recommended)

Multi-Client Setup (Recommended)

Architecture Overview

Step 1: Build the Service

Step 2: Start the Service

Step 3: Start the UI

Step 4: Connect IDEs

IDE Integration

Supported IDEs

VS Code

Windsurf

Cursor

Windsurf

Sublime Text

Zed

Claude Desktop

Configuration

Environment Variables

Data Storage Locations

Configuration File

Troubleshooting

Database Lock Errors

Service Won't Start

IDE Connection Fails

UI Uses Local Mode Instead of Remote

Port Already in Use

Binary Not Found

Advanced Usage

Remote Service Access

Using FastEmbed

Running as System Service

Multiple Instances

Helper Scripts

Windows PowerShell

Unix/macOS

Getting Help

Documentation

Support Channels

Common Questions

Next Steps

Summary