Related Pages

Related topics: Integrations, Tools, and MCP, Deployment Surfaces and Enterprise Features

Platform Architecture and Workflow Builder

Overview and Core Concepts

Sim is a visual workflow builder for orchestrating AI-agent processes. The product is delivered as a multi-package monorepo: a Turborepo orchestration layer with workspaces for the main apps/sim application, the realtime collaboration service (apps/realtime), the documentation site, and shared libraries such as @sim/workflow-types and @sim/testing (Source: package.json). The repository ships with a production Docker Compose stack that exposes the app on port 3000, the realtime service on 3002, and Postgres on 5432, with a recommended 12 GB+ of RAM for the full stack (Source: README.md).

The central architectural decision — encoded throughout the codebase and explicitly stated by the docs generator — is the block ontology: *everything is a block*. An integration, a logical control-flow construct, an HTTP call, and an agent are all represented uniformly as a block on the canvas (Source: scripts/README.md).

Block System Architecture

A block is described by a TypeScript record that carries its type, name, category (e.g. tools for integrations), bgColor, its configurable subBlocks, an optional tools.access list of actions, an optional triggers capability, and its outputs (Source: scripts/README.md). This uniform shape is what allows the editor, the executor, and the docs generator to treat all nodes identically.

A block may be one of three structural kinds, each with a dedicated factory used by the test harness:

Source: packages/testing/src/factories/block.factory.ts, packages/testing/src/factories/workflow.factory.ts

