Project Overview

Source Files

This page is generated from the following source files:

• README.md
• apps/sim/app/page.tsx
• apps/sim/package.json
• apps/sim/tools/posthog/get_project.ts
• apps/sim/tools/posthog/list_projects.ts
• apps/sim/app/workspace/[workspaceId]/settings/components/team-management/components/team-seats-overview/team-seats-overview.tsx
• apps/sim/tools/hex/types.ts
• apps/sim/tools/jira/types.ts
• apps/sim/tools/asana/types.ts
• apps/sim/tools/ahrefs/types.ts

Sim is an open-source AI agent platform designed for building and orchestrating agentic workflows. The platform enables developers to create AI-powered automation systems that connect with over 1,000 integrations and multiple LLM providers. Built with modern web technologies, Sim provides both cloud-hosted and self-hosted deployment options, making it suitable for organizations ranging from individual developers to enterprise teams. The platform emphasizes extensibility through its tool system, allowing seamless integration with analytics platforms, project management tools, and various AI model providers.

Project Introduction

Sim positions itself as a comprehensive platform for building AI agents and running agentic workforces. The project's core value proposition centers on enabling users to orchestrate complex AI-driven workflows without extensive infrastructure management. According to the landing page metadata, Sim supports "AI agents, agentic workforce, agentic workflows, knowledge bases, tables, document creation, email automation, Slack bots, data analysis, customer support, content generation" as primary use cases (apps/sim/app/page.tsx:78-88).

The platform offers a tiered pricing model including a free tier, pro subscription at $25/month, maximum tier at $100/month, team plans, and enterprise custom pricing. This structure accommodates various user segments from individual developers to large organizations. The project maintains global availability with English as the primary supported language (apps/sim/app/page.tsx:78-88).

Sim integrates with major LLM providers including OpenAI, Anthropic, Google AI, Mistral, xAI, and Perplexity. The platform also supports popular productivity and communication tools such as Slack, Gmail, Discord, Notion, Airtable, and Supabase. This extensive integration ecosystem enables agents to interact with diverse data sources and services within unified workflows (apps/sim/app/page.tsx:78-88).

The project's official tagline describes it as "the open-source platform to build AI agents and run your agentic workforce," emphasizing both the technical capabilities and the workforce automation aspect. The platform targets developers and organizations seeking to implement AI-driven automation without vendor lock-in, as evidenced by its Apache 2.0 licensing and self-hosting options (apps/sim/app/page.tsx:42-53).

Technology Stack

Sim is built on a modern technology stack optimized for performance and developer experience. The core framework leverages Next.js 16.1.6 with React 19.2.4, providing server-side rendering capabilities and a robust component architecture. The runtime environment requires Bun version 1.2.13 or higher, with Node.js 20+ as an alternative, reflecting the project's adoption of contemporary JavaScript tooling (apps/sim/package.json:1-28).

The data layer relies on PostgreSQL 12+ with the pgvector extension for vector similarity operations, essential for AI-powered semantic search and retrieval. The project uses Drizzle ORM (version 0.44.5) for type-safe database interactions. For realtime communication, Socket.io enables bidirectional event-based communication between clients and servers, supporting collaborative features and live updates (README.md:183-198).

The authentication system is built on Better Auth (version 1.3.12), providing secure user management with SSO capabilities through @better-auth/sso and Stripe integration via @better-auth/stripe. The UI component library leverages Radix UI primitives for accessible, customizable interface elements, styled with Tailwind CSS and enhanced with Framer Motion animations (apps/sim/package.json:1-28).

Background job processing is handled by Trigger.dev SDK (version 4.1.2), enabling reliable execution of long-running tasks such as AI model inference and data synchronization. For remote code execution, the platform integrates E2B (version 2.0.0), providing secure sandboxed environments for running user-submitted code. The monorepo structure is managed by Turborepo, optimizing build times and dependency management across multiple packages (README.md:183-198).

Core Architecture

The Sim platform follows a modular architecture designed for extensibility and maintainability. The system comprises several interconnected layers that handle user interface, business logic, data persistence, and external integrations.

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

