Quick Start

Source Files

This page is generated from the following source files:

• README.md
• docker-compose.prod.yml
• docker-compose.ollama.yml
• .devcontainer/README.md
• .devcontainer/devcontainer.json
• apps/sim/tools/mailchimp/start_automation.ts
• apps/sim/tools/mailchimp/index.ts
• apps/sim/tools/mailchimp/types.ts
• apps/sim/tools/mailchimp/add_member.ts
• apps/sim/tools/mailchimp/get_member.ts

Sim is an open-source platform for building AI agents and orchestrating agentic workflows. The platform supports over 1,000 integrations and multiple LLM providers, enabling visual workflow design on a canvas-based interface README.md:1-14.

Environment Requirements

System Prerequisites

The platform supports multiple deployment methods, each with specific requirements:

Memory Requirements: The production Docker deployment allocates 8GB RAM for the main application and 1GB for the realtime socket server docker-compose.prod.yml:7-10 docker-compose.prod.yml:45-48. For local AI models with Ollama, systems should have 12GB+ RAM available README.md:17.

Port Configuration

The following ports are used by default:

Port 3000 is exposed for the main application docker-compose.prod.yml:5-6, and port 3002 for the realtime socket server docker-compose.prod.yml:43-44.

Cloud-Hosted Quick Start

The fastest way to use Sim is through the cloud-hosted platform at sim.ai. This requires no local installation or configuration README.md:41-45.

The cloud platform provides:

• Visual workflow builder for agent design
• Copilot integration for natural language workflow generation
• Vector database integration for knowledge retrieval
• Access to 1,000+ integrations and multiple LLM providers README.md:1-14

No verification steps are required for the cloud-hosted version—simply navigate to the URL and create an account.

Self-Hosted NPM Package

The NPM package provides the quickest local setup option, wrapping Docker deployment in a single command.

Installation

Execute the following command to start Sim locally:

bash
1npx simstudio

The application will be available at http://localhost:3000 after startup README.md:47-52.

Prerequisites

Docker must be installed and running on the machine before executing the NPM command README.md:54-55. The NPM package internally uses Docker images configured for production deployment docker-compose.prod.yml:1-10.

Configuration Options

README.md:57-62

Verification

After running the command, verify the application is accessible by opening http://localhost:3000 in a web browser. The health check endpoint verifies the service is running via wget --spider --quiet http://127.0.0.1:3000 docker-compose.prod.yml:33-34.

Self-Hosted Docker Compose

Docker Compose deployment provides full control over the production environment with all services containerized.

Standard Production Deployment

Clone the repository and start services:

bash
1git clone https://github.com/simstudioai/sim.git && cd sim
2docker compose -f docker-compose.prod.yml up -d

Access the application at http://localhost:3000 README.md:64-71.

Service Architecture

The production deployment includes four services:

docker-compose.prod.yml:1-94

Local AI Models with Ollama

For offline AI capabilities, deploy with Ollama integration:

bash
1# Start with GPU support (automatically downloads gemma3:4b model)
2docker compose -f docker-compose.ollama.yml --profile setup up -d
3
4# For CPU-only systems:
5docker compose -f docker-compose.ollama.yml --profile cpu --profile setup up -d

After the model downloads, access the application at http://localhost:3000 README.md:73-85.

The Ollama configuration sets OLLAMA_URL=http://ollama:11434 to connect to the Ollama container docker-compose.ollama.yml:23.

To add additional models:

bash
1docker compose -f docker-compose.ollama.yml exec ollama ollama pull llama3.1:8b

README.md:85-88

External Ollama Instance

If Ollama is already running on the host machine:

bash
1OLLAMA_URL=http://host.docker.internal:11434 docker compose -f docker-compose.prod.yml up -d

On Linux, use the host's IP address or configure extra_hosts in the compose file README.md:90-98.

vLLM Integration

Sim supports vLLM for self-hosted models. Set the following environment variables:

• VLLM_BASE_URL: Base URL for the vLLM server
• VLLM_API_KEY: API key (optional)

README.md:100-102

Verification

Check container status:

bash
1docker compose -f docker-compose.prod.yml ps

All containers should show "healthy" status. The health checks verify:

• Main app: http://127.0.0.1:3000 docker-compose.prod.yml:33-38
• Realtime server: http://127.0.0.1:3002/health docker-compose.prod.yml:60-65
• Database: pg_isready -U postgres docker-compose.prod.yml:89-93

Self-Hosted Dev Containers

Dev Containers provide an isolated development environment with all dependencies pre-configured.

Setup Steps

1. Install VS Code with the Remote - Containers extension
2. Open the project folder in VS Code
3. Click "Reopen in Container" when prompted README.md:104-107

Running the Application

Inside the dev container, execute:

bash
1bun run dev:full

Alternatively, use the sim-start alias. This command starts both the main Next.js application and the realtime socket server README.md:108-109.

The realtime server configuration matches the production setup, running on port 3002 docker-compose.prod.yml:40-65.

Self-Hosted Manual Setup

Manual setup provides maximum control over the development environment but requires more configuration.

Requirements

• Bun runtime
• Node.js v20 or higher
• PostgreSQL 12+ with pgvector extension README.md:111-113

Installation Steps

1. Clone and install dependencies:

bash
1git clone https://github.com/simstudioai/sim.git
2cd sim
3bun install

README.md:115-121

2. Set up PostgreSQL with pgvector:

Using Docker:

bash
1docker run --name simstudio-db -e POSTGRES_PASSWORD=your_password -e POSTGRES_DB=simstudio -p 5432:5432 -d pgvector/pgvector:pg17

