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.json3-10 A complete development environment requires three core services running concurrently:
apps/sim): A Next.js 16 application running on port 3000 apps/sim/package.json11apps/sim/socket/index.ts): A dedicated Socket.IO server running on port 3002 for collaborative editing and execution updates apps/sim/package.json13-14pgvector extension for vector similarity search, typically on port 5432 .devcontainer/docker-compose.yml74-83Sources: package.json3-10 apps/sim/package.json10-14 .devcontainer/docker-compose.yml74-83
| 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 apps/sim/package.json8 |
| Docker | 20.10+ | Containerization for database and services README.md59-60 |
| PostgreSQL | 17 | Relational database with pgvector support .devcontainer/docker-compose.yml74 |
| RAM | 12 GB+ | Recommended for local execution and vector operations README.md21 |
The project specifies bun@1.3.11 in the packageManager field of the root package.json package.json3
Sources: package.json3 apps/sim/package.json7-9 README.md21 .devcontainer/docker-compose.yml74
Dev Containers provide a fully automated environment with all system dependencies pre-installed.
post-create.sh script automatically runs bun install, generates the Drizzle schema, and pushes migrations to the db service .devcontainer/post-create.sh63-98sim-start (an alias for bun run dev:full) to start the servers .devcontainer/sim-commands.sh7Dev Container Entity Mapping:
Title: Dev Container Architecture and Service Mapping
Sources: .devcontainer/devcontainer.json1-37 .devcontainer/post-create.sh1-126 .devcontainer/docker-compose.yml1-89 apps/sim/lib/execution/isolated-vm.ts84-92
To develop with local LLMs, the platform supports Ollama integration. The environment variable OLLAMA_URL defaults to http://localhost:11434 in the development environment .devcontainer/docker-compose.yml23
Sources: README.md21 .devcontainer/docker-compose.yml23
If you prefer running services directly on your host machine:
Create an .env file in apps/sim/. Key variables include:
| Variable | Description |
|---|---|
DATABASE_URL | Connection string: postgresql://postgres:postgres@localhost:5432/simstudio .devcontainer/docker-compose.yml16 |
BETTER_AUTH_SECRET | Secret for session management .devcontainer/docker-compose.yml19 |
ENCRYPTION_KEY | Key for encrypting sensitive block data .devcontainer/docker-compose.yml20 |
NEXT_PUBLIC_SOCKET_URL | URL for the realtime server (default http://localhost:3002) .devcontainer/docker-compose.yml24 |
Sources: .devcontainer/docker-compose.yml14-25
Sim uses Drizzle ORM. Ensure your database is running, then apply the schema .devcontainer/post-create.sh85-97:
Sources: .devcontainer/post-create.sh85-97
Run both the Next.js app and the Socket server concurrently using the dev:full script apps/sim/package.json14:
The sim-start alias in the dev container maps to this command .devcontainer/sim-commands.sh7
Sources: package.json15 apps/sim/package.json14 .devcontainer/sim-commands.sh7
Sim is organized into apps/ and packages/ package.json7-10:
apps/sim: The core platform apps/sim/package.json2apps/docs: Documentation site built with Fumadocs apps/docs/package.json2packages/db: Shared Drizzle schema and client.packages/logger: Standardized logging utility apps/sim/package.json83Sources: package.json7-10 apps/sim/package.json2-83 apps/docs/package.json2
The project uses Biome for linting and formatting package.json37
turbo run format package.json17turbo run lint package.json19The VS Code configuration automatically enables editor.formatOnSave using Biome .devcontainer/devcontainer.json11-15
Sources: package.json17-37 .devcontainer/devcontainer.json11-15
For executing custom code blocks safely, the system uses an IsolatedVMExecution pool apps/sim/lib/execution/isolated-vm.ts55-60 It spawns child processes and manages a queue of execution requests with configurable timeouts and resource limits apps/sim/lib/execution/isolated-vm.ts29-53
Sources: apps/sim/lib/execution/isolated-vm.ts29-60
Title: Runtime Service Interaction and Data Flow
Sources: apps/sim/package.json11-197 .devcontainer/docker-compose.yml50 apps/sim/lib/execution/isolated-vm.ts29-40
Refresh this wiki