Docs › Getting Started

Getting Started

Install NeuralCleave, connect a language model, and have your first agent answering messages — on any of the 32 supported platforms — in under five minutes.

Requirements

  • Python 3.12+ — required. Check with python --version.
  • Redis (optional) — powers short-term, TTL-based session memory. Without it, the gateway falls back to in-memory storage.
  • Qdrant (optional) — powers semantic / vector search. Without it, vector memory is disabled.
  • Ollama (optional) — enables fully offline, privacy-mode inference. Any provider API key works as an alternative.
ℹ

Redis and Qdrant are optional. NeuralCleave starts and responds to messages without them — memory capability is reduced but all channels, tools, and the plugin system work normally.

Installation

One-liner (recommended)

bash
# Linux / macOS
curl -fsSL https://neuralcleave.com/install.sh | bash
powershell
# Windows — run in PowerShell
iwr -useb https://neuralcleave.com/install.ps1 | iex

Both scripts detect Python 3.12+, pip-install the package, resolve the entry-point, run neuralcleave init --non-interactive for a zero-prompt first-run, and print next steps.

Via pip

bash
pip install neuralcleave

From source (development)

bash
git clone https://github.com/TheAmitChandra/NeuralCleave.git
cd NeuralCleave
pip install -e ".[dev]"    # installs ruff, pytest, httpx dev deps

Docker (no Python setup)

bash
docker pull ghcr.io/theamitchandra/neuralcleave:latest
docker run -d \
  -p 7432:7432 \
  -v neuralcleave-data:/root/.neuralcleave \
  --name neuralcleave \
  ghcr.io/theamitchandra/neuralcleave:latest

For Docker with Redis and Qdrant, see Deployment.

Guided setup

bash
neuralcleave init

The wizard asks for:

  1. Your agent's name (default: NeuralCleave)
  2. Primary language model + its API key (Anthropic, OpenAI, Gemini, DeepSeek, or Ollama)
  3. First channel to enable (Telegram bot token, Discord token, Slack tokens, etc.)
  4. Optional Redis / Qdrant URLs
  5. Optional voice test

The result is written to ~/.neuralcleave/config.toml. Every key is documented in Configuration.

💡

Run neuralcleave init --non-interactive (or -y) for a zero-prompt setup that writes sane defaults. Useful in scripts or CI.

Start the gateway

bash
# Background daemon (PID written to ~/.neuralcleave/gateway.pid)
neuralcleave start --background

# Foreground — useful during setup; logs stream to stdout
neuralcleave start

# Bind to a custom host/port
neuralcleave start --host 0.0.0.0 --port 7432

The gateway binds to 127.0.0.1:7432 by default. You can verify it's alive:

bash
curl http://localhost:7432/health
# {"status":"ok","version":"2.1.0","agent":"YourAgentName"}

First message

Talk to your agent directly from the terminal:

bash
neuralcleave chat

Or send a message via the REST API:

bash
curl -s -X POST http://localhost:7432/api/v1/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello! Who are you?"}' | python -m json.tool

Once your channel is configured (Telegram, Discord, Slack, etc.), message the bot there — NeuralCleave receives the message through the channel adapter, routes it through the LLM, and replies back on the same platform.

Check status

bash
neuralcleave status

Shows: agent name, primary model, gateway bind address, enabled channels, memory backend status, and long-term memory row count.

Stop the gateway

bash
neuralcleave stop

OS autostart

Register NeuralCleave to start automatically at login:

bash
neuralcleave autostart enable    # writes OS-specific startup entry
neuralcleave autostart status    # check if registered
neuralcleave autostart disable   # remove startup entry

Platform details:

  • Windows — adds HKCU\Software\Microsoft\Windows\CurrentVersion\Run\NeuralCleave
  • macOS — writes ~/Library/LaunchAgents/com.neuralcleave.plist (launchd)
  • Linux — writes ~/.config/systemd/user/neuralcleave.service

Desktop app

A Tauri 2.x desktop app is available for Windows, macOS, and Linux. It bundles the backend as a PyInstaller sidecar — no separate terminal needed.

  • Download from the GitHub Releases page
  • System tray icon for quick access
  • Global hotkey Ctrl+Shift+Space to show / hide the window
  • Single-instance guard — won't launch a second gateway
  • Close-to-tray behaviour — the gateway keeps running when the window is closed

Mobile (PWA)

NeuralCleave serves a Progressive Web App from the gateway at /app. Open it in Safari (iOS) or Chrome (Android) and tap "Add to Home Screen" — no app store required.

bash
# Open on mobile browser while on the same network
http://YOUR_MACHINE_IP:7432/app

The PWA supports offline access (Service Worker cache), Web Push notifications, and the same WebSocket chat protocol as the desktop client.

Next Architecture →