Or install manually via the pgvector guide README.md:123-129.

The production Docker setup uses pgvector/pgvector:pg17 as the database image docker-compose.prod.yml:78-79.

3. Configure environment variables:

bash
1cp apps/sim/.env.example apps/sim/.env
2cp packages/db/.env.example packages/db/.env

Edit both .env files to set DATABASE_URL="postgresql://postgres:your_password@localhost:5432/simstudio" README.md:131-137.

Required Environment Variables

README.md:160-174

These variables are also referenced in the Docker Compose production configuration docker-compose.prod.yml:11-25.

4. Run database migrations:

bash
1cd packages/db && bunx drizzle-kit migrate --config=./drizzle.config.ts

README.md:139-143

5. Start development servers:

bash
1bun run dev:full

This starts both the Next.js app and realtime socket server. To run separately:

• Next.js only: bun run dev
• Realtime server only: cd apps/sim && bun run dev:sockets README.md:145-151

Deployment Flow Overview

The following diagram illustrates the decision flow for selecting a deployment method:

正在加载图表渲染器...

Verification and Health Checks

Service Health Verification

Each service in the Docker Compose deployment includes health checks:

Main Application (simstudio):

• Endpoint: http://127.0.0.1:3000
• Check interval: 90 seconds
• Timeout: 5 seconds
• Retries: 3
• Start period: 10 seconds docker-compose.prod.yml:33-38

Realtime Socket Server:

• Endpoint: http://127.0.0.1:3002/health
• Check interval: 90 seconds
• Timeout: 5 seconds
• Retries: 3 docker-compose.prod.yml:60-65

PostgreSQL Database:

• Check command: pg_isready -U postgres
• Check interval: 5 seconds
• Timeout: 5 seconds
• Retries: 5 docker-compose.prod.yml:89-93

Manual Verification Commands

Check all container statuses:

bash
1docker compose -f docker-compose.prod.yml ps

Expected output should show all services as "healthy" or "running".

View logs for troubleshooting:

bash
1docker compose -f docker-compose.prod.yml logs -f simstudio
2docker compose -f docker-compose.prod.yml logs -f realtime

Common Issues and Troubleshooting

Port Conflicts

Symptom: Container fails to start with "port is already allocated" error.

Cause: Ports 3000, 3002, or 5432 are already in use by other services README.md:17.

Solution:

1. Identify the process using the port: lsof -i :3000 (macOS/Linux) or netstat -ano | findstr :3000 (Windows)
2. Stop the conflicting service or modify the port mapping in docker-compose.prod.yml
3. For custom ports, use the -p flag with NPM package: npx simstudio -p 3001

Docker Not Running

Symptom: "Cannot connect to the Docker daemon" error.

Cause: Docker is not installed or the Docker daemon is not running README.md:17.

Solution:

1. Verify Docker installation: docker --version
2. Check Docker daemon status: docker info
3. Start Docker Desktop (Windows/macOS) or Docker daemon (Linux)

Insufficient Memory

Symptom: Containers are killed or become unresponsive.

Cause: System has insufficient RAM. The main application requires 8GB and realtime server requires 1GB docker-compose.prod.yml:7-10 docker-compose.prod.yml:45-48. With Ollama, 12GB+ total RAM is recommended README.md:17.

Solution:

1. Check available memory: docker stats
2. Increase Docker memory allocation in Docker Desktop settings
3. For Ollama deployments, use CPU-only mode if GPU memory is limited

Database Connection Failures

Symptom: Application fails with "connection refused" or "database does not exist" errors.

Cause: Database service is not healthy or DATABASE_URL is misconfigured.

Solution:

1. Verify database container is running: docker compose -f docker-compose.prod.yml ps db
2. Check database health: The container uses pg_isready -U postgres for health checks docker-compose.prod.yml:89-90
3. Verify DATABASE_URL format matches: postgresql://${POSTGRES_USER:-postgres}:${POSTGRES_PASSWORD:-postgres}@db:5432/${POSTGRES_DB:-simstudio} docker-compose.prod.yml:13

Migration Failures

Symptom: Migrations container exits with error, application fails to start.

Cause: Database schema is not initialized or migration files are corrupted.

Solution:

1. Check migration logs: docker compose -f docker-compose.prod.yml logs migrations
2. The migrations service runs bun run db:migrate docker-compose.prod.yml:75
3. For manual setup, ensure migrations are run: cd packages/db && bunx drizzle-kit migrate --config=./drizzle.config.ts README.md:141-142

Ollama Model Download Issues

Symptom: Ollama container starts but AI features don't work.

Cause: Model download is incomplete or failed.

Solution:

1. Wait for model download to complete (gemma3:4b is downloaded automatically with --profile setup) README.md:78-79
2. Check Ollama logs: docker compose -f docker-compose.ollama.yml logs ollama
3. Manually pull models: docker compose -f docker-compose.ollama.yml exec ollama ollama pull gemma3:4b

Next Steps

After successfully deploying Sim, consider the following:

1. Configure LLM Providers: Set up API keys for OpenAI, Anthropic, or other LLM providers in the settings
2. Enable Copilot: Generate a Copilot API key from sim.ai → Settings → Copilot and set COPILOT_API_KEY for AI-assisted workflow building README.md:153-158
3. Set Up Integrations: Connect to the 1,000+ available integrations through the workflow builder
4. Create Workflows: Use the visual canvas to design agent workflows by connecting agents, tools, and blocks README.md:20-21
5. Upload Knowledge: Integrate vector databases to enable agents to answer questions based on custom documents README.md:34-35

For detailed usage instructions, refer to the official documentation README.md:13.