Building from Source

​

Prerequisites

​

Backend Requirements

• Go 1.24.1 or later - Download
• GCC/G++ - C compiler for CGO dependencies
• Make - Build automation tool
• Git - Version control

​

Frontend Requirements

• Node.js 23 or later - Download
• npm - Comes with Node.js
• 4GB+ RAM - For Vite build process

​

Docker Image Requirements

• Docker - Install Docker
• 20GB+ free disk space - For build layers and images

​

Building the Backend

​

Quick Build

# Navigate to backend directory
cd backend

# Download dependencies
go mod download

# Build main application
go build -trimpath -o pentagi ./cmd/pentagi

# Build testing utilities
go build -trimpath -o ctester ./cmd/ctester
go build -trimpath -o etester ./cmd/etester
go build -trimpath -o ftester ./cmd/ftester

​

Backend Dependencies

• GraphQL: github.com/99designs/gqlgen v0.17.57 - GraphQL server
• Web Framework: github.com/gin-gonic/gin v1.10.0 - HTTP web framework
• Database: github.com/jackc/pgx/v5 v5.7.2 - PostgreSQL driver
• Docker Client: github.com/docker/docker v28.3.3 - Container management
• AI/LLM: github.com/vxcontrol/langchaingo - LLM integration
• Vector Store: github.com/pgvector/pgvector-go v0.1.1 - pgvector support
• Observability: OpenTelemetry SDKs for metrics, traces, and logs

​

Build Flags

go build -o pentagi ./cmd/pentagi

​

Building the Frontend

​

Quick Build

# Navigate to frontend directory
cd frontend

# Install dependencies
npm ci --include=dev

# Build for production
npm run build

# Output will be in: dist/

​

Frontend Dependencies

• react v19.0.0 - UI library
• react-dom v19.0.0 - React DOM renderer
• typescript v5.6.2 - Type safety
• vite v7.0.0 - Build tool and dev server

• @apollo/client v3.13.8 - GraphQL client
• graphql v16.11.0 - GraphQL implementation
• graphql-ws v6.0.5 - WebSocket subscriptions
• axios v1.13.5 - HTTP client

• @radix-ui/* - Accessible UI components
• lucide-react v0.553.0 - Icon library
• @xterm/xterm v5.5.0 - Terminal emulator
• react-markdown v10.1.0 - Markdown rendering

• @tanstack/react-table v8.21.3 - Table management
• react-hook-form v7.56.4 - Form handling
• zod v3.25.32 - Schema validation

​

Available Scripts

# Development
npm run dev                 # Start dev server
npm run graphql:generate    # Generate GraphQL types

# Production
npm run build              # Build for production

# Testing
npm test                   # Run tests once
npm run test:watch         # Run tests in watch mode
npm run test:coverage      # Generate coverage report

# Code Quality
npm run lint               # Check for linting errors
npm run lint:fix           # Fix linting errors
npm run prettier           # Check formatting
npm run prettier:fix       # Fix formatting

# Utilities
npm run ssl:generate       # Generate SSL certificates

​

Building Docker Images

​

Docker Build Process

1. Frontend Build Stage (fe-build)
   • Base: node:23-slim
   • Builds React frontend with Vite
   • Output: /frontend/dist
2. Backend Build Stage (be-build)
   • Base: golang:1.24-bookworm
   • Builds Go backend and testing tools
   • Output: /pentagi, /ctester, /etester, /ftester
3. Final Runtime Stage
   • Base: alpine:3.23.3
   • Minimal runtime with binaries and static files
   • Non-root user: pentagi

​

Building the Image

# Build from repository root
docker build -t pentagi:latest .

​

Build Optimizations

• Layer Caching: Dependencies are cached separately from source code
• Parallel Builds: Frontend and backend build in parallel stages
• Minimal Runtime: Alpine Linux base (~5MB) for small final image
• Build Cache Mounts: Go modules and npm cache are mounted during build

# Example: Go module cache mount
RUN --mount=type=cache,target=/go/pkg/mod \
    go mod download

# Example: npm cache mount  
RUN --mount=type=cache,target=/root/.npm \
    npm ci --include=dev

​

Image Structure

/opt/pentagi/
├── bin/
│   ├── pentagi          # Main application
│   ├── ctester          # Provider compatibility tester
│   ├── etester          # Embedding tester
│   ├── ftester          # Function tester
│   └── entrypoint.sh    # Startup script
├── fe/                  # Frontend static files
├── conf/                # Provider config examples
├── ssl/                 # SSL certificates (generated)
├── logs/                # Application logs
├── data/                # Persistent data
├── LICENSE
├── NOTICE
└── EULA

​

Entrypoint Script

1. Checks for existing SSL certificates
2. Generates self-signed certificates if needed
3. Sets proper file permissions
4. Launches the PentAGI application

​

Build Troubleshooting

​

Backend Build Issues

# Clear module cache and retry
go clean -modcache
go mod download
go build -o pentagi ./cmd/pentagi

# Install musl-dev for CGO support
apk add musl-dev gcc g++

# Or disable CGO entirely
CGO_ENABLED=0 go build -o pentagi ./cmd/pentagi

# Use parallel builds
go build -p 4 -o pentagi ./cmd/pentagi

# Or use cache
go build -o pentagi ./cmd/pentagi

​

Frontend Build Issues

# Increase Node.js memory limit
export NODE_OPTIONS="--max-old-space-size=8192"
npm run build

# Regenerate GraphQL types
npm run graphql:generate

# Then rebuild
npm run build

# Clean install
rm -rf node_modules package-lock.json
npm install
npm run build

​

Docker Build Issues

# Build with increased memory
docker build \
  --build-arg NODE_OPTIONS="--max-old-space-size=8192" \
  -t pentagi:latest .

# Ensure Docker daemon is running
sudo systemctl start docker

# Or add user to docker group
sudo usermod -aG docker $USER
newgrp docker

# Build without cache
docker build --no-cache -t pentagi:latest .

​

Next Steps

• Run tests to verify your build
• Set up your development environment
• Learn about the architecture
• Deploy with Docker Compose