Quickstart

This guide walks you through running the full Zuko stack locally. Follow each step in order.

Clone the repository

git clone https://github.com/codemancers/zuko.git zuko
cd zuko

Install dependencies

From the repo root, install all workspace dependencies:

bun install

Configure environment variables

Copy the example env files for each service:

cp apps/backend/.env.example apps/backend/.env
cp apps/web/.env.example apps/web/.env
cp apps/ai-agents/.env.example apps/ai-agents/.env

Then edit each file with your actual values. The required variables for each service are listed below.

Root `.env`

Create a .env file at the repo root for shared variables that apply across all services:

# ── Database ──────────────────────────────────────────────────
DATABASE_URL=postgres://postgres:password@localhost:5432/zuko_dev

# ── Auth ──────────────────────────────────────────────────────
# Random secret for Better Auth session signing (min 32 chars)
BETTER_AUTH_SECRET=your-secret-here

# ── AI ────────────────────────────────────────────────────────
OPENAI_API_KEY=sk-...

# ── Agents ────────────────────────────────────────────────────
# Shared secret token — must match AGENT_TOKEN in each service .env
AGENT_TOKEN=your-agent-token

NX automatically loads the root .env for all workspace commands. Set shared variables here once instead of repeating them in each service’s .env.

Backend `apps/backend/.env`

# ── Database ──────────────────────────────────────────────────
DATABASE_URL=postgres://postgres:password@localhost:5432/zuko_dev

# ── Auth ──────────────────────────────────────────────────────
BETTER_AUTH_SECRET=your-secret-here

# GitHub OAuth — create app at https://github.com/settings/developers
# Homepage URL: http://localhost:3000
# Authorization callback URL: http://localhost:3001/auth/callback/github
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

# ── URLs ──────────────────────────────────────────────────────
BACKEND_URL=http://localhost:3001
FRONTEND_URL=http://localhost:3000

# List of allowed CORS origins (comma-separated)
TRUSTED_ORIGINS=http://localhost:3000,http://localhost:3001

# ── AI ────────────────────────────────────────────────────────
OPENAI_API_KEY=sk-...

# ── Agents ────────────────────────────────────────────────────
AGENT_TOKEN=your-agent-token

# ── Auth options ──────────────────────────────────────────────
BETTER_AUTH_INCLUDE_EMAILS_AUTH=true

# LangSmith tracing (optional)
LANGSMITH_TRACING=false
LANGSMITH_API_KEY=
LANGSMITH_PROJECT=zuko

Web `apps/web/.env`

NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_BACKEND_URL=http://localhost:3001
NEXT_PUBLIC_BETTER_AUTH_INCLUDE_EMAILS_AUTH=true
NEXT_PUBLIC_USE_AUTH_PROXY=true

AI Agents `apps/ai-agents/.env`

# PostgreSQL (used for LangGraph checkpoint storage)
DATABASE_URL=postgres://postgres:password@localhost:5432/zuko_dev

OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4.1

BACKEND_URL=http://localhost:3001
AGENT_TOKEN=your-agent-token

LANGSMITH_TRACING=false
LANGSMITH_API_KEY=

AGENT_TOKEN must be the same value in both apps/backend/.env and apps/ai-agents/.env. It authenticates the agents service when calling backend endpoints.

Set up the database

Create the database:

createdb zuko_dev

Generate the Prisma client:

bun nx run @zuko/models:prisma:generate

Run database migrations:

bun nx run @zuko/models:prisma:migrate -- --name init

Seed test data (optional): Creates a test user (e2e@example.com / TestPassword123!) and sample CRM data:

bun nx run @zuko/models:seed

Browse the database (optional):

bun nx run @zuko/models:prisma:studio
# Opens Prisma Studio at http://localhost:5555

Set up GitHub OAuth

Go to github.com/settings/developers
Click New OAuth App
Fill in:
- Application name: Zuko (local)
- Homepage URL: http://localhost:3000
- Authorization callback URL: http://localhost:3001/auth/callback/github
Copy the Client ID and generate a Client Secret
Paste them into apps/backend/.env as GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET

Start the app

Recommended — start backend + frontend together:

bun nx run @zuko/web:dev

This starts both the NestJS backend and the Next.js frontend with hot reload.

Service	URL
Frontend	http://localhost:3000
Backend API	http://localhost:3001
Auth	http://localhost:3001/auth

Start the AI agents service

In a separate terminal:

bun nx run @zuko/ai-agents:dev

This starts the LangGraph agent runtime at http://localhost:8080 with LangGraph Studio for debugging.

