Skip to main content
Run Proliferate locally for development, testing, or evaluation.

​
Prerequisites

  • Docker Desktop (Mac/Windows) or Docker Engine (Linux)
  • Docker Compose v2+
  • API keys:
    • Anthropic API key (LLM provider)
    • Sandbox provider credentials (Modal or E2B)
    • GitHub App (required for private repos)

​
Quick Start

1

Clone the repository

git clone https://github.com/proliferate-ai/proliferate.git
cd proliferate
2

Configure environment

cp .env.example .env
Edit .env and set the essentials:
ANTHROPIC_API_KEY=sk-ant-...
MODAL_APP_NAME=...
MODAL_TOKEN_ID=...
MODAL_TOKEN_SECRET=...
MODAL_ENDPOINT_URL=...
GITHUB_APP_ID=...
GITHUB_APP_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
GITHUB_APP_WEBHOOK_SECRET=...
NEXT_PUBLIC_GITHUB_APP_SLUG=...
3

Start services

docker-compose up -d
4

Run database migrations

The database starts empty. Run migrations to create the required tables (requires Node.js 20+ and pnpm):
pnpm install
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/proliferate \
  pnpm -C packages/db db:migrate
5

Open Proliferate

Visit http://localhost:3000

​
What Gets Started

ServicePortDescription
Web3000Next.js frontend and API
Gateway8787WebSocket server
Worker-Background job processor
PostgreSQL5432Database
Redis6379Job queue and cache

​
Configuration

​
Minimal config (local dev)

ANTHROPIC_API_KEY=sk-ant-...
MODAL_APP_NAME=...
MODAL_TOKEN_ID=...
MODAL_TOKEN_SECRET=...
MODAL_ENDPOINT_URL=...
Modal is the default sandbox provider. If you prefer E2B, set DEFAULT_SANDBOX_PROVIDER=e2b and add the E2B credentials (see Self‑hosting → Environment Variables). For Modal setup details, see Self‑hosting → Modal Setup.
Private repo access requires a GitHub App. See Self‑hosting → GitHub App for the setup checklist.
Start from .env.example for the full list of environment variables, then fill only what you need for your deployment.
For local dev, you can keep the defaults in .env.example for database, Redis, URLs, and feature flags.
LLM proxy is optional. If LLM_PROXY_URL is unset, sandboxes call Anthropic directly using ANTHROPIC_API_KEY. If you enable the proxy, it must be publicly reachable by your sandbox provider.
For production self‑hosting, see Self‑hosting → Environment Variables for the minimal production checklist and feature‑gated options.

​
Common Commands

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# View specific service logs
docker-compose logs -f web

# Stop all services
docker-compose down

# Stop and remove volumes (reset data)
docker-compose down -v

# Rebuild after code changes
docker-compose up -d --build

​
Development Mode

For active development with hot reloading: 
# Install dependencies
pnpm install

# Start infrastructure only
docker-compose up -d postgres redis

# Run services locally
pnpm dev
Running services locally requires Node.js 20+ and pnpm. See the repository README for full development setup.

​
Troubleshooting

Check what’s using the port and stop it:
lsof -i :3000
kill -9 <PID>
  • Ensure Docker Desktop is running
  • Try docker-compose down then docker-compose up -d
  • Check Docker logs: docker-compose logs
Wait for PostgreSQL to be healthy:
docker-compose ps  # Check health status
docker-compose logs postgres
Clean up Docker:
docker system prune -a

​
Next Steps

Authentication

Configure OAuth or local auth

Deploy to AWS

Move to production on AWS