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

​
Step 1 — Clone the repository

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

​
Step 2 — Install dependencies

From the repo root, install all workspace dependencies: 
bun install

​
Step 3 — 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 ──────────────────────────────────────────────────
# PostgreSQL connection string (can be omitted if set in root .env)
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

# 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 ────────────────────────────────────────────────────
# Shared secret token used by the ai-agents service to call /api/agents/*
AGENT_TOKEN=your-agent-token

# ── Auth options ──────────────────────────────────────────────
# Enable email/password login in addition to GitHub OAuth
BETTER_AUTH_INCLUDE_EMAILS_AUTH=true

# LangSmith tracing (optional but useful for debugging agents)
LANGSMITH_TRACING=false
LANGSMITH_API_KEY=
LANGSMITH_PROJECT=zuko

​
Web — apps/web/.env

# Frontend URL
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Backend API URL
NEXT_PUBLIC_BACKEND_URL=http://localhost:3001

# Enable email/password login (must match backend setting)
NEXT_PUBLIC_BETTER_AUTH_INCLUDE_EMAILS_AUTH=true

# Auth proxy: frontend proxies /api/auth/* to backend
NEXT_PUBLIC_USE_AUTH_PROXY=true

​
AI Agents — apps/ai-agents/.env

# PostgreSQL (used for LangGraph checkpoint storage)
# Can be omitted if set in root .env
DATABASE_URL=postgres://postgres:password@localhost:5432/zuko_dev

# OpenAI (can be omitted if set in root .env)
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4.1

# Backend connection — must match AGENT_TOKEN in backend .env
BACKEND_URL=http://localhost:3001
AGENT_TOKEN=your-agent-token

# Optional tracing
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.

​
Step 4 — 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

​
Step 5 — Set up GitHub OAuth

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

​
Step 6 — 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.
ServiceURL
Frontendhttp://localhost:3000
Backend APIhttp://localhost:3001
Authhttp://localhost:3001/auth

​
Step 7 — Start the AI agents service (optional)

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

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
Clear the cached client and regenerate:
rm -rf node_modules/.prisma/
bun nx run @zuko/models:prisma:generate
  • 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
  • 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
rm bun.lockb
bun install --force
Find and kill the process on the conflicting port:
lsof -ti:3001 | xargs kill -9
  • 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