This document describes how to set up a local development environment for the Sim platform. It covers prerequisites, installation steps, and common development workflows using Bun and Docker.
The Sim platform is architected as a Bun workspace monorepo package.json1-10 A complete development environment requires several core services running concurrently:
apps/sim): A Next.js 16 application running on port 3000 apps/sim/package.json11apps/realtime): A dedicated Socket.IO server running on port 3002 for collaborative editing and execution updates package.json14-15 apps/realtime/package.json54-55pgvector extension for vector similarity search, typically on port 5432 docker-compose.prod.yml88-91apps/docs): A Fumadocs-powered site for platform documentation apps/docs/package.json27-30Sources: package.json1-15 apps/sim/package.json11 apps/docs/package.json27-30 docker-compose.prod.yml88-91
| Requirement | Version | Purpose |
|---|---|---|
| Bun | >=1.2.13 | Primary runtime, package manager, and test runner apps/sim/package.json7 |
| Node.js | >=20.0.0 | Compatibility layer for specific libraries like isolated-vm apps/sim/package.json8-9 |
| Docker | Latest | Containerization for database and production-like services README.md59-60 |
| RAM | 12 GB+ | Recommended for local execution and vector operations README.md21 |
The project specifies bun@1.3.13 in the packageManager field of the root package.json package.json3
Sources: package.json3 apps/sim/package.json7-9 README.md21 README.md59-60
To run the full stack as it would appear in production, use the provided production compose file docker-compose.prod.yml1-106
This starts the simstudio app, realtime server, db (PostgreSQL + pgvector), and a one-time migrations container to sync the schema docker-compose.prod.yml1-85
Sources: README.md21 docker-compose.prod.yml1-85
To develop with local LLMs, use the Ollama profile provided in the repository configuration. This setup includes a model-setup helper that automatically pulls necessary models README.md21
Sources: README.md21
If you prefer running services directly on your host machine for faster iteration:
The project uses Bun workspaces to manage internal packages and external dependencies package.json7-10
Create an .env file in apps/sim/. Key variables include:
| Variable | Description |
|---|---|
DATABASE_URL | Connection string for PostgreSQL docker-compose.prod.yml13 |
NEXT_PUBLIC_APP_URL | The base URL for the application apps/sim/next.config.ts166 |
BETTER_AUTH_SECRET | Secret for Better Auth session management docker-compose.prod.yml20 |
ENCRYPTION_KEY | Key for encrypting sensitive workflow data docker-compose.prod.yml21 |
INTERNAL_API_SECRET | Secret for internal service-to-service communication docker-compose.prod.yml23 |
Sources: docker-compose.prod.yml11-34 apps/sim/next.config.ts166
Sim uses Drizzle ORM. Apply the schema using the following command from the workspace root:
This executes the migration script which is containerized in the migrations service for production deployments docker-compose.prod.yml76-85
Sources: docker-compose.prod.yml76-85 package.json11-47
Run the full stack concurrently from the root:
The dev:full script uses concurrently to execute next dev for the main app and bun run dev for the realtime server package.json15
Sources: package.json15 apps/sim/package.json11
Sim is organized into apps/ and packages/ package.json7-10:
apps/sim: The core Next.js platform apps/sim/package.json2apps/realtime: The Socket.IO collaboration server apps/realtime/package.json55apps/docs: Documentation site built with Fumadocs apps/docs/package.json2@sim/db: Shared Drizzle schema and database client apps/realtime/package.json60@sim/workflow-types: Shared TypeScript interfaces for the workflow engine apps/realtime/package.json67@sim/security: Security utilities including CSP and encryption apps/realtime/package.json63Sources: package.json7-10 apps/sim/package.json2 apps/realtime/package.json55-67 apps/docs/package.json2
The project uses Biome for linting and formatting package.json59
turbo run format package.json17turbo run lint package.json19turbo run type-check package.json46Sources: package.json17-66 apps/sim/package.json26-29
Title: "Development Service Interaction and Data Flow"
Sources: apps/sim/package.json11-124 apps/realtime/package.json66 docker-compose.prod.yml28
Title: "CI/CD Pipeline and Build Stages"
Sources: .github/workflows/test-build.yml11-154 docker/app.Dockerfile4-142
Refresh this wiki