Skip to main content
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

  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

​
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

​
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

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: bash 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
bash rm bun.lockb bun install --force
Find and kill the process on the conflicting port: bash 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
  • Add the Zuko MCP server to your AI coding agent for context-aware setup help