Architecture Diagram Explanation:

• Client Layer: React 19 components handle UI rendering, while Socket.io client manages realtime WebSocket connections. TanStack Query provides efficient server state management and caching.
• Server Layer: Next.js 16 App Router serves as the primary HTTP handler. Better Auth manages authentication flows. Socket.io server handles bidirectional realtime communication. Trigger.dev processes asynchronous background jobs.
• Data Layer: PostgreSQL with pgvector extension provides persistent storage and vector similarity search. Redis handles session management and caching for improved performance.
• External Services: LLM providers supply AI capabilities. Tool integrations connect to third-party APIs. E2B provides isolated code execution environments.

Evidence Points:

• apps/sim/package.json:1-28 — Defines core dependencies including Next.js, React, Socket.io, and Trigger.dev
• README.md:183-198 — Documents technology stack including database, realtime, and background job systems

Deployment Options

Sim provides multiple deployment pathways to accommodate different operational requirements and infrastructure preferences. The platform supports Docker-based deployment, Dev Containers for development, and manual setup for custom environments.

Docker Deployment

The Docker deployment option offers containerized execution with pre-configured services. For environments requiring local AI model inference, the platform supports Ollama integration through the OLLAMA_URL environment variable. The recommended Docker command is:

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

On Linux systems, users should configure extra_hosts: ["host.docker.internal:host-gateway"] in the compose file to enable proper host network access (README.md:95-99).

vLLM Integration

For organizations preferring self-hosted LLM inference, Sim supports vLLM integration. Users configure the VLLM_BASE_URL environment variable pointing to their vLLM server, with optional VLLM_API_KEY for authentication. This enables deployment of custom or fine-tuned models within private infrastructure (README.md:100-102).

Dev Containers

The Dev Containers approach provides a fully configured development environment through VS Code's Remote - Containers extension. After installing the extension, developers open the project and select "Reopen in Container." The environment automatically configures dependencies and services. The bun run dev:full command starts both the main application and the realtime socket server concurrently (README.md:104-109).

Manual Setup

Manual installation requires Bun runtime, Node.js v20+, and PostgreSQL 12+ with pgvector extension. The database setup command using Docker is:

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

After cloning the repository, developers run bun install to install dependencies. Environment configuration involves copying .env.example to .env and configuring required variables (README.md:111-134).

Integration Ecosystem

Sim's extensibility stems from its modular tool system that abstracts third-party API interactions into standardized interfaces. Each tool defines parameters, request configurations, and response transformations, enabling agents to interact with external services through a consistent pattern.

Tool Architecture Pattern

The tool system follows a configuration-based approach where each tool specifies its identity, parameters, and request handling logic. The PostHog integration exemplifies this pattern with two primary tools: posthog_get_project and posthog_list_projects. Each tool defines a ToolConfig object containing:

• Identity: Unique id, human-readable name, descriptive description, and version
• Parameters: Schema defining input parameters with types, requirements, visibility levels, and descriptions
• Request Configuration: Functions generating URLs, HTTP methods, and headers based on parameters

(apps/sim/tools/posthog/get_project.ts:2-52)

PostHog Integration Implementation

The list_projects tool demonstrates the parameter definition pattern:

typescript
1params: {
2  apiKey: {
3    type: 'string',
4    required: true,
5    visibility: 'user-only',
6    description: 'PostHog Personal API Key',
7  },
8  region: {
9    type: 'string',
10    required: false,
11    visibility: 'user-only',
12    description: 'Cloud region: us or eu (default: us)',
13  },
14}

The visibility field controls whether parameters are exposed to LLM reasoning (user-or-llm) or kept private (user-only). Sensitive credentials like API keys use user-only visibility to prevent accidental exposure in agent logs (apps/sim/tools/posthog/list_projects.ts:2-56).

The request configuration dynamically constructs API endpoints based on the region parameter:

typescript
1url: (params) => {
2  const baseUrl = params.region === 'eu' ? 'https://eu.posthog.com' : 'https://us.posthog.com'
3  return `${baseUrl}/api/projects/`
4},
5method: 'GET',
6headers: (params) => ({
7  Authorization: `Bearer ${params.apiKey}`,
8})

