Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Quick Start

Get NeuAIs running in 3 simple steps

This guide will get you up and running with both Observatory (3D visualization) and Perfection (automation system).

Prerequisites

Required:

  • Python 3.9+ (for local web server)
  • Web Browser (Chrome 90+, Firefox 88+, Edge 90+)

Optional (for full platform):

  • Rust 1.70+ (for IDE and Git tools)
  • Go 1.21+ (for services and Perfection)
  • Node.js 20+ (for dashboard and tools)
  • PostgreSQL 14+ (for IDE/Git data storage)

Launch the 3D visualization interface in 30 seconds:

Step 1: Navigate to Observatory

cd neuais.com/hub.neuais.com/observatory.neuais.com

Step 2: Start Web Server

python3 -m http.server 3000

Step 3: Open in Browser

Visit: http://localhost:3000/start.html

What you’ll see:

  • Beautiful landing page with animated starfield
  • “Launch Observatory” button
  • 3D constellation of agents, services, and infrastructure
  • Interactive controls (drag, zoom, click)

Alternative: Perfection Automation

Generate complete systems from CSV manifests:

Step 1: Navigate to Automation

cd neuais.com/automation

Step 2: Generate System

./cli/perfection generate manifest/neuais-complete.csv

This creates:

  • 19 backend services (Go HTTP + gRPC)
  • 9 AI agents (Rust + Go with GPT-4/Claude)
  • 3 infrastructure configs (PostgreSQL, Redis, Consul)
  • 7 frontend components (React/TypeScript)
  • 6 documentation files (MkDocs)

Generation time: ~10 seconds
Output location: automation/generated/

Step 3: View in Control Panel

cd frontend/dashboard
node server.js

Visit: http://localhost:3002

Full Platform Setup (Optional)

For complete development environment with IDE and Git tools:

1. Build Development Tools

First time only - compiles Rust binaries (5-15 minutes):

cd neuais.com/automation
./build-tools.sh

This compiles:

  • NeuAIs IDE (Lapdev) - Web-based IDE with terminal, LSP, extensions
  • NeuAIs Git (GitArena) - Self-hosted Git with issues and code review

2. Setup PostgreSQL

Required for IDE and Git tools:

# Install PostgreSQL (if not already installed)
# Ubuntu/Debian:
sudo apt install postgresql

# macOS:
brew install postgresql
brew services start postgresql

# Create database
./automation/setup-postgres.sh

3. Start All Services

cd neuais.com/automation
./start-all.sh

This starts:

  • Control Panel Dashboard (port 3002)
  • NeuAIs IDE (port 3001)
  • NeuAIs Git (port 3000)

Access Points

Primary Applications

ApplicationURLPurpose
Observatoryhttp://localhost:3000/start.html3D visualization ⭐
Control Panelhttp://localhost:3002Manage services/agents
IDEhttp://localhost:3001Code editor
Githttp://localhost:3000Repository management

Documentation

ResourceURLDescription
External Docshttps://docs.neuais.comPublic documentation
Internal Docsdocs-internal/README.mdInternal guides
Observatory Docshub.neuais.com/observatory.neuais.com/README.mdObservatory guide

What You Can Do

In Observatory (3D View)

  1. Explore the system - Drag to rotate, scroll to zoom
  2. Click nodes - View detailed information cards
  3. Use the dock - Hover at bottom for tools
  4. Customize visuals - Change colors and shapes
  5. View metrics - Real-time performance data
  6. Access terminal - Execute commands
  7. Capture screenshots - Save visualization as PNG

In Control Panel (Dashboard)

  1. View all components - Services, agents, docs in cards
  2. Start/stop services - Click “Start” on any service or agent
  3. View code - Click “Code” to open in IDE
  4. Read documentation - Click on documentation cards
  5. Access tools - Quick links to IDE and Git

Usage Workflows

Observatory Workflow

Typical user flow:

  1. Open Observatory → See 3D visualization
  2. Explore nodes → Click for details
  3. Check metrics → Open metrics card
  4. View topology → See connections
  5. Customize → Adjust colors/shapes
  6. Monitor → Watch real-time updates

Automation Workflow

Development flow:

  1. Edit CSV manifest → Define services/agents
  2. Run ./cli/perfection generate → Generate code
  3. Open Control Panel → View all components
  4. Click “Start” → Launch services/agents
  5. Click “Code” → Edit in NeuAIs IDE
  6. Commit → Push via NeuAIs Git
  7. Deploy → Services auto-connect

Scaling Workflow

For 1000+ agents:

Same workflow, scales automatically:

  • Manifest with 1000 entries
  • Control Panel shows all 1000
  • Observatory visualizes all
  • Start/stop individually or in groups
  • No architectural changes needed

Troubleshooting

Port already in use

# Find what's using the port
lsof -i :3002  # or :3001, :3000

# Kill it
kill <PID>

Build fails

# Update Rust
rustup update

# Clean build
cd neuais.com/tools/ide/lapdev-lapdev-cli
cargo clean
cargo build --release -p lapdev-ws

Dashboard shows no data

# Regenerate manifest
cd neuais.com/automation
./cli/perfection generate manifest/neuais-complete.csv

# Check manifest exists
ls -lh frontend/dashboard/generated.manifest.json

IDE/Git won’t start

# Check if binaries exist
ls neuais.com/tools/ide/lapdev-lapdev-cli/target/release/lapdev-ws
ls neuais.com/tools/git/gitarena/target/release/gitarena

# If missing, rebuild
./build-tools.sh

Database connection fails

# Check PostgreSQL is running
systemctl status postgresql

# Or
brew services list | grep postgresql

# Create database if needed
./automation/setup-postgres.sh

Configuration

Observatory Settings

Location: Browser localStorage (automatic)

Customizable:

  • Colors and shapes
  • Particle effects
  • Auto-rotation
  • Quality settings

Reset: Customize card → “Reset to Default”

Perfection Configuration

Config files:

  • config/dev.toml - Development
  • config/prod.toml - Production
  • config/staging.toml - Staging

Environment variables:

export NEUAIS_ENV=dev
export NEUAIS_LOG_LEVEL=debug
export NEUAIS_API_URL=http://localhost:8080

Next Steps

Learn More

Documentation:

External Docs:

Try These

Observatory:

  1. Click the “Customize” icon in dock
  2. Change agent colors to purple
  3. Enable/disable particle flows
  4. Take a screenshot

Automation:

  1. Edit manifest/neuais-complete.csv
  2. Add a new agent
  3. Regenerate with Perfection
  4. View in Control Panel

Support

Documentation:

  • Internal: docs-internal/
  • External: https://docs.neuais.com
  • Observatory: hub.neuais.com/observatory.neuais.com/README.md

Logs:

  • Automation: automation/logs/
  • Services: automation/generated/services/*/logs/
  • Browser: F12 Developer Console

Community:

  • GitHub Issues: https://github.com/neuais/platform/issues
  • Discussions: https://github.com/neuais/platform/discussions

Last updated: December 12, 2025