The AI agents service is only needed if you want to use the agentic chat features. The core CRM (contacts, companies, deals) works without it.

Verify your setup

Open http://localhost:3000 — you should see the Zuko login page. Click Sign in with GitHub and authorize the OAuth app. You’ll land on the CRM dashboard. Email/password auth is enabled by default in the config above. Log in with e2e@example.com / TestPassword123! after seeding, or use Sign in with GitHub.

All commands reference

# Install dependencies
bun install

# Database
bun nx run @zuko/models:prisma:generate                  # Generate Prisma client
bun nx run @zuko/models:prisma:migrate -- --name init    # Run migrations
bun nx run @zuko/models:seed                             # Seed test data
bun nx run @zuko/models:prisma:studio                    # Open DB browser (port 5555)
bun nx run @zuko/models:prisma:reset                     # Reset DB (destructive!)

# Development
bun nx run @zuko/web:dev                                 # Start frontend + backend
bun nx run @zuko/backend:serve                           # Start backend only
bun nx run @zuko/ai-agents:dev                           # Start AI agents (port 8080)
bun nx run @zuko/meeting-bot:dev                         # Start meeting bot (port 8000)

# Tests
bun nx run @zuko/backend:test                            # Backend unit tests
bun nx run @zuko/web:test                                # Web unit tests
bun nx affected -t test                                  # Test only affected projects

# E2E tests
NODE_ENV=test bunx nx run web-e2e:e2e                    # Run E2E tests
NODE_ENV=test bunx nx run web-e2e:e2e --ui               # E2E with UI mode

# Build
bun nx run @zuko/backend:build
bun nx run @zuko/web:build
bun nx run @zuko/ai-agents:build

# Utilities
bun nx graph                                             # Visualize project dependency graph
bun nx show project @zuko/backend                        # Show available targets
bun nx affected -t lint                                  # Lint affected projects

Troubleshooting

PostgreSQL connection error

Ensure PostgreSQL is running:

# macOS
brew services start postgresql@16

# Linux
sudo systemctl start postgresql

Test the connection:

psql -U postgres -d zuko_dev

Check DATABASE_URL format: postgres://user:password@host:port/dbname

Prisma client errors

Clear the cached client and regenerate: bash rm -rf node_modules/.prisma/ bun nx run @zuko/models:prisma:generate

Auth / CORS errors

Ensure TRUSTED_ORIGINS in apps/backend/.env includes both http://localhost:3000 and http://localhost:3001 - Clear browser cookies and retry - Confirm the GitHub OAuth callback URL is exactly http://localhost:3001/auth/callback/github

Frontend can't connect to backend

Confirm NEXT_PUBLIC_BACKEND_URL=http://localhost:3001 in apps/web/.env - Make sure the backend started without errors before opening the frontend - Check the backend terminal for startup errors

Bun install fails or lock file issues

bash rm bun.lockb bun install --force

Port already in use

Find and kill the process on the conflicting port: bash lsof -ti:3001 | xargs kill -9

AI agents service won't start

Ensure OPENAI_API_KEY is set in apps/ai-agents/.env
Ensure AGENT_TOKEN matches the value in apps/backend/.env
The first start may be slow (downloading LangGraph CLI dependencies)
If port 8080 is in use, kill it: lsof -ti:8080 | xargs kill -9

Next steps

Explore the Concepts section to understand the architecture
Read the Guides to learn how to use agentic chat with CRM data
Add the Zuko MCP server to your AI coding agent for context-aware setup help

Overview

Getting Started

Setup

Concepts

Guides

Clone the repository

Install dependencies

Configure environment variables

Root `.env`

Backend `apps/backend/.env`

Web `apps/web/.env`

AI Agents `apps/ai-agents/.env`

Set up the database

Set up GitHub OAuth

Start the app

Start the AI agents service

Verify your setup

All commands reference

Troubleshooting

Next steps

​Clone the repository

​Install dependencies

​Configure environment variables

​Root .env

​Backend apps/backend/.env

​Web apps/web/.env

​AI Agents apps/ai-agents/.env

​Set up the database

​Set up GitHub OAuth

​Start the app

​Start the AI agents service

​Verify your setup

​All commands reference

​Troubleshooting

​Next steps

Clone the repository

Install dependencies

Configure environment variables

Root `.env`

Backend `apps/backend/.env`

Web `apps/web/.env`

AI Agents `apps/ai-agents/.env`

Set up the database

Set up GitHub OAuth

Start the app

Start the AI agents service

Verify your setup

All commands reference

Troubleshooting

Next steps