Installation

Installation

Prerequisites

Dependency	Minimum	Notes
Python	3.11+	Required
Node.js	22+	Required
uvx	any	pip install uv — used to run MCP servers
Ollama	any	Optional — for local models only
Docker	any	Optional — for sandbox code execution

The setup script will attempt to install missing prerequisites automatically.

---

Option 1: Quick Setup Script (Recommended)

The automated script clones the repo, installs all dependencies, verifies your environment, and starts both servers.

macOS / Linux:

curl -sSL https://raw.githubusercontent.com/naveenraj-17/synapse-ai/main/setup.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/naveenraj-17/synapse-ai/main/setup.ps1 | iex

Once complete, open http://localhost:3000.

---

Option 2: pip Install

pip install synapse-ai
synapse setup    # interactive setup wizard (API keys, settings)
synapse start    # start backend + frontend, open browser

---

Option 3: Manual Setup

1. Clone the repository

git clone https://github.com/naveenraj-17/synapse-ai
cd synapse-ai

2. Backend

cd backend
python3.11 -m venv venv
source venv/bin/activate          # Windows: venv\Scripts\activate
pip install -r requirements.txt
python3.11 main.py

Backend starts on http://localhost:8765 (default).

3. Frontend

In a separate terminal:

cd frontend
npm install
npm run dev

Frontend starts on http://localhost:3000 (default).

4. Configure

Copy .env.example to .env and set your API keys:

cp .env.example .env
# Edit .env with your LLM API keys

---

Option 4: Docker Compose

git clone https://github.com/naveenraj-17/synapse-ai
cd synapse-ai
docker-compose up

This starts the backend (port 8765) and frontend (port 3000) as separate containers with a shared named volume (synapse-data).

---

Local Models with Ollama

To use local models, install Ollama and pull a model:

ollama pull mistral-nemo   # default model
# or any other model:
ollama pull llama3
ollama pull codellama

Synapse connects to Ollama at http://127.0.0.1:11434 by default. Change via OLLAMA_BASE_URL in .env.

---

Verifying the Install

synapse status    # shows backend/frontend process state

Or visit http://localhost:3000 — you should see the Synapse chat UI.

---

Next Steps

• Configuration — set up API keys and environment variables
• CLI Reference — full synapse command reference
• Agents — create your first agent