This pattern enables region-aware API routing while maintaining a consistent tool interface (apps/sim/tools/posthog/list_projects.ts:58-65).

Response Type Definitions

Tools define TypeScript interfaces for both parameters and responses, ensuring type safety throughout the integration layer. The PostHogProjectDetail interface captures comprehensive project metadata including:

• Basic identifiers: id, uuid, organization, api_token
• Configuration: app_urls, timezone, data_attributes
• Feature flags: anonymize_ips, session_recording_opt_in, capture_performance_opt_in
• Nested configurations: correlation_config with exclusion lists

(apps/sim/tools/posthog/get_project.ts:9-37)

Supported Integration Categories

Based on the tool directory structure and dependencies, Sim supports integrations across multiple categories:

The tool system's modular design allows adding new integrations by implementing the ToolConfig interface without modifying core platform code.

Core Modules

Module 1: Application Entry Point

The main application entry point resides in apps/sim/app/page.tsx, serving as the landing page component. This module handles SEO metadata configuration and initial page rendering.

Responsibility Boundary:

• Generates OpenGraph and Twitter card metadata for social sharing
• Configures search engine directives and LLM-specific meta tags
• Renders the landing page component
• Does NOT handle authentication or workspace-specific logic

Key Implementation: The metadata export configures comprehensive SEO information:

typescript
1export const metadata: Metadata = {
2  title: 'Sim — Build AI Agents & Run Your Agentic Workforce',
3  description: 'Sim is the open-source platform to build AI agents...',
4  openGraph: {
5    title: 'Sim — Build AI Agents & Run Your Agentic Workforce',
6    locale: 'en_US',
7    images: [{ url: '/logo/426-240/primary/small.png', ... }],
8  },
9  twitter: {
10    card: 'summary_large_image',
11    site: '@simdotai',
12  },
13}

(apps/sim/app/page.tsx:31-61)

The module includes LLM-specific meta tags for enhanced discoverability by AI systems:

typescript
1'llm:use-cases': 'AI agents, agentic workforce, agentic workflows...',
2'llm:integrations': 'OpenAI, Anthropic, Google AI, Mistral...',
3'llm:pricing': 'free tier available, pro $25/month...',

(apps/sim/app/page.tsx:78-88)

Module 2: Team Management System

The team management module handles subscription-based seat allocation and team membership administration. Located in the workspace settings hierarchy, this module provides UI components for managing team subscriptions.

Responsibility Boundary:

• Displays team seat utilization (used vs. total seats)
• Handles subscription upgrade flows
• Manages seat reduction workflows
• Does NOT process payments directly (delegates to Stripe integration)

Key Data Structures: The TeamSeatsOverviewProps interface defines the component contract:

typescript
1interface TeamSeatsOverviewProps {
2  subscriptionData: Subscription | null
3  isLoadingSubscription: boolean
4  totalSeats: number
5  usedSeats: number
6  isLoading: boolean
7  onConfirmTeamUpgrade: (seats: number) => Promise<void>
8  onReduceSeats: () => Promise<void>
9  onAddSeatDialog: () => void
10}

(apps/sim/app/workspace/[workspaceId]/settings/components/team-management/components/team-seats-overview/team-seats-overview.tsx:14-24)

State Handling: The component implements three rendering states:

1. Loading State: Displays skeleton UI during subscription data fetch
2. No Subscription State: Shows setup prompt with upgrade button
3. Active Subscription State: Renders seat overview with management actions

(apps/sim/app/workspace/[workspaceId]/settings/components/team-management/components/team-seats-overview/team-seats-overview.tsx:57-85)

Module 3: Tool Integration Framework

The tool integration framework provides a standardized pattern for connecting external services. Each tool implements the ToolConfig interface with consistent structure.

Responsibility Boundary:

• Defines tool identity and capabilities
• Specifies parameter schemas with visibility controls
• Configures HTTP request generation
• Transforms API responses to standardized format
• Does NOT execute requests directly (delegates to tool executor)

Key Interface Pattern: Tools export interfaces for parameters and responses:

