Getting Started

Prerequisites

Node.js 20+ and pnpm 9+
Python 3.11+
Docker and Docker Compose (for databases)

Installation

1. Clone the Repository

git clone https://github.com/AgentaFlow/agentbase.git
cd agentbase

2. Install Dependencies

pnpm install

3. Environment Configuration

Copy the root environment file and the frontend environment file:

cp .env.example .env
cp packages/frontend/.env.example packages/frontend/.env.local

Key variables to set in .env:

Variable	Description	Default
`OPENAI_API_KEY`	OpenAI API key for GPT models (platform key, optional for BYOK)	—
`ANTHROPIC_API_KEY`	Anthropic API key for Claude (platform key, optional for BYOK)	—
`GEMINI_API_KEY`	Google Gemini API key (platform key, optional for BYOK)	—
`HUGGINGFACE_API_KEY`	HuggingFace Inference API key (platform key, optional for BYOK)	—
`ENCRYPTION_KEY`	64-hex-char key for encrypting user BYOK provider keys at rest	—
`JWT_SECRET`	Secret for signing JWT tokens	`CHANGE_ME...`
`JWT_REFRESH_SECRET`	Secret for refresh tokens	`CHANGE_ME...`
`POSTGRES_PASSWORD`	PostgreSQL password	`agentbase_dev`
`REDIS_PASSWORD`	Redis password	`agentbase_dev`

Generating ENCRYPTION_KEY: run node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" — store the output securely and never rotate it without first re-encrypting all saved provider keys.

See Self-Hosting Guide for the full list of environment variables.

4. Start Infrastructure

docker compose up -d

This starts PostgreSQL, MongoDB, and Redis.

5. Run Migrations

pnpm db:migrate

6. Start Development Servers

pnpm dev

This starts all three services concurrently (core, frontend, ai-service).

First Steps

Open http://localhost:3000 (opens in a new tab) and register an account
Create your first AI application
Try a conversation in the chat interface
Browse the plugin marketplace
Customize themes in the dashboard

Next Steps

Plugin Development — extend the platform
Theme Development — customize the look
API Reference — integrate via REST APIs

Introduction Self-Hosting Guide