Installation & setup

ContextMint has two user-facing components: Engine (desktop operator console + Python server) and the VS Code extension (chat, Context Lens, governance UI). The default path is local-first on one machine. Stuck during setup? Jump to installation support — your first line of help before contacting us.

Prerequisites

  • Windows 10+, macOS 12+, or Linux x64
  • VS Code 1.85 or later
  • Ollama for local model inference (Engine first-run wizard can link to install)
  • Enough disk for embeddings (rough guide: 1–3 GB per medium-sized repo)
  • Network loopback to localhost:8000 (default API port)

Local-first install (recommended)

  1. Download and install ContextMint Engine from releases.
  2. Open Engine from the system tray → run Start all (server + Ollama).
  3. Install the ContextMint extension from the VSIX or marketplace.
  4. Open your project folder in VS Code — the extension registers the workspace automatically.
  5. Wait for readiness to move past Offline / Starting; indexing may continue in the background.

Quick walkthrough: Getting started (5 min). Engine's first-run wizard also links here when something fails.

First-run wizard (Engine)

On first launch, Engine may prompt for:

  • Python / backend path (usually auto-detected in packaged builds)
  • Ollama URL and default embed + chat models
  • Whether to start server and Ollama on login (optional autostart)

Complete the wizard before expecting chat to reach Ready or Limited. Each wizard step includes an Installation help link to this page.

Workspace registration

Each opened folder gets a stable workspace ID (12-char hex). The extension calls POST /set-workspace with the folder path and open editor paths so indexing can prioritize files you are editing. You do not configure this manually in normal use.

Sovereign on-prem server (enterprise pilot)

Platform teams may deploy the API stack on an internal host with OpenAI-compatible inference (typically vLLM) — not only “shared Ollama.” Developers point the extension at that URL:

  • ContextMint.serverUrl — team API base (HTTPS)
  • ContextMint.enterpriseMode — enable when server auth is required
  • OIDC / JWT configuration per your IdP

The extension does not start Engine in this mode. Repo paths must align (Remote SSH or mounted volumes). Full detail: Sovereign server deployment, BYOK & enterprise, and Trust & Security.

Verify install

  • Engine → Overview shows server Running
  • VS Code status bar: ContextMint | Ready (or Indexing / Limited)
  • Browser: http://localhost:8000/api/health returns OK (local-first)

Installation support (first line)

Use this section when setup does not match the happy path above. Work through the symptom that matches what you see in Engine or VS Code. Only after these steps should you export a support bundle and email anis@contextmint.ai.

Decision guide

  1. Engine tray missing? → Check tray overflow; relaunch Engine from Start menu.
  2. Start all fails? → Logs tab + port 8000 conflict → restart machine → reinstall Engine bundle.
  3. Extension shows Offline? → Engine not running or wrong serverUrl.
  4. Stuck on Starting in VS Code? → Reload window; Engine → Server → restart server.
  5. Limited / Ollama offline? → Install Ollama; Engine → Ollama → Start; pull models in Models tab.
  6. Indexing errors? → Engine → Indexing drill-down; fix permissions; reindex workspace.

Engine & server

“Start all” does nothing or fails immediately

Try:

  1. Engine → Logs — look for Python traceback or “address already in use”.
  2. Stop all → quit Engine → ensure no stray contextmint / python process on port 8000.
  3. Engine → Settings — confirm backend path points at the bundled server (packaged install).
  4. Reinstall the latest Engine release if the server binary is missing.

Still blocked? Engine troubleshooting · export bundle from About.

Health URL does not load in browser

Try: Engine → Overview → confirm server Running. Use the exact URL from Settings (default http://127.0.0.1:8000). Disable VPN/proxy blocking loopback. On shared-server mode, use your team HTTPS URL instead.

Ollama & models

Ollama not detected / Limited mode in VS Code

Try:

  1. Install from ollama.com/download.
  2. Engine → Ollama → Start or Restart.
  3. Engine → Models → pull recommended embed + chat models.
  4. Start all again; wait for Overview readiness to clear Ollama warnings.
Models pulled but chat still errors

Try: Confirm model names in Engine Models match server defaults. Restart server after changing embed model (may require reindex). Test with a short “hi” message in Ask mode.

VS Code extension

Extension installed but no ContextMint icon

Try: Enable extension in Extensions panel. Reload window. Check Output → ContextMint for activation errors. Confirm VS Code ≥ 1.85.

Chat blocked — “server offline” or “starting”

Try:

  1. Engine → Start all (local-first).
  2. Settings → ContextMint.serverUrl must match Engine (usually http://localhost:8000).
  3. Reload VS Code window after server is healthy.

Note: Indexing does not block chat — only offline/starting/error do.

Enterprise shared server — 401 or path errors

Try: Enable enterpriseMode, re-auth SSO, align repo paths with server (Remote SSH). See BYOK & enterprise.

Indexing during install

Indexing stuck at 0% or shows errors

Try: Engine → Indexing → open workspace drill-down. Check disk space and read permissions. Exclude huge folders via .gitignore / .contextmintignore. Manual reindex from Overview workspace card.

When to escalate

  1. Engine → About → Download support bundle (or Logs tab).
  2. Note Engine version, OS, and steps you already tried from this page.
  3. Email anis@contextmint.ai or open GitHub issue for release builds.
  4. Design partners: use your named engineering channel.

Broader symptom index: Full troubleshooting · All user docs · Support home