This page provides step-by-step instructions for setting up a local development environment for the Sim platform. It covers installation of prerequisites, database configuration, environment setup, and running development servers.
Note: For production deployment options, see Deployment Options. For database operations and migrations, see Database Operations.
The following tools are required for local development:
| Requirement | Version | Configuration Reference | Purpose |
|---|---|---|---|
| Bun | >=1.2.13 | package.json3 | Runtime and package manager |
| Node.js | >=20.0.0 | apps/sim/package.json8 | Required for some dependencies |
| PostgreSQL | 12+ | docker-compose.prod.yml | Primary database |
| pgvector extension | Latest | Vector extension for PostgreSQL | Vector embeddings for AI features |
| Docker (optional) | 20.10+ | For containerized services | Optional containerization |
| Git | Latest | Source control | Repository management |
pgvector Requirement: The platform requires PostgreSQL with the pgvector extension installed. This extension enables vector similarity search used by the knowledge base system (packages/db/schema/knowledge-bases.ts), semantic search in workflows, and AI embedding storage. The database initialization scripts automatically create the extension via CREATE EXTENSION IF NOT EXISTS vector;.
Package Manager: The project uses Bun as the primary package manager. All scripts in package.json11-26 and apps/sim/package.json10-24 are designed to run with bun run. Using npm or yarn is not officially supported and may cause dependency resolution issues.
Sources: README.md113 package.json3 apps/sim/package.json6-9 bun.lock1-10
Development Server Processes
The development environment consists of two primary server processes that run concurrently:
Key File Paths:
| Component | Entry Point | Configuration | Purpose |
|---|---|---|---|
| Next.js Server | apps/sim/app/layout.tsx31-229 | apps/sim/next.config.ts10-342 | Main application with SSR |
| Socket Server | apps/sim/socket/index.ts | Port 3002 (hardcoded) | Real-time collaboration |
| Database Schema | packages/db/index.ts | packages/db/drizzle.config.ts | ORM and migrations |
| Logger | packages/logger/index.ts | Shared logging utility | Structured logging |
Script Orchestration:
The development servers are started via Turborepo (turbo.json) which orchestrates the monorepo build pipeline:
bun run dev (package.json13): Starts Next.js dev server onlybun run dev:sockets (apps/sim/package.json13): Starts Socket.io server onlybun run dev:full (apps/sim/package.json14): Starts both using concurrentlySources: apps/sim/app/layout.tsx1-230 apps/sim/package.json10-24 package.json11-26 apps/sim/next.config.ts1-342 apps/sim/postcss.config.mjs1-9
The fastest way to run Sim locally using Docker:
This command automatically:
http://localhost:3000Flags:
-p, --port <port>: Specify custom port (default: 3000)--no-pull: Skip pulling latest imagesRequirements: Docker must be installed and running.
Sources: README.md43-59 packages/cli/package.json
For more control over the containerized environment:
With Ollama (Local AI Models):
The application will be available at http://localhost:3000.
Sources: README.md60-91
For VS Code development with Remote Containers:
bun run dev:full or use the sim-start aliasThe Dev Container automatically configures the development environment with all dependencies.
Sources: README.md92-97
This option provides the most flexibility for active development:
Sources: README.md107-113
Option A: Docker (Recommended)
Option B: Manual Installation
createdb simstudiopsql -d simstudio -c "CREATE EXTENSION vector;"Sources: README.md115-132
Environment File Structure
The platform uses environment variables for configuration, with separate .env files for different parts of the monorepo:
Step-by-Step Configuration:
1. Main Application Configuration (apps/sim/.env):
Edit apps/sim/.env with required variables. The environment variables are validated by @t3-oss/env-nextjs in apps/sim/lib/core/config/env.ts:
2. Database Package Configuration (packages/db/.env):
This is needed for running migrations with drizzle-kit:
Edit packages/db/.env:
Environment Variable Validation: The application uses a strict schema validation system powered by Zod and @t3-oss/env-nextjs defined in apps/sim/lib/core/config/env.ts Missing required variables will cause the application to fail at startup with descriptive error messages.
Sources: README.md133-143 apps/sim/.env.example packages/db/.env.example
Run migrations from the database package:
This applies the schema to your PostgreSQL database, creating all necessary tables.
Migration Files Location: packages/db/migrations/
For more details on database operations, see Database Operations.
Sources: README.md158-161 docker/db.Dockerfile1-42
Recommended: Run both servers together (from project root):
This starts:
Alternative: Run separately
Main application (from project root):
Realtime socket server (in separate terminal, from apps/sim):
Access the application:
http://localhost:3000http://localhost:3000/api/*ws://localhost:3002Sources: README.md163-184
Monorepo Build System
The monorepo uses Turborepo for task orchestration and caching. The build pipeline is defined in turbo.json and executed via scripts in the root package.json
Script Reference:
| Command | File | Line | Description |
|---|---|---|---|
bun run dev | package.json13 | Root | Starts Next.js dev server via Turbo |
bun run dev:full | package.json15 | Root | Starts both Next.js + Socket server concurrently |
bun run dev:sockets | package.json14 | Root | Socket server only (port 3002) |
bun run build | package.json12 | Root | Production build for all packages |
bun run test | package.json16 | Root | Run test suites across monorepo |
bun run lint | package.json19 | Root | Auto-fix linting issues with Biome |
bun run format | package.json17 | Root | Format code with Biome |
bun run type-check | package.json25 | Root | TypeScript type checking |
Workspace Configuration:
The monorepo is configured with workspaces in package.json7-10:
This allows packages to reference each other using workspace protocol (e.g., "@sim/db": "workspace:*" in apps/sim/package.json14).
Development Server Ports:
| Service | Port | Configured In |
|---|---|---|
| Next.js App | 3000 | apps/sim/package.json11 --port 3000 |
| Socket.io Server | 3002 | apps/sim/socket/index.ts hardcoded |
| Drizzle Studio | Dynamic | Launched via bunx drizzle-kit studio |
Concurrency Configuration:
The dev:full command uses concurrently (installed in apps/sim/package.json189) to run both servers with colored output:
Sources: package.json11-26 apps/sim/package.json10-24 turbo.json
Environment Variable Schema
All environment variables are validated using @t3-oss/env-nextjs in apps/sim/lib/core/config/env.ts This file defines the schema using Zod and exports type-safe environment variables.
| Variable | Purpose | Validation | Example |
|---|---|---|---|
DATABASE_URL | PostgreSQL connection string | Zod string | postgresql://postgres:pass@localhost:5432/simstudio |
BETTER_AUTH_SECRET | Session encryption key | Min 32 chars | Generate: openssl rand -hex 32 |
BETTER_AUTH_URL | Auth callback base URL | URL format | http://localhost:3000 |
NEXT_PUBLIC_APP_URL | Public app URL | URL format | http://localhost:3000 |
ENCRYPTION_KEY | General encryption key | Min 32 chars | Generate: openssl rand -hex 32 |
INTERNAL_API_SECRET | Internal API auth | Min 32 chars | Generate: openssl rand -hex 32 |
API_ENCRYPTION_KEY | API key encryption | Min 32 chars | Generate: openssl rand -hex 32 |
| Variable | Purpose | Default |
|---|---|---|
NEXT_PUBLIC_SOCKET_URL | WebSocket server URL for client | http://localhost:3002 |
PORT | Main app port | 3000 |
The socket server port is hardcoded to 3002 in apps/sim/socket/index.ts and not configurable via environment variable.
| Variable | Purpose | Load Balancing |
|---|---|---|
OPENAI_API_KEY | OpenAI API access | Use _1, _2, _3 suffixes for multiple keys |
ANTHROPIC_API_KEY_1 | Anthropic Claude | Supports load balancing |
GEMINI_API_KEY_1 | Google Gemini | Supports load balancing |
OLLAMA_URL | Local Ollama instance | Default: http://localhost:11434 |
VLLM_BASE_URL | vLLM server | No default |
AZURE_OPENAI_API_KEY | Azure OpenAI | Requires AZURE_OPENAI_ENDPOINT |
| Variable | Purpose | Default |
|---|---|---|
COPILOT_API_KEY | Enables Copilot (from sim.ai) | None |
REDIS_URL | Rate limiting & caching | None (optional) |
RESEND_API_KEY | Email notifications | None |
ADMIN_API_KEY | Admin API access | None |
DISABLE_REGISTRATION | Disable user signups | false |
| Variable | Purpose | Default |
|---|---|---|
NODE_ENV | Environment mode | development |
ANALYZE | Enable bundle analysis | false |
TURBOPACK | Use Turbopack bundler | Auto-detected by Next.js |
Docker Build Placeholders:
During Docker image builds, temporary placeholder values are set in docker/app.Dockerfile to allow Next.js to evaluate server-side code without crashing. These must be overridden at runtime:
DATABASE_URL=postgresql://placeholder:placeholder@placeholder:5432/placeholderNEXT_PUBLIC_APP_URL=http://placeholder:3000Environment Variable Loading:
Next.js loads environment variables in this order:
process.env.env.local (not committed, highest priority).env.development / .env.production.envFor complete reference, see the template files:
Sources: apps/sim/.env.example README.md162-173 apps/sim/next.config.ts2
Copilot is a Sim-managed service. To use it in self-hosted instances:
COPILOT_API_KEY in apps/sim/.envWithout this key, Copilot features will be disabled, but the rest of the application will function normally.
Sources: README.md186-191
The following diagram illustrates the database setup and migration process:
Migration Files: All database migrations are stored in packages/db/migrations/ and are managed by Drizzle Kit. The schema is defined in TypeScript files under packages/db/schema/.
Sources: README.md145-161 packages/db/drizzle.config.ts
The development environment uses the following core technologies, with specific version constraints defined in the package manifests:
| Technology | Version | Package Reference | Purpose |
|---|---|---|---|
| Bun | >=1.2.13 | package.json3 | JavaScript runtime and package manager |
| Node.js | >=20.0.0 | apps/sim/package.json8 | Required for some native dependencies |
| Next.js | 16.1.0-canary.21 | apps/sim/package.json125 | React framework with App Router |
| React | 19.2.1 | apps/sim/package.json139 | UI library |
| TypeScript | ^5.7.3 | apps/sim/package.json195 | Type safety |
| Technology | Version | Package Reference | Purpose |
|---|---|---|---|
| PostgreSQL | 12+ | External dependency | Primary database |
| pgvector | Latest | External extension | Vector similarity search |
| Drizzle ORM | ^0.44.5 | apps/sim/package.json96 | Type-safe database queries |
| postgres.js | ^3.4.5 | apps/sim/package.json135 | PostgreSQL driver |
| Technology | Version | Package Reference | Purpose |
|---|---|---|---|
| Better Auth | 1.3.12 | apps/sim/package.json83 | Authentication system |
| @better-auth/sso | 1.3.12 | apps/sim/package.json37 | SSO integration |
| jose | 6.0.11 | apps/sim/package.json113 | JWT handling |
| ipaddr.js | 2.3.0 | apps/sim/package.json111 | IP address validation |
| Technology | Version | Package Reference | Purpose |
|---|---|---|---|
| Tailwind CSS | ^3.4.1 | apps/sim/package.json194 | Utility-first CSS |
| Radix UI | Various | apps/sim/package.json54-73 | Unstyled UI primitives |
| Framer Motion | ^12.5.0 | apps/sim/package.json101 | Animation library |
| Lucide React | ^0.479.0 | apps/sim/package.json119 | Icon library |
| Technology | Version | Package Reference | Purpose |
|---|---|---|---|
| Zustand | ^4.5.7 | apps/sim/package.json166 | Client state management |
| TanStack Query | 5.90.8 | apps/sim/package.json78 | Server state & caching |
| React Hook Form | ^7.54.2 | apps/sim/package.json142 | Form management |
| Technology | Version | Package Reference | Purpose |
|---|---|---|---|
| ReactFlow | ^11.11.4 | apps/sim/package.json146 | Visual workflow editor |
| Socket.io | ^4.8.1 | apps/sim/package.json153 | WebSocket server |
| socket.io-client | 4.8.1 | apps/sim/package.json154 | WebSocket client |
| Technology | Version | Package Reference | Purpose |
|---|---|---|---|
| OpenAI SDK | ^4.91.1 | apps/sim/package.json132 | OpenAI integration |
| Anthropic SDK | ^0.39.0 | apps/sim/package.json27 | Claude integration |
| @google/genai | 1.34.0 | apps/sim/package.json42 | Gemini integration |
| isolated-vm | 6.0.2 | apps/sim/package.json112 | Secure code execution |
| @e2b/code-interpreter | ^2.0.0 | apps/sim/package.json41 | Python code execution |
| Technology | Version | Package Reference | Purpose |
|---|---|---|---|
| Trigger.dev | 4.1.2 | apps/sim/package.json80 | Background job orchestration |
| OpenTelemetry | Various | apps/sim/package.json46-53 | Observability & tracing |
| PostHog | Various | apps/sim/package.json136-137 | Analytics |
| Technology | Version | Package Reference | Purpose |
|---|---|---|---|
| Turborepo | 2.7.4 | package.json16 | Monorepo task runner |
| Biome | 2.0.0-beta.5 | package.json8 | Linting & formatting |
| Vitest | ^3.0.8 | apps/sim/package.json197 | Unit testing |
| Concurrently | ^9.1.0 | apps/sim/package.json189 | Run multiple processes |
| Package | Location | Purpose |
|---|---|---|
| @sim/db | packages/db | Shared database schema & utilities |
| @sim/logger | packages/logger | Structured logging |
| @sim/tsconfig | packages/tsconfig | Shared TypeScript configs |
| @sim/testing | packages/testing | Testing utilities |
Version Overrides:
The root package.json28-35 defines version overrides to ensure consistency across the monorepo:
Sources: README.md200-213 package.json1-55 apps/sim/package.json25-166 bun.lock1-325
The GitHub Actions workflows provide insight into the development setup, as CI mirrors the local development environment:
Key CI Files:
.github/workflows/test-build.yml: Runs tests and builds (mirrors local bun run test and bun run build).github/workflows/ci.yml: Builds Docker images for all architectures.github/workflows/trigger-deploy.yml: Deploys Trigger.dev background jobs.github/workflows/migrations.yml: Applies database migrationsSources: package.json1-73 apps/sim/package.json1-162
After completing the setup, verify that all components are working correctly:
This opens Drizzle Studio at https://local.drizzle.studio where you can:
users, workflows, workflowBlocks, workflowEdges tablespgvector extension is installed (check pg_extension table)Manual Connection Test:
Expected output:
extname | extversion
---------+------------
vector | 0.5.1
Check Next.js Server:
When running bun run dev, you should see:
▲ Next.js 16.1.0-canary.21
- Local: http://localhost:3000
- Environments: .env
✓ Ready in 2.3s
Check Socket.io Server:
When running bun run dev:sockets, you should see:
[Realtime] Socket.io server listening on port 3002
Check Both (Concurrent Mode):
When running bun run dev:full, you should see both servers with colored output:
[App] ▲ Next.js 16.1.0-canary.21
[Realtime] Socket.io server listening on port 3002
Navigate to http://localhost:3000 and verify:
/login) is accessibleExpected routing flow defined in apps/sim/app/layout.tsx31-229:
/ → /login/ → /workspaceBrowser Console Verification:
Open browser developer tools (F12) → Console tab, you should see:
[Socket] Connected to ws://localhost:3002
[Socket] Room joined: workspace:abc123
Network Tab Verification:
localhost:3002The WebSocket connection is established by the client in apps/sim/hooks/useCollaborativeWorkflow.ts (if exists) or similar hooks.
/workspace (authenticated)Create a simple workflow:
Run the workflow:
Verify execution:
workflowExecutionLogs table in database has new entriestraceSpans tableExpected API Call:
POST /api/workflows/{workflowId}/execute
Defined in apps/sim/app/api/workflows/[workflowId]/execute/route.ts.
This runs TypeScript compiler with --noEmit flag across all packages. Should complete with no errors.
Tests use Vitest configured in apps/sim/vitest.config.ts The test setup is in apps/sim/vitest.setup.ts
This should:
apps/sim/.next/Expected Output:
>>> apps/sim:build
Route (app) Size First Load JS
┌ ○ / 137 B 87.7 kB
├ ○ /login ...
└ ○ /workspace ...
○ (Static) prerendered as static HTML
Error: FATAL: password authentication failed
Diagnosis:
Solutions:
DATABASE_URL in both apps/sim/.env and packages/db/.env matchdocker ps or systemctl status postgresqlError: could not connect to server: Connection refused
Diagnosis:
Solutions:
docker start simstudio-db or brew services start postgresqlpostgresql.conf has listen_addresses = '*' (if remote)Error: database "simstudio" does not exist
Solution:
Error: extension "vector" does not exist
Diagnosis:
Solutions:
Option 1: Use pgvector Docker image (recommended):
Option 2: Install pgvector manually:
Option 3: Enable in existing PostgreSQL:
Error: Error: listen EADDRINUSE: address already in use :::3000
Diagnosis:
Solutions:
Option 1: Kill the process:
Option 2: Use a different port:
Error: Socket server port conflict (3002)
Diagnosis:
Solution:
The socket server port is hardcoded in apps/sim/socket/index.ts To change it:
const PORT = 3002 to another portNEXT_PUBLIC_SOCKET_URL in .env:
Error: Drizzle kit push failed
Diagnosis:
Solutions:
Option 1: Reset database (development only):
Option 2: Check permissions:
Option 3: Manual migration:
Error: Environment variable validation failed
This error comes from @t3-oss/env-nextjs validation in apps/sim/lib/core/config/env.ts
Diagnosis:
The error message will show which variable failed validation. Check the terminal output for details.
Common Solutions:
Required format:
Error: Module not found: Can't resolve '@sim/db'
Diagnosis:
Solution:
Error: Type error: Cannot find module '@/components/...' or its corresponding type declarations
Solution:
Check apps/sim/tsconfig.json3-25 has correct path mappings:
Restart TypeScript server in VS Code: Cmd+Shift+P → "TypeScript: Restart TS Server"
Error: Hydration failed because the initial UI does not match...
This is a common Next.js error during development, often caused by the hydration error handler in apps/sim/app/layout.tsx
Solutions:
Clear browser cache and storage:
Check for SSR/CSR mismatches:
useEffect hooks that modify DOM on mountsuppressHydrationWarning attribute where appropriateRestart dev server:
Error: WebSocket connection failed
Diagnosis:
Check browser console for:
WebSocket connection to 'ws://localhost:3002' failed: Connection refused
Solutions:
Verify socket server is running:
Check NEXT_PUBLIC_SOCKET_URL:
Restart socket server:
Error: Error: spawn ENOENT or line ending issues
Solution:
Configure Git for Unix line endings:
Use WSL2 (recommended):
Install Windows build tools:
Issue: Slow build or dev server startup
Solutions:
Clear Next.js cache:
Increase Node memory:
Disable Turbopack (if issues):
Edit apps/sim/package.json11:
After completing development setup:
Sources: README.md1-217 docker/app.Dockerfile1-117 docker/db.Dockerfile1-42 docker/realtime.Dockerfile1-76 .github/workflows/test-build.yml1-68 .github/workflows/ci.yml1-216 .github/workflows/trigger-deploy.yml1-56
Refresh this wiki
This wiki was recently refreshed. Please wait 7 days to refresh again.