How to Set Up a Development Environment for PentAGI: Complete Guide

Install Docker, Go 1.22+, and Node 20+, then clone the vxcontrol/pentagi repository, run go mod download in backend/, npm ci in frontend/, configure your .env file with an LLM API key, and launch with ./installer or docker compose up -d to access the UI at https://localhost:8443.

Setting up a PentAGI development environment requires configuring three integrated layers: a Go backend that compiles to the pentagi binary, a React/TypeScript frontend, and a Docker-based sandbox for isolated tool execution. This guide walks through the exact commands and configuration files—referencing specific paths like backend/pkg/config/config.go and docker-compose.yml—to get a local instance running for development or contribution.

Prerequisites

Before cloning the repository, ensure your workstation meets the following requirements. PentAGI runs its agents inside containers and compiles native code for the API server and UI.

• Docker (or Podman with podman-compose) for container orchestration
• Go 1.22 or later for backend compilation
• Node.js 20 or later with npm for frontend builds
• Git and optionally make for task automation
• At least 4 CPU cores and 8 GB RAM (16 GB recommended for running multiple agents)

Clone the Repository and Install Dependencies

Start by cloning the monorepo and installing language-specific dependencies. The repository structure separates backend and frontend code, each with distinct package managers.

Backend Setup

Navigate to the backend/ directory and download Go modules. The source code in backend/README.md specifies these exact commands at line 44.

cd backend
go mod download
go build -trimpath -o pentagi ./cmd/pentagi

This produces the pentagi executable used by the interactive installer and CI pipelines. The -trimpath flag ensures reproducible builds across different developer machines.

Frontend Setup

Move to the frontend/ directory to install Node dependencies. As documented in frontend/README.md at line 2, use npm ci to guarantee a reproducible install locked to the project's package-lock.json.

cd ../frontend
npm ci

Optionally start the development server with npm run dev to verify the Vite configuration loads correctly on http://localhost:8000.

Configure Environment Variables

PentAGI requires environment variables for LLM API keys, database credentials, and network settings. The backend reads these via the configuration loader defined in backend/pkg/config/config.go.

Copy the example template and edit the resulting .env file:

cp .env.example .env

Edit .env to add at least one LLM provider key. The system supports multiple providers:

• OPEN_AI_KEY for OpenAI GPT models
• ANTHROPIC_API_KEY for Claude models
• GEMINI_API_KEY for Google Gemini

The .env.example file at the repository root serves as the authoritative source of default values and available options.

Launch the Development Stack

You can start PentAGI using the interactive installer for guided setup, or manually with Docker Compose for granular control.

Option 1: Interactive Installer (Recommended)

The ./installer script, referenced in the Quick Start section of README.md (lines 55-61), validates Docker availability, pulls required images, writes a fully populated .env if needed, and orchestrates the stack.

chmod +x installer
./installer

Follow the wizard prompts to select which optional stacks (observability, knowledge graph) to enable.

Option 2: Manual Docker Compose

For manual control, start the core services defined in docker-compose.yml:

docker compose up -d

Add optional stacks by specifying additional compose files:

docker compose -f docker-compose-observability.yml up -d   # Prometheus/Grafana/Loki

docker compose -f docker-compose-graphiti.yml up -d      # Neo4j knowledge graph

If using Podman, substitute podman-compose for docker compose. The repository includes specific guidance for rootless Podman configurations in the README (lines 333-380), requiring minor port adjustments for the scraper service.

Verify the Installation

Confirm the stack is healthy by accessing the web interface and running the test suites.

Access the UI

Open https://localhost:8443 in your browser. Log in with the default administrator credentials:

• Username: admin@pentagi.com
• Password: admin

Successful login confirms the React frontend can communicate with the Go backend via GraphQL/REST endpoints.

Run Test Suites

Validate your environment before making code changes. From the repository root, execute backend unit tests:

go test ./...

For frontend validation, run from the frontend/ directory as specified in frontend/README.md (line 8):

npm run test

Passing tests indicate that Go modules, Node dependencies, and environment variables are correctly configured.

Key Files for Development Reference

When extending PentAGI, you will frequently consult these authoritative source locations:

File	Purpose
backend/pkg/config/config.go	Environment variable mapping and struct definitions
docker-compose.yml	Core service orchestration (API server, Postgres, Grafana)
scripts/entrypoint.sh	Container initialization logic
backend/docs/docker.md	Docker client implementation details for agent sandboxing
examples/guides/worker_node.md	Architecture guide for isolated worker nodes

Summary

• Install Docker, Go 1.22+, and Node 20+ on your workstation.
• Clone vxcontrol/pentagi and run go mod download in backend/ plus npm ci in frontend/.
• Configure .env from .env.example, adding at least one LLM API key (OpenAI, Anthropic, or Gemini).
• Launch using ./installer for automated setup or docker compose up -d for manual control.
• Verify by accessing https://localhost:8443 with admin@pentagi.com / admin and running go test ./... and npm run test.

Frequently Asked Questions

Do I need GPU support for local development?

No. PentAGI uses external LLM APIs (OpenAI, Anthropic, Gemini) rather than local model inference, so GPU acceleration is not required for the development environment. CPU-only machines run the Docker containers and agent sandboxes efficiently.

Can I use Podman instead of Docker?

Yes. The repository supports rootless Podman as documented in README.md (lines 333-380). Use podman-compose up -d instead of docker compose up -d, and apply the non-privileged port mappings for the scraper service described in that section.

What if the installer fails to detect my LLM API key?

The installer validates that at least one provider key exists in .env. If detection fails, manually ensure your key is uncommented and properly formatted (e.g., OPEN_AI_KEY=sk-... without quotes or spaces). The configuration loader in backend/pkg/config/config.go requires these variables to be non-empty for the backend to start.

How do I run only the backend for API development?

Start the infrastructure containers (Postgres, Neo4j) with docker compose up -d postgres neo4j, then run the Go binary directly with go run ./cmd/pentagi from the backend/ directory. This bypasses the frontend container and allows hot-reloading during API development.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}