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

> Set up your Pentagi development environment quickly. Follow this guide to install dependencies, clone the repo, configure LLM keys, and launch Pentagi for AI development.

- Repository: [VXControl/pentagi](https://github.com/vxcontrol/pentagi)
- Tags: getting-started
- Published: 2026-03-21

---

**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`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/config/config.go) and [`docker-compose.yml`](https://github.com/vxcontrol/pentagi/blob/main/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`](https://github.com/vxcontrol/pentagi/blob/main/backend/README.md) specifies these exact commands at line 44.

```bash
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`](https://github.com/vxcontrol/pentagi/blob/main/frontend/README.md) at line 2, use `npm ci` to guarantee a reproducible install locked to the project's [`package-lock.json`](https://github.com/vxcontrol/pentagi/blob/main/package-lock.json).

```bash
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`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/config/config.go).

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

```bash
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`](https://github.com/vxcontrol/pentagi/blob/main/README.md) (lines 55-61), validates Docker availability, pulls required images, writes a fully populated `.env` if needed, and orchestrates the stack.

```bash
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`](https://github.com/vxcontrol/pentagi/blob/main/docker-compose.yml):

```bash
docker compose up -d

```

Add optional stacks by specifying additional compose files:

```bash
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:

```bash
go test ./...

```

For frontend validation, run from the `frontend/` directory as specified in [`frontend/README.md`](https://github.com/vxcontrol/pentagi/blob/main/frontend/README.md) (line 8):

```bash
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`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/config/config.go) | Environment variable mapping and struct definitions |
| [`docker-compose.yml`](https://github.com/vxcontrol/pentagi/blob/main/docker-compose.yml) | Core service orchestration (API server, Postgres, Grafana) |
| [`scripts/entrypoint.sh`](https://github.com/vxcontrol/pentagi/blob/main/scripts/entrypoint.sh) | Container initialization logic |
| [`backend/docs/docker.md`](https://github.com/vxcontrol/pentagi/blob/main/backend/docs/docker.md) | Docker client implementation details for agent sandboxing |
| [`examples/guides/worker_node.md`](https://github.com/vxcontrol/pentagi/blob/main/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`](https://github.com/vxcontrol/pentagi/blob/main/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`](https://github.com/vxcontrol/pentagi/blob/main/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.