Installation¶

You're installing the harness for AI agents - a 26 MB Go binary that brokers tool calls, scores memory, and persists context across sessions.

Neuralgentics provides three primary installation paths depending on your environment and trust level.

🛠️ Installation Flow¶

                                  START
                                     │
                                     ▼
                      ╔══════════════════════════╗
                      ║    FRESH VS UPGRADE?     ║
                      ╚══════════════════════════╝
                                     │
             ┌─────────────────────┴─────────────────────┐
             ▼                                            ▼
      [ FRESH INSTALL ]                           [ EXISTING INSTALL ]
             │                                            │
             ▼                                            ▼
    ╔══════════════════════╗                    ╔══════════════════════╗
    ║   CHOOSE METHOD      ║                    ║    RUN INSTALLER     ║
    ╚══════════════════════╝                    ╚══════════════════════╝
             │                                            │
     ┌───────┴───────┬──────────────────┐                  │
     ▼               ▼                    ▼                  ▼
╔══════════╗ ╔══════════════╗ ╔══════════════╗        [ VERSION BUMP ]
║ BINARY   ║ ║ CONTAINER    ║ ║ FROM SOURCE  ║               │
╚══════════╝ ╚══════════════╝ ╚══════════════╝               │
     │               │                    │                  │
     └───────────────┴──────────┬─────────┘                  │
                                 ▼                           │
                      ╔══════════════════════╗               │
                      ║  VERIFY VIA 'ping'   ║ $\longleftarrow$  ┘
                      ╚══════════════════════╝
                                 │
                                 ▼
                          [ SYSTEM READY ]

Diagram 10 — Install Flow Decision Tree. This flowchart helps you determine the best way to deploy Neuralgentics. For most users, the binary installer is recommended. Developers should use the source build to ensure local tool-chain alignment.

📦 Option 1: Binary Release (Recommended)¶

This is the fastest way to get started. We provide pre-built binaries for Linux, macOS, and Windows.

Steps¶

1. Run the installer:

   curl -fsSL https://raw.githubusercontent.com/Veedubin/neuralgentics/main/scripts/install.sh | bash
   

2. Verify the install:

   neuralgentics status
   

Customization¶

The installer defaults to a project-local install at $PWD/.neuralgentics — binaries, data, and the projects registry all live inside your project, so the install never touches $HOME unless you ask. curl ... | bash (no flags) installs silently with all defaults; no prompts, ever. For non-default behavior, pass flags:

# Global install to $HOME/.neuralgentics with a symlink in ~/.local/bin
curl -fsSL .../install.sh | bash -s -- --home-dir

# Custom absolute path
curl -fsSL .../install.sh | bash -s -- --prefix /opt/neuralgentics

# Use an existing database instead of creating a new container
# (drop a .env in $PWD/.neuralgentics/ with the 5 required keys first)
curl -fsSL .../install.sh | bash -s -- --existing

# Use a sample .env template shipped in the repo
cp scripts/.env.example .neuralgentics/.env
$EDITOR .neuralgentics/.env   # fill in POSTGRES_PASSWORD
curl -fsSL .../install.sh | bash -s -- --existing

# Combine: global install + existing database
curl -fsSL .../install.sh | bash -s -- --home-dir --existing

# Interactive (TTY only): prompts for the install location
curl -fsSL .../install.sh -o install.sh
bash install.sh

Environment variables are also honored: NONINTERACTIVE=1 (same as --yes), NEURALGENTICS_PREFIX (same as --prefix).

🐳 Option 2: Containerized (Podman/Docker)¶

Ideal for isolated development or CI environments.

Steps¶

1. Ensure Podman or Docker is installed.
2. Clone the repo (or download compose files from the latest release):

   git clone https://github.com/Veedubin/neuralgentics.git
   cd neuralgentics
   

3. Copy the example env file:

   cp compose.example.env .env
   $EDITOR .env  # set NEURALGENTICS_DB_PASSWORD
   

4. Spin up the stack:

   docker compose up -d
   # or
   podman-compose up -d
   

5. Verify the stack is up:

   docker compose ps
   

This brings up PostgreSQL 18 + pgvector, the embedding sidecar, the Go backend, and the TUI (commented out by default; uncomment in docker-compose.yml to enable).

Users can browse and activate from a curated catalog of populares MCP servers using the /catalog command in the TUI.

Images are published to ghcr.io/veedubin/neuralgentics-{postgres,sidecar,backend,tui}:vX.Y.Z.

💻 Option 3: Build From Source¶

Required for contributors or those modifying the core Go/Python logic.

1. Prerequisites:
2. Go 1.22+
3. Python 3.12+
4. Node.js 20+
5. PostgreSQL with pgvector extension
6. Build the backend:

   make build
   

7. Initialize the TUI overlay:

   cd overlay/packages/opencode
   npm install && npm run build
   

⚠️ Special Environments¶

WSL / WSL2 Support¶

Neuralgentics fully supports Windows Subsystem for Linux. - ** Detection: The installer automatically detects WSL and provides specific path warnings. - Recommendation: Always install to ~/.local/bin inside the Linux distro. Do not** attempt to call Linux binaries from the Windows CMD/PowerShell prompt unless using wslpath.

Upgrade Paths¶

To upgrade an existing installation to the latest version:

curl -fsSL https://raw.githubusercontent.com/Veedubin/neuralgentics/main/scripts/install.sh | bash