Guides
Local Development Setup
Run the full Codmir platform locally as a cluster of interconnected services. This guide walks you through setting up every service and understanding how they connect.
Service Architecture
Codmir runs as a cluster of services that communicate via HTTP and WebSocket. Here's how they connect:
┌──────────────┐
│ Desktop │ Tauri + React
│ :1420 │
└──────┬───────┘
│
REST │ WebSocket
┌────┴──────────────┐
│ │
▼ ▼
┌────────────┐ ┌─────────────┐
│ Web │ │ Connect │
│ Next.js │ │ NestJS │
│ :3000 │ │ :3300 │
└─────┬──────┘ └─────────────┘
│
▼
┌────────────┐ ┌─────────────┐
│ API │ │ Workstation │
│ Hono │ │ NestJS │
│ :9000 │ │ :3400 │
└─────┬──────┘ └──────┬──────┘
│ │
▼ ▼
┌──────────────────────────────┐
│ PostgreSQL + Redis │
└──────────────────────────────┘
Web :3000
Next.js dashboard, auth, REST API, and admin panel. The main entry point for browser users.
API :9000
Hono API server handling CRUD operations, AI endpoints, and session management via Redis.
Connect :3300
NestJS WebSocket server for presence, chat, notifications, and real-time collaboration.
Workstation :3400
NestJS AI workstation: agent runtime, AI proxy, overseer, and IDE bridge.
1Prerequisites
Make sure you have the following installed before proceeding:
# Node.js 22+ (via nvm or fnm)
node --version # v22.x.x
# pnpm 9+
pnpm --version # 9.x.x
# Redis (for API sessions)
redis-cli ping # PONG
# PostgreSQL (local or Neon remote)
psql --version # 16+2Clone and Install
git clone [email protected]:codmir/codmir.git
cd codmir
pnpm installMemory limit: The .npmrc caps Node heap at 7GB. Do not remove this — uncapped builds can crash on 16GB machines.
3Environment Variables
cp .env.example .envEdit .env and fill in the required values:
4Database Setup
# Generate Prisma client
pnpm --filter @codmir/web exec prisma generate
# Push schema to database (creates tables)
pnpm --filter @codmir/web exec prisma db push
# Optional: seed with sample data
pnpm --filter @codmir/web exec prisma db seed5Start the Dev Cluster
Start all core services with a single command:
pnpm devThis starts Web (:3000), API (:9000), and Workstation (:3400) via Turbo, with logs multiplexed into .dev.log.
Or start services individually:
# Web only
pnpm dev:web
# API server
pnpm --filter @codmir/api dev
# Connect (WebSocket server)
pnpm --filter @codmir/connect dev
# Server (AI workstation)
pnpm --filter @codmir/server dev
# Desktop (Tauri app)
pnpm --filter @codmir/desktop dev6Verify Services
# API health check
curl http://localhost:9000/health
# => {"status":"ok","service":"api"}
# Workstation health check
curl http://localhost:3400/health
# => {"status":"ok","service":"server"}
# Open the dashboard
open http://localhost:3000Service Connection Map
How services discover each other via environment variables:
| From | To | Env Variable | Default |
|---|---|---|---|
| Web | API | API_BASE_URL | http://localhost:9000 |
| Desktop | Web | NEXT_PUBLIC_APP_URL | http://localhost:3000 |
| Desktop | Connect | (client config) | ws://localhost:3300 |
| Desktop | Workstation | (client config) | http://localhost:3400 |
| API | PostgreSQL | DATABASE_URL | (required) |
| API | Redis | REDIS_URL | redis://localhost:6379 |
Common Tasks
Type-check before pushing
# Always scope — never run bare tsc on apps/web (OOMs)
npx turbo run typecheck --filter=@codmir/web...
npx turbo run typecheck --filter=@codmir/api...Build for production
npx turbo run build --filter=@codmir/web...
npx turbo run build --filter=@codmir/api...Reset database
pnpm --filter @codmir/web exec prisma db push --force-reset
pnpm --filter @codmir/web exec prisma db seedView live logs
# Tail the unified dev log
tail -f .dev.log
# Filter by service
tail -f .dev.log | grep "\[api\]"
tail -f .dev.log | grep "\[workstation\]"Docker (Kernel Service)
docker compose up -d
# Starts kernel on :7700Troubleshooting
Port already in use
Kill the occupying process: lsof -ti :3000 | xargs kill -9
MODULE_NOT_FOUND on startup
Run pnpm install then rebuild: npx turbo run build --filter=@codmir/api...
OOM during build
Ensure .npmrc has node-options="--max-old-space-size=7168"
Prisma client not generated
Run pnpm --filter @codmir/web exec prisma generate
Redis connection refused
Start Redis: sudo systemctl start redis or redis-server
Previous
All Guides