Getting Started

Relevant source files

• .devcontainer/Dockerfile
• .devcontainer/README.md
• .devcontainer/devcontainer.json
• .devcontainer/docker-compose.yml
• .devcontainer/post-create.sh
• .devcontainer/sim-commands.sh
• .dockerignore
• .github/workflows/docs-embeddings.yml
• .github/workflows/i18n.yml
• .github/workflows/migrations.yml
• .github/workflows/publish-cli.yml
• .github/workflows/publish-ts-sdk.yml
• .github/workflows/test-build.yml
• README.md
• apps/docs/package.json
• apps/docs/tsconfig.json
• apps/sim/lib/execution/isolated-vm.ts
• apps/sim/next.config.ts
• apps/sim/package.json
• apps/sim/tsconfig.json
• bun.lock
• docker-compose.local.yml
• docker-compose.prod.yml
• docker/app.Dockerfile
• docker/db.Dockerfile
• docker/realtime.Dockerfile
• helm/sim/templates/_helpers.tpl
• helm/sim/templates/deployment-worker.yaml
• helm/sim/values.yaml
• package.json
• packages/tsconfig/base.json
• packages/tsconfig/library.json
• packages/tsconfig/nextjs.json

This document provides step-by-step instructions for setting up Sim Studio locally and creating your first AI agent workflow. It covers installation prerequisites, multiple deployment methods, and initial configuration.

For production deployment options, see 1.2 Deployment Options. For detailed technology stack information, see 1.3 Technology Stack.

---

Overview

Sim Studio is a platform for building and deploying AI agent workflows. The system consists of three core services and a background worker:

Service	Port	Purpose
simstudio	3000	Next.js application serving the UI and API apps/sim/package.json11
sim-worker	3001	BullMQ background worker for long-running tasks apps/sim/package.json22
realtime	3002	Socket.io server for collaborative editing apps/sim/package.json13
db	5432	PostgreSQL 17 with pgvector extension docker-compose.prod.yml119

All deployment methods provision these services plus a one-time migrations container for database schema setup docker-compose.prod.yml107-116

Sources: docker-compose.prod.yml1-137 apps/sim/package.json11-22

---

System Architecture

Code-to-Entity Mapping

This diagram associates system services with their specific entry points and resource requirements defined in the codebase.

Deployment Service Configuration

The main application container requires 8GB RAM due to workflow execution sandboxing via isolated-vm, in-memory document parsing, and vector operations docker-compose.prod.yml10 The worker requires 4GB RAM to handle background workflow execution and document processing docker-compose.prod.yml50

Sources: docker-compose.prod.yml1-137 docker-compose.local.yml1-132 apps/sim/next.config.ts90-95 apps/sim/package.json150

---

Prerequisites

Required Software

Component	Version	Purpose
Docker	20.10+	Container runtime (all deployment methods except manual)
Bun	1.2.13+	JavaScript runtime (manual setup only) apps/sim/package.json7
Node.js	20.0.0+	JavaScript runtime (manual setup only) apps/sim/package.json8
PostgreSQL	17+	Database with pgvector docker-compose.prod.yml119

System Requirements

Resource	Minimum	Recommended
CPU	2 cores	4+ cores
RAM	12 GB	16+ GB
Storage	20 GB SSD	50+ GB SSD

Memory is the primary constraint due to isolated-vm sandboxing for workflow execution apps/sim/next.config.ts90 in-memory document parsing via mammoth/officeparser apps/sim/package.json138-150 and pgvector operations.

Sources: README.md21 apps/sim/package.json6-9 apps/sim/package.json138-150 docker-compose.prod.yml10-50

---

Deployment Methods

Sources: README.md45-152

---

Method 1: NPM Package (Fastest)

The NPM package automatically manages Docker containers for you.

Installation

This command:

1. Pulls Docker images: ghcr.io/simstudioai/simstudio:latest, ghcr.io/simstudioai/realtime:latest, ghcr.io/simstudioai/migrations:latest.
2. Starts PostgreSQL with pgvector.
3. Runs database migrations.
4. Starts the application on port 3000.

Verification

Open http://localhost:3000. You should see the login page.

Sources: README.md51-56

---

Method 2: Docker Compose

Standard Deployment

This uses the production compose file at docker-compose.prod.yml1-137 Key services:

Service	Image	Resources
simstudio	ghcr.io/simstudioai/simstudio:latest	8G memory limit docker-compose.prod.yml10
sim-worker	ghcr.io/simstudioai/simstudio:latest	4G memory limit docker-compose.prod.yml50
realtime	ghcr.io/simstudioai/realtime:latest	1G memory limit docker-compose.prod.yml88
db	pgvector/pgvector:pg17	Persistent volume docker-compose.prod.yml119

Environment Variables

Key variables are defined in docker-compose.prod.yml12-28:

For custom configuration, create a .env file in the repository root. See 9.1 Environment Variables for the full list.

Sources: docker-compose.prod.yml1-137 README.md21

---

Method 3: Manual Setup (Development)

For development without Docker or when extending the codebase.

Application Setup

The monorepo structure defined in package.json7-10 includes:

• apps/sim: Main Next.js application.
• apps/docs: Documentation site.
• packages/*: Shared logic and database schema.

Start Development Servers

To run all necessary services for development:

This executes the dev:full script from apps/sim/package.json14 which starts:

• Next.js dev server on port 3000 apps/sim/package.json11
• Socket.io realtime server on port 3002 apps/sim/package.json13
• BullMQ worker apps/sim/package.json22

Sources: package.json7-10 apps/sim/package.json11-22 README.md111-152

---

Monorepo Structure

Key workspaces defined in package.json7-10:

Workspace	Purpose
apps/sim	Main application - Next.js 16, React 19, API routes, UI components.
apps/docs	Documentation - Fumadocs site apps/docs/package.json24-29
packages/db	Database layer - Drizzle ORM schema and migrations apps/sim/package.json112
packages/logger	Logging - Structured logging utilities apps/sim/package.json88

Sources: package.json1-52 apps/sim/package.json1-186 apps/docs/package.json1-49

---

Initial Configuration

Authentication Setup

Sim Studio uses Better Auth for session management apps/sim/package.json116

1. Secrets: You must provide BETTER_AUTH_SECRET, ENCRYPTION_KEY, and INTERNAL_API_SECRET docker-compose.prod.yml16-19
2. Social Login: Supports GitHub and Google if GITHUB_CLIENT_ID and GOOGLE_CLIENT_ID are provided helm/sim/values.yaml108-111

AI Provider Keys

Add AI provider API keys to enable agent blocks in your .env:

Copilot Configuration

Copilot provides AI-assisted workflow building. Set your key in the environment docker-compose.prod.yml21:

Sources: docker-compose.prod.yml16-21 helm/sim/values.yaml108-126 apps/sim/package.json116

---

Creating Your First Workflow

1. Canvas Basics

• Blocks: Design workflows visually by connecting agents, tools, and logic blocks on the canvas README.md24-29
• Real-time: Collaborative editing is powered by the realtime service docker/realtime.Dockerfile84
• Copilot: Use the natural language interface to generate nodes or fix errors README.md31-36

2. Execution

• Sync/Async: Workflows can be run instantly from the UI or triggered via webhooks.
• Worker: Long-running or scheduled workflows are handled by the sim-worker docker-compose.prod.yml43-45

Sources: README.md24-36 docker-compose.prod.yml43-45 docker/realtime.Dockerfile84