Installation

This page walks you through cloning HypLab, setting up environment variables, and starting all services. By the end, you will have HypLab running on your machine.

Step 1: Clone the repository

Open a terminal and run:

git clone https://github.com/hyplabAI/hyplab.git
cd hyplab

This downloads the entire HypLab codebase to a folder called hyplab.

Step 2: Run the setup command

If you have make installed (recommended):

make setup

What make setup does under the hood:

Installs Node.js dependencies for the API (api/) and frontend (app/)
Compiles translation files (PO to JSON) for the frontend
Installs Python dependencies for the AI agents (agents/)
Copies example .env files if they don't exist yet
Pulls and builds Docker images for MongoDB, Redis, and the application services

If you don't have make, you can run each step manually:

# Install API dependencies
cd api && npm install && cd ..

# Install frontend dependencies
cd app && npm install && npm run i18n:convert && cd ..

# Install AI agent dependencies
cd agents && pip install -e . && cp .env.example .env && cd ..

Step 3: Configure environment variables

HypLab uses .env files to configure each service. The setup command creates these from example files, but you should review them.

Backend (`api/.env`)

PORT=4096
NODE_ENV=development
MONGODB_URL=mongodb://localhost:27018/hyplab
REDIS_URL=redis://localhost:6380
AI_PROVIDER=mock

AI_PROVIDER=mock means AI features return placeholder data. To use real AI generation, see LLM Setup.

Frontend (`app/.env.local`)

NEXT_PUBLIC_API_URL=http://localhost:4096
NEXT_PUBLIC_TELEMETRY_ENABLED=false

AI Agents (`agents/.env`)

# Add your LLM provider key here
# GEMINI_API_KEY=your-key-here
# Or use OpenAI, Ollama, etc. -- see LLM Setup guide

Step 4: Start the services

make dev

What make dev starts:

Service	Port	What it does
MongoDB	27018	Database for all application data
Redis	6380	Cache and background job queue
API Server	4096	Express.js backend handling all requests
Web Interface	4090	Next.js frontend you interact with
OpenTelemetry Collector	4317/4318	Collects traces (optional, runs automatically)
Jaeger UI	16686	View traces (optional, runs automatically)

If you prefer Docker Compose directly:

docker compose -f docker/docker-compose.yml up --build

What you should see

After running make dev, wait about 30-60 seconds for all services to start. You should see log output from the gateway and web services. The key indicator is seeing messages like:

gateway-1  | Server started on port 4096
web-1      | Ready on http://localhost:4090

If you see errors, don't panic -- check the Troubleshooting page.

Next: Verify and Explore -- confirm everything is working and take a first look around.

Installation

On this page