DocumentationNeuronAgent Documentation
Documentation Branch: You are viewing documentation for the main branch (3.0.0-devel). Select a branch to view its documentation:
main (3.0.0-devel) - LatestREL2_STABLE (2.0.0) - StableREL1_STABLE (1.0.0) - StableGitHub Repository →

Getting Started with NeuronAgent

Introduction

📌 Branch & Version Selection

NeuronAgent has three branches with different versions. Choose based on your needs:

BranchVersionStatusUse When
main3.0.0-develLatestNew projects, development, latest features (default)
REL2_STABLE2.0.0StableProduction, stable v2.0 features
REL1_STABLE1.0.0StableProduction, maximum stability required

Note: This documentation reflects version 3.0.0-devel from the main branch. For stable releases, use REL2_STABLE (v2.0.0) or REL1_STABLE (v1.0.0). See GitHub repository for branch details.

NeuronAgent is an AI agent runtime system providing REST API and WebSocket endpoints for building autonomous agent applications. It includes:

  • Agent Runtime - Complete state machine for autonomous task execution with persistent memory
  • Multi-Agent Collaboration - Agent-to-agent communication, task delegation, and shared workspaces
  • Workflow Engine - DAG-based workflow execution with human-in-the-loop (HITL) support
  • Long-term Memory - HNSW-based vector search for context retrieval across sessions
  • 20+ Tools - SQL, HTTP, Code, Shell, Browser, Filesystem, Memory, Collaboration, NeuronDB tools, Multimodal
  • Budget & Evaluation - Real-time cost tracking, budget controls, and quality scoring

What you can build: Autonomous AI agents with persistent memory, multi-agent systems, workflow automation, and agentic AI applications - all backed by PostgreSQL.

Choose Your Path

Pick the installation method that best fits your needs:

MethodBest ForTimeDifficulty
Quick StartCreate your first agent with tools and memory10 minutes⭐⭐ Medium
Docker InstallationComplete setup with Docker Compose5 minutes⭐ Easy
Source BuildProduction, custom builds, developers30+ minutes⭐⭐⭐ Advanced

💡 Note: New here? Start with Quick Start to create your first agent. For Docker deployment, use Docker Installation. Production deployments should use Source Build.

Docker Quick Start

Complete NeuronAgent setup running in under 5 minutes with Docker Compose. This method includes NeuronAgent with NeuronDB integration and requires minimal configuration.

Start NeuronAgent with Docker Compose

# Clone repository (main branch = 3.0.0-devel)
git clone https://github.com/neurondb-ai/neurondb.git
cd neurondb

# For stable 1.0.0 release, checkout REL1_STABLE branch:
# git checkout REL1_STABLE

# Start NeuronAgent with NeuronDB
docker compose up -d neuronagent neurondb

# Verify services
docker compose ps

# Check health endpoint
curl -sS http://localhost:8080/health

This starts:

  • NeuronAgent (REST API) on port 8080
  • NeuronDB (PostgreSQL with extension) on port 5433
  • WebSocket support for real-time streaming
  • Background workers for memory promotion and async tasks

Continue to Quick Start guide →

Source Build (Advanced)

For production deployments or custom builds, install from source. This requires Go 1.21+, PostgreSQL 16-18 with NeuronDB extension, and build dependencies.

See the Installation Guide for detailed platform-specific instructions.

Quick reference (Ubuntu/Debian)

# Install dependencies
sudo apt-get install -y postgresql-17 postgresql-server-dev-17 build-essential golang-go

# Clone repository
git clone https://github.com/neurondb-ai/neurondb.git
cd neurondb

# For stable 1.0.0 release, checkout REL1_STABLE branch:
# git checkout REL1_STABLE

# Build NeuronAgent
cd NeuronAgent
go build -o neuronagent ./cmd/server

# Run NeuronAgent
./neuronagent --config configs/config.yaml.example

After building NeuronAgent, configure it to connect to your NeuronDB instance. See the Configuration Guide for details.

Next Steps

After installation, use these guides:

NextQuick Start