For a service-style integration, the block references actions and a trigger that live in dedicated packages: apps/sim/tools/<service>/*.ts for actions (params + outputs) and apps/sim/triggers/<provider>/ for the trigger's config + outputs (Source: scripts/README.md). The @sim/workflow-types package publishes these block and workflow shapes as TypeScript-only types, and declares reactflow ^11.11.4 as a peer dependency — confirming the canvas is built on React Flow (Source: packages/workflow-types/package.json).

Workflow Composition and State Model

A workflow is a graph: a blocks map keyed by block id, an edges array of directed connections, and a loops map for nested iteration state (Source: packages/testing/src/factories/workflow.factory.ts). The shared @sim/testing package exposes a fluent WorkflowBuilder and a set of pre-shaped factories that codify the canonical topologies:

• createLinearWorkflow(n) — starter → function → function → …
• createBranchingWorkflow() — start → condition → {true-branch, false-branch} → end
• createLoopWorkflow(iterations) — start → loop[loop-body] → end

Source: packages/testing/src/builders/workflow.builder.ts, packages/testing/src/factories/workflow.factory.ts

At runtime, an ExecutionContext carries per-block logs, metadata, environment/workflow variables, router and condition decisions, loop execution state, an activeExecutionPath, and an abortSignal. The builder offers .createForWorkflow(id), .createCancelled(), and .createWithTimeout(ms) helpers that map directly to the lifecycle states the executor emits (Source: packages/testing/src/builders/execution.builder.ts).

flowchart LR
    Starter[starter block] --> A[function / api / agent]
    A --> Decision{condition}
    Decision -- condition-if --> T[true branch]
    Decision -- condition-else --> F[false branch]
    T --> End[response block]
    F --> End
    A -. parallel .- Loop[loop container]
    Loop --> Body[loop-body function]
    Body --> Loop

Real-time Collaboration

Multi-user editing is implemented in apps/realtime over socket connections. The operations handler authenticates the socket, validates the payload with Zod, persists the operation via persistWorkflowOperation, bumps the room's last-modified timestamp through roomManager.updateRoomLastModified, and then fans the change out to peers as a workflow-operation event. Position-only updates are broadcast without persistence; structural mutations always persist first. Each request correlates to the caller via an operationId, which the server echoes back as operation-confirmed (with serverTimestamp) on success or operation-failed/operation-error on failure. ZodError is treated as non-retryable, while other failures are marked retryable: true (Source: apps/realtime/src/handlers/operations.ts).

Testing Infrastructure and Cross-Cutting Concerns

The @sim/testing package is the canonical harness for both unit and integration tests. It exposes three layers:

1. Builders — fluent WorkflowBuilder, ExecutionContextBuilder, and ToolTester for HTTP-tool stubbing.
2. Factories — createAgentWithToolsWorkflowState, createBranchingWorkflow, createLoopWorkflow, createLinearWorkflow, plus per-block factories.
3. Assertions — semantic matchers like expectBlockExecuted, expectExecutionOrder, expectBlockOutput, expectConditionDecision, expectLoopCompleted, expectWorkflowAccessGranted, and expectSocketAccessGranted.

Source: packages/testing/src/builders/index.ts, packages/testing/src/assertions/index.ts

The DB schema itself is reproduced in test mocks so tests can run without a live database. The mock covers usageLog, credential (with the credentialTypeEnum of oauth | env_workspace | env_personal | service_account), credentialMember, pendingCredentialDraft, knowledgeConnector (with syncMode, lastSyncAt, consecutiveFailures, archival fields), knowledgeConnectorSyncLog, and userTableDefinitions — matching the production schema that backs blocks such as knowledge, credentials, and connectors (Source: packages/testing/src/mocks/schema.mock.ts).

Cross-cutting services that the builder relies on include the Guardrails library, which provides JSON, regex, and hallucination validators in-process and a PII detector that runs against a long-lived Presidio sidecar built from docker/pii.Dockerfile and exposed on port 5001, configured via PII_URL (Source: apps/sim/lib/guardrails/README.md). Runtime feature flags are backed by AWS AppConfig, wired in through @aws-sdk/client-appconfig at the workspace root (Source: package.json).

Community Notes

Several open requests in the issue tracker map directly onto architecture extension points described above. Issue #801 ("Custom OpenAI API URL") and #1579 ("OpenAI-compatible providers") are requests that would extend the agent block's provider configuration — the tools.access and providerId surfaces documented by the integration generator (Source: scripts/README.md). Issue #1553 ("Creating MCP Servers") targets the apps/sim/tools/ and apps/sim/blocks/blocks/ registration paths. Issue #895 (VPS Docker Compose deployment) concerns the same Compose topology referenced by the README's ports and resource requirements. Issue #3975 (signed audit trail) would attach a new integrity layer to the ExecutionContext shape, which already records blockLogs, metadata, and decisions (Source: packages/testing/src/builders/execution.builder.ts).

See Also

• Integration Documentation Generator
• Realtime Collaboration Service
• Guardrails and PII Detection
• Workflow Testing Utilities (@sim/testing)
• Workflow Type Contracts (@sim/workflow-types)

Related Pages

Related topics: Platform Architecture and Workflow Builder, Deployment Surfaces and Enterprise Features

Integrations, Tools, and MCP

Purpose and Scope

In Sim Studio, the term integration refers to a third-party service (Gmail, Slack, GitHub, Notion, HubSpot, etc.) that is exposed inside the visual workflow builder as a draggable block with a set of callable actions and, optionally, one or more event-based triggers. The codebase makes this relationship explicit: *"everything is a block, and an integration is one block that has Actions and, optionally, a Trigger"* (Source: scripts/README.md).

A tool is a single, typed action belonging to an integration — for example gmail.send_message, slack.post_message, or github.create_issue. Tools declare their input parameters and output shape and are invoked from workflow blocks during execution. The Model Context Protocol (MCP) layer is Sim's standardized way of letting agents and external clients discover and call these tools with a consistent contract, regardless of the underlying service.

This page documents the on-disk architecture for integrations, how tools are defined and registered, and how MCP connects to that registry.

Architecture: Blocks, Tools, and Triggers

Each integration is defined by three TypeScript source roots that the docs generator (scripts/generate-docs.ts) treats as the canonical registry (Source: scripts/README.md):

flowchart LR
    UI[Workflow Builder UI] -->|drag| Block[Block Definition<br/>blocks/blocks/service.ts]
    Block -->|tools.access| Tools[Tool Registry<br/>tools/service/*.ts]
    Block -->|triggers| Triggers[Trigger Registry<br/>triggers/provider/*]
    Tools -->|execute| Runtime[Sim Execution Runtime]
    Triggers -->|webhook/poll| Runtime
    Runtime -->|MCP contract| MCP[MCP Server Endpoint]
    MCP -->|JSON-RPC| Agents[Agents / External Clients]

The block file owns metadata and UI; the tool files own callable logic and parameter schemas; the trigger files own event ingestion. The generator aggregates these into apps/docs/content/docs/en/integrations/<service>.mdx, with hand-written MANUAL-CONTENT blocks preserved across regeneration (Source: scripts/README.md).

Tool Definition Pattern

A tool module exports one or more ToolConfig objects. Each declares its id, name, description, an OAuth/credential requirement, a Zod-style params shape describing user inputs, and a request body describing the outbound API call. The runtime resolves credentials from the workspace's credential store (types include oauth, env_workspace, env_personal, and service_account — see packages/testing/src/mocks/schema.mock.ts) and substitutes secrets at execution time.

For example, a tool that wraps a vendor's binary protocol uses an explicit client like callNoteStore(token, writer) to construct framed requests, then exposes higher-level helpers (createNotebook, listTags) that downstream tools compose (Source: apps/sim/app/api/tools/evernote/lib/client.ts). This separation — a thin transport client plus typed action wrappers — is the standard pattern reused across apps/sim/tools/<service>/.

Blocks reference the tools they want to surface through tools.access, an allowlist that prevents exposing internal helpers to end users. Output shape (outputs) on the block lets downstream nodes reference <blockId>.output.<field> paths in the visual data graph.

Triggers and Connectors

Triggers are inbound — they turn external events (GitHub webhooks, Google Calendar push notifications, scheduled cron) into workflow executions. A block lists an optional triggers capability, and the corresponding files in apps/sim/triggers/<provider>/ define poll or webhook ingestion plus their output payloads. Recent releases have rapidly expanded this surface: GitLab, PagerDuty, and Zendesk webhook triggers (v0.7.11), Grafana validation plus folder/health/contact tools (v0.7.8), Google Calendar v3 freebusy alignment (v0.7.8), and HubSpot notes/emails/properties/associations (v0.7.6). Knowledge-base connectors similarly evolved from string fields to resource selectors (v0.7.10).

The scheduled-tasks agent was migrated from a generic jobs agent in v0.7.8, and v0.7.11 added Google Calendar-style recurrence options while v0.7.6 introduced pause/resume, mutation toasts, and submit guards — useful context when designing triggers that schedule future runs (Source: community release notes v0.7.6–v0.7.11).

MCP and Community Expectations

MCP (Model Context Protocol) is the standardized JSON-RPC surface that Sim exposes so that agents and third-party clients can enumerate and invoke tools. Because every action is already a typed ToolConfig, the MCP server primarily re-uses the block registry rather than maintaining a parallel tool catalog — this is why the docs generator and the MCP layer both treat blocks/blocks/*.ts as the source of truth (Source: scripts/README.md).

Community interest in MCP is high. Issue #1553 requests first-class support for creating and managing MCP servers inside the platform, so that MCP developers can publish custom tools as MCP-compatible endpoints for agents. Until then, contributors add new integrations by registering a block plus its tools (and optionally triggers), then running bun run generate-docs from apps/sim (Source: apps/sim/package.json).

Related recurring requests — custom OpenAI-compatible base URLs (#801), local LLM providers via llama.cpp/LM Studio (#1637, #1579), and full self-hosting guidance (#895) — also depend on the integration registry, since providers, tools, and triggers are all expressed in the same blocks → tools → triggers shape.

Adding or Modifying an Integration

The practical workflow (Source: scripts/README.md):

1. Add or edit apps/sim/blocks/blocks/<service>.ts — declare type, category: 'tools', tools.access, and outputs.
2. Add one file per action under apps/sim/tools/<service>/<action>.ts — declare params and the HTTP/RPC request shape.
3. If the integration has an inbound event, add files under apps/sim/triggers/<provider>/.
4. Run bun run generate-docs to regenerate the integration doc page; CI will re-run and commit the result on push to main.
5. To change the prose intro without losing it on regeneration, wrap edits in {/* MANUAL-CONTENT-START:intro */} … {/* MANUAL-CONTENT-END */} markers inside the generated .mdx (Source: scripts/README.md).

