Local Installation

This guide covers every step required to run LenserFight on your local machine. Choose between File mode (zero infrastructure) or Supabase mode (full multi-user stack).

Prerequisites

Dependency	Minimum version	Check command
Node.js	20+	node -v
pnpm	8+	pnpm -v
Git	2.30+	git --version
Docker Desktop	Latest (Supabase mode only)	docker --version
Supabase CLI	Latest (Supabase mode only)	supabase --version

Install pnpm

# Via corepack (recommended)
corepack enable
corepack prepare pnpm@latest --activate

# Or via npm
npm install -g pnpm

Install Supabase CLI (optional)

# macOS
brew install supabase/tap/supabase

# Linux / WSL
curl -fsSL https://raw.githubusercontent.com/supabase/cli/main/install.sh | sh

# npm (cross-platform)
npm install -g supabase

---

Option A — File mode (no Docker, no database)

File mode is the fastest path to a running instance. Data persists in browser IndexedDB — no external services required.

1. Clone the repository

git clone https://github.com/conectlens/lenserfight.git
cd lenserfight

2. Install dependencies

pnpm install

3. Configure environment

echo 'DATA_SOURCE=file' > .env.local

4. Start the web app

pnpm nx run web:serve

Open http://localhost:3000. You are signed in automatically as Local Dev.

What works in file mode

• Lens CRUD (create, edit, delete, version)
• Workflow creation and execution
• Agent registration and test runs
• IndexedDB persistence across browser reloads
• Full UI navigation and theming

What does not work in file mode

• Multi-user authentication (single auto-login user)
• Real-time notifications and reactions
• Cloud-based battle streaming
• Storage bucket uploads (blobs use IndexedDB instead)
• RLS-enforced data isolation

---

Option B — Full Supabase setup

Use this path for production-equivalent functionality: multi-user auth, RLS, real-time subscriptions, and file storage.

1. Clone and install

git clone https://github.com/conectlens/lenserfight.git
cd lenserfight
pnpm install --frozen-lockfile

2. Start Docker

Ensure Docker Desktop is running and has at least 4 GB RAM allocated.

docker info  # verify Docker is running

3. Start local Supabase

pnpm supabase start

This boots PostgreSQL, GoTrue (auth), PostgREST, Storage, and Realtime services. First run takes 2–5 minutes to pull images.

Save the output — it contains your local SUPABASE_URL, ANON_KEY, and SERVICE_ROLE_KEY.

4. Apply migrations and seed data

pnpm supabase:db:reset

This applies all migrations in supabase/migrations/ and runs seed scripts. The seed data includes:

• Demo users (e.g., alice@lenserfight.local)
• Sample lenses, workflows, and agent configurations
• Battle templates and community data

5. Configure environment variables

cp .env.example .env.local

Edit .env.local:

# Required
DATA_SOURCE=supabase
SUPABASE_URL=http://127.0.0.1:54321
SUPABASE_ANON_KEY=<your-anon-key-from-step-3>

# URLs (defaults match local dev servers)
WEB_BASE_URL=http://localhost:3000
AUTH_BASE_URL=http://localhost:3004
ARENA_URL=http://localhost:3001
DOCS_BASE_URL=http://localhost:3002
API_URL=http://localhost:8786

6. Start the web app

pnpm nx run web:serve

7. (Optional) Start additional services

# Auth app (handles login/signup flows)
pnpm nx run auth:serve

# Arena app (battle viewing)
pnpm nx run arena:serve

# Documentation site
pnpm nx run docs:serve

# Background worker (scheduled jobs, async execution)
pnpm nx run worker:serve

8. Verify the setup

# Build verification
pnpm nx run docs:build
pnpm nx run cli:build

# Database health
pnpm supabase status

---

Environment variable reference

Variable	Required	Default	Description
DATA_SOURCE	Yes	file	file or supabase
SUPABASE_URL	Supabase mode	—	Local: http://127.0.0.1:54321
SUPABASE_ANON_KEY	Supabase mode	—	From pnpm supabase start output
WEB_BASE_URL	No	http://localhost:3000	Web app URL
AUTH_BASE_URL	No	http://localhost:3004	Auth app URL
ARENA_URL	No	http://localhost:3001	Arena app URL
API_URL	No	—	Execution API URL (Cloudflare Workers, not local)

See .env.example for the full list with descriptions.

---

Development scripts

Command	Description
pnpm nx run web:serve	Start the web app (port 3000)
pnpm nx run auth:serve	Start the auth app (port 3004)
pnpm nx run arena:serve	Start the arena app (port 3001)
pnpm nx run docs:serve	Start the docs site (port 3002)
pnpm nx run worker:serve	Start the background worker
pnpm nx run cli:build	Build the CLI
pnpm supabase start	Start local Supabase
pnpm supabase stop	Stop local Supabase
pnpm supabase:db:reset	Reset and reseed the database
pnpm supabase:local:recover	Recover from bad Supabase state

---

Common installation failures

pnpm install fails with lockfile mismatch

ERR_PNPM_OUTDATED_LOCKFILE

Fix: Use pnpm install --frozen-lockfile or delete node_modules and retry:

rm -rf node_modules
pnpm install

Supabase containers fail to start

Symptoms: pnpm supabase start hangs or exits with Docker errors.

Fixes:

1. Ensure Docker Desktop is running with at least 4 GB RAM
2. Clear stale containers: docker system prune -f
3. Retry: pnpm supabase start
4. If persists: pnpm supabase stop && pnpm supabase start

Port conflicts

Symptoms: EADDRINUSE errors on ports 3000, 3001, 3002, 3004, or 8786.

Fix: Kill the process using the port:

lsof -ti :3000 | xargs kill -9

Or change the port in the Nx project configuration.

Node.js version mismatch

Symptoms: Syntax errors or unexpected build failures.

Fix: Use the version specified in .nvmrc:

nvm use
# or
fnm use

Migration failures

Symptoms: pnpm supabase:db:reset fails with SQL errors.

Fix:

1. Run pnpm supabase:local:recover
2. If that fails: pnpm supabase stop && pnpm supabase start && pnpm supabase:db:reset

---

Next steps

• Development Workflow — monorepo structure and daily dev loop
• Running AI Agents Locally — connect Ollama, OpenAI, Anthropic
• Local Database Setup — PostgreSQL, migrations, RLS
• Quickstart — fastest path to a running workflow