typescript
1export interface PostHogGetProjectParams {
2  projectId: string
3  apiKey: string
4  region?: 'us' | 'eu'
5}
6
7export interface PostHogGetProjectResponse {
8  success: boolean
9  output: { project: PostHogProjectDetail }
10  error?: string
11}

(apps/sim/tools/posthog/get_project.ts:3-45)

Error Handling: The response interface includes an optional error field, enabling graceful degradation when API calls fail. Tools return structured responses with success boolean indicators, allowing calling code to implement appropriate fallback strategies.

Module 4: Development Scripts System

The package.json scripts section defines the development workflow commands that orchestrate the application lifecycle.

Key Scripts:

(apps/sim/package.json:10-28)

The dev:full script uses concurrently to run both the Next.js application and Socket.io server with labeled output:

bash
1bunx concurrently -n "App,Realtime" -c "cyan,magenta" "bun run dev" "bun run dev:sockets"

This enables developers to see interleaved logs from both services with color-coded prefixes (apps/sim/package.json:14).

Data Flow Architecture

The following sequence diagram illustrates the critical data flow for tool execution, showing how user requests propagate through the system to external APIs and back.

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

Data Flow Explanation:

1. Request Initiation: User or AI agent initiates tool execution through the React UI, which sends a POST request to the Next.js API endpoint.
2. Session Validation: The API layer validates the user session using Better Auth before processing the request.
3. Tool Loading: The tool framework loads the appropriate tool configuration based on the requested tool ID.
4. Parameter Building: Tool configuration functions generate request parameters, URLs, and headers dynamically.
5. Cache Check: Redis cache is consulted for previously cached responses to reduce API calls.
6. External Request: On cache miss, the tool executes the HTTP request to the external API.
7. Response Transformation: Raw API responses are transformed to the standardized ToolResponse format.
8. Result Delivery: Transformed results return through the API layer to the UI for display.

Evidence Points:

• apps/sim/tools/posthog/get_project.ts:75-77 — Shows request URL construction pattern
• apps/sim/tools/posthog/list_projects.ts:58-65 — Demonstrates header generation and HTTP method configuration

Project Structure

The Sim project follows a monorepo structure managed by Turborepo. The primary application resides in apps/sim/ with shared packages in the workspace root.

sim/
├── apps/
│   └── sim/                    # Main application
│       ├── app/                # Next.js App Router pages
│       │   ├── page.tsx        # Landing page
│       │   └── workspace/      # Workspace routes
│       ├── components/         # React components
│       │   └── emails/         # Email templates
│       ├── tools/              # Tool integrations
│       │   ├── posthog/        # PostHog analytics tools
│       │   ├── jira/           # Jira integration
│       │   ├── asana/          # Asana integration
│       │   ├── ahrefs/         # SEO analytics
│       │   └── hex/            # Data platform tools
│       ├── socket/             # Socket.io server
│       └── package.json        # Dependencies
├── packages/                   # Shared workspace packages
│   ├── logger/                 # Logging utilities
│   ├── testing/                # Test utilities
│   └── tsconfig/               # Shared TypeScript configs
└── README.md                   # Project documentation

The tools/ directory contains modular integrations, each implementing the standardized tool pattern. This structure enables independent development and testing of integrations while maintaining consistent interfaces.

Report Navigation Guide

The following diagram illustrates the recommended reading sequence for this technical analysis report, showing relationships between chapters and prerequisite knowledge.

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

Navigation Recommendations:

• Start Here: Project Overview (current chapter) provides foundational understanding of technology stack and core concepts
• Next Steps: System Architecture chapter details component interactions and module boundaries
• Deep Dive: Data Flow Analysis traces request paths through the system
• Implementation: API Design and Data Model chapters provide developer reference material
• Production: Deployment Guide and Security Analysis prepare for production operations

Quantitative Capabilities

Based on the source code analysis, Sim provides the following quantifiable capabilities:

The platform's dependency list includes over 180 production dependencies, indicating a feature-rich ecosystem with comprehensive integration capabilities (apps/sim/package.json:29-181).