Never hand-edit apps/docs/components/icons.tsx — it is regenerated from the sim app and overwritten on every run. Pages listed in HANDWRITTEN_INTEGRATION_DOCS, HANDWRITTEN_TRIGGER_DOCS, and SKIP_TRIGGER_PROVIDERS are intentionally skipped by the generator and remain fully hand-authored (Source: scripts/README.md).

See Also

• Workflow Blocks overview
• Triggers and Scheduled Tasks
• MCP Server contract and deployment
• Credential and OAuth storage
• Self-hosting with Docker Compose (addresses community issue #895)

Related Pages

Related topics: Platform Architecture and Workflow Builder, Deployment Surfaces and Enterprise Features

Self-Hosting and LLM Provider Configuration

Overview and Repository Layout

Sim is a Turborepo-managed monorepo whose root package.json declares turbo as the orchestrator and a trustedDependencies allow-list (e.g. sharp). The workspace exposes a primary Next.js application (apps/sim), a CLI (packages/cli), a public TypeScript SDK (packages/ts-sdk, published to npm from packages/ts-sdk), and several private libraries — @sim/audit, @sim/security, @sim/workflow-types, @sim/testing, and supporting @sim/utils, @sim/db, and @sim/logger packages.

The published SDK surface is significant for self-hosters: the ts-sdk package publishes repository.directory of packages/ts-sdk, with engines.node pinned to >=16 and a publishConfig.access: "public" (packages/ts-sdk/package.json). The companion CLI at packages/cli (Commander 11, Inquirer 8, Listr2 6) is intended to script deployments and workspace bootstraps (packages/cli/package.json).

The apps/sim app is the runtime that ships in the Docker image. Its package.json shows the full provider surface: @anthropic-ai/sdk 0.71.2, the full AWS SDK family (@aws-sdk/* at 3.1032.0), @trigger.dev/sdk 4.4.3 for background jobs, better-auth 1.6.11 for auth, and drizzle-orm 0.45.2 for the data layer (apps/sim/package.json). This dependency footprint explains the RAM ceiling discussed below.

Self-Hosting with Docker Compose

The repository ships two production-oriented Compose files referenced from the README: a generic docker-compose.prod.yml and an ollama variant that includes a setup profile for pulling local model weights (README.md).

Key constraints surfaced by the README:

The README's "Set Up with Cursor" badge links to an info text block that walks operators through cloning the repository and bringing up the stack with docker compose -f docker-compose.prod.yml up -d, then waiting for the health-checks reported by docker compose ... ps (README.md). A standing community thread (#895) documents operators hitting broken Ollama builds, Copilot failures, and login-flow issues in this path — a reminder that the default Compose file is tuned for cloud LLM credentials, and that the Ollama variant is the supported escape hatch for fully on-prem deployments.

flowchart LR
  User[Operator / Browser] -->| :3000 | App[apps/sim<br/>Next.js + better-auth]
  App -->| SQL :5432 | DB[(Postgres)]
  App -->| HTTP | LLM[(LLM Provider)]
  App -->| gRPC/HTTP :5001 | PII[Presidio Sidecar]
  CLI[packages/cli] -->| HTTP | App
  SDK[packages/ts-sdk] -->| HTTP | App
  subgraph Sidecars
    PII
  end
  subgraph Optional Local Stack
    LLM[Ollama / llama.cpp /<br/>LM Studio / llama-swap]
  end

LLM Provider Configuration

The apps/sim manifest pins Anthropic's first-party SDK to 0.71.2 alongside a wide set of AWS service SDKs (Bedrock, Athena, IAM, RDS Data, etc.) (apps/sim/package.json). Release v0.7.9 added "feat(providers): support large agent-block attachments via Files APIs and remote URLs" (#5092), meaning the agent block can already reach a base URL rather than a hard-coded host — the architectural prerequisite for OpenAI-compatible endpoints.

Operator requests tracked in the issue tracker describe the missing configuration knobs:

• #801 — Custom OpenAI API URL — operators want to point the OpenAI block at llama-swap, llama-server, or an Ollama instance in "OpenAI Compatibility" mode.
• #1579 — DeepInfra / OpenAI-compatible providers — the same shape: a base URL, a model name, and an API key should suffice.
• #1637 — Local llama.cpp / LM Studio — explicitly: "I cannot get the ollama docker to build at all as it consistently claims to be out of memory."

Until the URL-overriding UI ships, the supported paths are (a) route OpenAI-compatible traffic through Ollama's /v1 shim using docker-compose.ollama.yml (README.md), or (b) wire credentials through the env-var mechanism used by apps/sim providers at startup. Operators should expect to revisit the apps/sim/app/(landing)/ onboarding and the .env.example shipped inside the apps/sim directory once the URL-customization request lands.

Sidecar Services: PII / Presidio

Self-hosters running the Guardrails block need one long-lived PII sidecar. The container image is built from docker/pii.Dockerfile (source in apps/pii/server.py) and exposes /analyze, /anonymize, and /health on a single port. The recommended local recipe (apps/sim/lib/guardrails/README.md) is:

docker build -f docker/pii.Dockerfile -t sim-pii .
docker run -d -p 5001:5001 sim-pii
PII_URL=http://localhost:5001

Release v0.7.11 gated PII redaction behind a feature flag (#5144) and v0.7.13 ships a Helm-chart sidecar entry (#5188), so Kubernetes-based self-hosters should treat PII_URL as a required value rather than an optional one. The sidecar image also bakes in specialized recognizers (check-digit-validated VIN, multi-language NLP) (apps/sim/lib/guardrails/README.md), so no extra recognizer wiring is required for those classes.

Common Failure Modes and Community Workarounds

See Also

• scripts/README.md — how integration reference docs are generated
• packages/audit/package.json — signed audit-trail package relevant to enterprise self-hosting (#3975)
• packages/security/package.json — security primitives consumed by the app
• packages/workflow-types/package.json — block and workflow contracts shared with the SDK
• packages/testing/package.json — factories used to mock provider responses during local validation

Related Pages

Related topics: Platform Architecture and Workflow Builder, Integrations, Tools, and MCP, Self-Hosting and LLM Provider Configuration

Deployment Surfaces and Enterprise Features

Overview

Sim exposes a layered set of deployment surfaces — from a single-host Docker Compose stack, to a multi-service Helm chart for Kubernetes, to a public TypeScript SDK and a CLI — together with a growing catalog of enterprise features (PII redaction, feature flags, audit logging, whitelabeling, and a guarded v1 API). The platform's core thesis is that the same workflow engine that powers the hosted product must runnable in an enterprise VPC without losing observability or compliance affordances.

The system is organized as a monorepo (package.json:1 workspace root) containing apps/sim (the Next.js app), apps/docs, apps/pii (the Presidio sidecar), and several shared packages. This layout is what makes multiple deployment shapes feasible from a single source tree. Source: README.md:1-40, package.json:1-50.

Containerized Deployment (Docker Compose)

The fastest path to a running instance is Docker Compose. The root README wires the call-to-action into a one-click Cursor setup that clones the repo, runs docker compose -f docker-compose.prod.yml up -d, waits for healthy containers, and verifies the app on http://localhost:3000. Common failure modes are called out explicitly: ports 3000/3002/5432 collisions, Docker daemon not running, and insufficient memory (12 GB+ recommended). Source: README.md:1-40.

For local AI workloads, a separate docker-compose.ollama.yml profile is used in place of the production stack so that Ollama can be pulled in via the setup profile. This dual-stack pattern — one for "demo", one for "local models" — is the same shape that the Helm chart later generalizes for cloud targets.

Kubernetes Deployment (Helm)

For production, the helm/sim chart packages the platform as several cooperating Deployments. A default install includes the Next.js app, a separate realtime WebSocket service for live workflow updates, and an in-cluster pgvector/pgvector Postgres. Source: helm/sim/README.md:1-50.

The chart ships example values files for each target environment, so the same chart can be retargeted without forking:

Source: helm/sim/README.md:50-110.

The chart requires Kubernetes 1.25+ and is licensed Apache-2.0; secrets (BETTER_AUTH_SECRET, ENCRYPTION_KEY, INTERNAL_API_SECRET, CRON_SECRET, POSTGRES_PASSWORD) are expected to be generated out-of-band and supplied at install time. The presence of dedicated values files for AWS / GCP / Azure plus an external-secrets profile signals an explicit enterprise posture: secrets, storage, and identity are pluggable rather than hard-coded.

Enterprise Features

PII detection (Presidio sidecar)

PII detection runs against a single long-lived Presidio sidecar built from docker/pii.Dockerfile (source in apps/pii/server.py). The sidecar constructs a warm AnalyzerEngine + AnonymizerEngine once and exposes /analyze, /anonymize, and /health on a single port. In deployment it runs alongside the app container in the same ECS task; locally it is brought up with docker build -f docker/pii.Dockerfile -t sim-pii . and the app is pointed at it via PII_URL=http://localhost:5001. Source: apps/sim/lib/guardrails/README.md:1-40.

The sidecar image bakes in recognizers (a check-digit-validated VIN recognizer plus multi-language NLP) and a Helm chart entry for the sidecar, reflecting release v0.7.13's "publish PII image to GHCR and add Presidio sidecar to Helm chart" work. This is gated behind the PII_URL env / AppConfig feature flag, so the same chart can be installed in environments that do not require redaction. Source: package.json:50-60 (AppConfig client dependency).

Guardrails block

The Guardrails block in the workflow editor composes four validators: JSON validation, regex validation, hallucination detection (RAG + LLM scoring against a knowledge base), and PII detection (Presidio). The first three run in-process; the fourth delegates to the sidecar described above. Source: apps/sim/lib/guardrails/README.md:1-20.

Feature flags and runtime config

Runtime configuration is being migrated from environment variables to AWS AppConfig-backed flags. The root manifest pins @aws-sdk/client-appconfig and the app manifest pins @aws-sdk/client-appconfigdata, indicating a hybrid local-env / remote-flag model that lets enterprise operators toggle capabilities (e.g., PII redaction, data retention) without redeploying. Source: package.json:50-60, apps/sim/package.json:60-70.

Data model: credentials, usage, and auditability

The persisted schema encodes the enterprise boundary. credential records cover four types (oauth, env_workspace, env_personal, service_account), and credentialMember rows model per-user roles and join status with invitedBy attribution. usageLog rows are categorised by usageLogCategoryEnum and usageLogSourceEnum and carry workspaceId, workflowId, and executionId — the same execution identifiers a signed audit trail would need to reference. Source: packages/testing/src/mocks/schema.mock.ts:1-80.

This is precisely the gap RFC #3975 ("Signed audit trail for Sim workflow executions") targets: enterprise deployments need cryptographic guarantees that execution records have not been retroactively edited. The schema's per-execution identifiers and per-credential service-account storage (encryptedServiceAccountKey) are the hooks such an audit layer would attach to. Source: packages/testing/src/mocks/schema.mock.ts:20-40.

Programmatic Surfaces: SDK and CLI

The packages/ts-sdk package publishes a public TypeScript SDK (publishConfig.access: "public", Node ≥ 16) and is the canonical way to embed Sim workflows into other services. Source: packages/ts-sdk/package.json:1-30.

The packages/cli package wraps deployment, seeding, and migration workflows behind commander + inquirer + listr2, and depends on dotenv for environment loading. This is the CLI surface typically used to bootstrap a fresh enterprise install or to drive migrations from CI. Source: packages/cli/package.json:1-30.

The v1 deployment endpoints (added in v0.7.5) and the "gate programmatic workflow execution behind a paid plan" change in v0.7.6 are part of the same program: turning Sim into a callable platform, not just a hosted web app, while reserving programmatic execution for paying workspaces.

Security and Testing

Enterprise deployments depend on a reusable test surface. The @sim/security package isolates security-sensitive utilities and runs under vitest. Source: packages/security/package.json:1-20.

The @sim/testing package exposes semantic assertions (expectBlockExecuted, expectEdgeConnects, expectExecutionOrder, expectRoleCanPerform, expectSocketAccessGranted, expectWorkflowAccessDenied) and fluent builders (WorkflowBuilder.linear(3), ExecutionContextBuilder.createForWorkflow('wf').cancelled().build()) that let CI verify both functional behaviour and permission boundaries on every PR. Source: packages/testing/src/assertions/index.ts:1-30, packages/testing/src/builders/index.ts:1-20.

• packages/testing/src/mocks/schema.mock.ts:1-80 — credential / usage / knowledge-connector table shapes
• packages/testing/src/assertions/index.ts:1-30 — semantic workflow & permission assertions
• packages/testing/src/builders/index.ts:1-20 — fluent WorkflowBuilder / ExecutionContextBuilder]<]minimax[>[

flowchart LR
  subgraph Client
    UI[Web App / Builder]
    SDK[ts-sdk]
    CLI[packages/cli]
  end
  subgraph Sim Platform
    App[Next.js app]
    RT[realtime WebSocket service]
    PII[Presidio PII sidecar]
    AppConfig[AWS AppConfig flags]
  end
  subgraph Data
    PG[(pgvector Postgres)]
    Vault[(External Secrets)]
  end
  UI --> App
  SDK --> App
  CLI --> App
  App <--> RT
  App --> PII
  App --> AppConfig
  App --> PG
  App --- Vault

See Also

• README.md — quickstart, Docker Compose, troubleshooting
• helm/sim/README.md — production Kubernetes deployment values
• apps/sim/lib/guardrails/README.md — Guardrails block and PII sidecar
• scripts/README.md — integration documentation generator
• Related issue: RFC #3975 — Signed audit trail for Sim workflow executions
• Release notes: v0.7.5 (Deployments block), v0.7.6 (programmatic execution gating), v0.7.13 (PII sidecar, workspace retention overrides)

Doramagic Pitfall Log

Found 20 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: RFC: Signed audit trail for Sim workflow executions
• User impact: Developers may fail before the first successful local run: RFC: Signed audit trail for Sim workflow executions
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: RFC: Signed audit trail for Sim workflow executions. Context: Observed when using node
• Evidence: failure_mode_cluster:github_issue | https://github.com/simstudioai/sim/issues/3975

2. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/simstudioai/sim/issues/3975

3. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/simstudioai/sim/issues/5198

4. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/simstudioai/sim

5. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: v0.7.10
• User impact: Upgrade or migration may change expected behavior: v0.7.10
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.7.10. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/simstudioai/sim/releases/tag/v0.7.10

6. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: v0.7.11
• User impact: Upgrade or migration may change expected behavior: v0.7.11
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.7.11. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/simstudioai/sim/releases/tag/v0.7.11

7. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: v0.7.3
• User impact: Upgrade or migration may change expected behavior: v0.7.3
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.7.3. Context: Observed during version upgrade or migration.
• Evidence: failure_mode_cluster:github_release | https://github.com/simstudioai/sim/releases/tag/v0.7.3

8. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: v0.7.4
• User impact: Upgrade or migration may change expected behavior: v0.7.4
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.7.4. Context: Observed when using docker
• Evidence: failure_mode_cluster:github_release | https://github.com/simstudioai/sim/releases/tag/v0.7.4

9. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: v0.7.5
• User impact: Upgrade or migration may change expected behavior: v0.7.5
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.7.5. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/simstudioai/sim/releases/tag/v0.7.5

10. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: v0.7.7
• User impact: Upgrade or migration may change expected behavior: v0.7.7
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.7.7. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/simstudioai/sim/releases/tag/v0.7.7

11. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: v0.7.8
• User impact: Upgrade or migration may change expected behavior: v0.7.8
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.7.8. Context: Observed during version upgrade or migration.
• Evidence: failure_mode_cluster:github_release | https://github.com/simstudioai/sim/releases/tag/v0.7.8

12. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/simstudioai/sim

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using sim with real data or production workflows.

• [[REQUEST] Optional: add an HVTracker trust badge to the README](https://github.com/simstudioai/sim/issues/5198) - github / github_issue
• RFC: Signed audit trail for Sim workflow executions - github / github_issue
• v0.7.13 - github / github_release
• v0.7.12 - github / github_release
• v0.7.11 - github / github_release
• v0.7.10 - github / github_release
• v0.7.9 - github / github_release
• v0.7.8 - github / github_release
• v0.7.7 - github / github_release
• v0.7.6 - github / github_release
• v0.7.5 - github / github_release
• v0.7.4 - github / github_release