feat(opencode): add optional runtime overlay

simstudioai · Danigm-dev · Mar 25, 2026 · Mar 25, 2026 · Mar 25, 2026 · Mar 25, 2026
commit 314656246e2a2dbf6855c5aba80ba7e057cf8305
diff --git a/README.md b/README.md
@@ -63,13 +63,126 @@ Docker must be installed and running on your machine.
 
 ### Self-hosted: Docker Compose
 
+For local Docker builds, use the local compose file:
+
+```bash
+git clone https://github.com/simstudioai/sim.git && cd sim
+docker compose -f docker-compose.local.yml up -d --build
+```
+
+For a cloud or production-style deployment, use the published images:
+
 ```bash
 git clone https://github.com/simstudioai/sim.git && cd sim
 docker compose -f docker-compose.prod.yml up -d
 ```
 
 Open [http://localhost:3000](http://localhost:3000)
 
+#### OpenCode Setup
+
+OpenCode is opt-in. By default the `OpenCode` block stays hidden so the base Sim UX and deployment path remain unchanged.
+
+Minimum setup:
+
+```bash
+cp apps/sim/.env.example apps/sim/.env
+```
+
+Then add these values to `apps/sim/.env`:
+
+```env
+NEXT_PUBLIC_OPENCODE_ENABLED=true
+OPENCODE_SERVER_USERNAME=opencode
+OPENCODE_SERVER_PASSWORD=change-me
+OPENCODE_REPOS=https://github.com/octocat/Hello-World.git
+
+# Pick at least one provider key that OpenCode can use
+GEMINI_API_KEY=your-gemini-key
+# or OPENAI_API_KEY=...
+# or ANTHROPIC_API_KEY=...
+```
+
+If you want private repositories:
+
+```env
+# Generic HTTPS or Azure Repos
+GIT_USERNAME=your-user-or-email
+GIT_TOKEN=your-token-or-pat
+
+# Optional GitHub-only fallback
+GITHUB_TOKEN=your-github-token
+```
+
+Important:
+
+- The `OpenCode` block remains hidden unless `NEXT_PUBLIC_OPENCODE_ENABLED=true` is set on the Sim app.
+- `docker compose` reads environment from the shell, not from `apps/sim/.env` automatically.
+- If you want the app and the OpenCode runtime to use the same credentials, load that file before starting compose:
+
+```bash
+set -a
+source apps/sim/.env
+set +a
+docker compose -f docker-compose.local.yml -f docker-compose.opencode.local.yml up -d --build
+```
+
+Local vs production behavior:
+
+- `docker-compose.local.yml`
+  - remains unchanged
+- `docker-compose.opencode.local.yml`
+  - adds OpenCode locally without changing the base local compose file
+  - publishes `OPENCODE_PORT` to the host so `next dev` on the host can talk to OpenCode
+  - defaults `OPENCODE_SERVER_USERNAME=opencode`
+  - defaults `OPENCODE_SERVER_PASSWORD=dev-opencode-password` if you do not set one explicitly
+- `docker-compose.prod.yml`
+  - contains the upstream-style base deployment only
+- `docker-compose.opencode.yml`
+  - adds the `opencode` service as a production overlay
+  - builds the OpenCode runtime locally from this repository instead of requiring an official Sim-hosted image
+  - injects the required `NEXT_PUBLIC_OPENCODE_ENABLED` and `OPENCODE_*` variables into `simstudio`
+  - keeps OpenCode internal to the Docker network with `expose`, not a published host port
+  - expects `OPENCODE_SERVER_PASSWORD` to be set explicitly
+
+Production deploy command:
+
+```bash
+docker compose -f docker-compose.prod.yml -f docker-compose.opencode.yml up -d --build
+```
+
+For local hot reload with `next dev` on the host, also set this in `apps/sim/.env`:
+
+```env
+OPENCODE_BASE_URL=http://127.0.0.1:4096
+```
+
+Then start only the optional OpenCode runtime:
+
+```bash
+docker compose -f docker-compose.local.yml -f docker-compose.opencode.local.yml up -d --build opencode
+```
+
+Without that override, host-side Next.js cannot reliably reach the Docker service alias.
+
+Notes:
+
+- If `OPENCODE_REPOS` is empty, `opencode` still starts but no repositories are cloned.
+- Repositories are cloned into `/app/repos/<repo-name>`.
+- Private Azure Repos must use `https` plus `GIT_USERNAME` and `GIT_TOKEN`; the container will not prompt interactively for passwords.
+- `GOOGLE_GENERATIVE_AI_API_KEY` is optional; the optional overlays map it automatically from `GEMINI_API_KEY` if not set.
+- If you prefer to run OpenCode in separate infrastructure, skip the overlays and point Sim at that deployment with `OPENCODE_BASE_URL`, `OPENCODE_SERVER_USERNAME`, and `OPENCODE_SERVER_PASSWORD`.
+
+Basic verification after startup:
+
+```bash
+curl -u "opencode:change-me" http://127.0.0.1:4096/global/health
+```
+
+If you changed the username, password, or port, use those values instead.
+
+See [`docker/opencode/README.md`](docker/opencode/README.md) for service-specific verification steps and runtime behavior.
+
 #### Using Local Models with Ollama
 
 Run Sim with local AI models using [Ollama](https://ollama.ai) - no external APIs required:
@@ -136,6 +249,26 @@ cp packages/db/.env.example packages/db/.env
 # Edit both .env files to set DATABASE_URL="postgresql://postgres:your_password@localhost:5432/simstudio"
 ```
 
+If you want to use the OpenCode workflow block while running `next dev` on the host, also set these in `apps/sim/.env`:
+
+```env
+NEXT_PUBLIC_OPENCODE_ENABLED=true
+OPENCODE_BASE_URL=http://127.0.0.1:4096
+OPENCODE_SERVER_USERNAME=opencode
+OPENCODE_SERVER_PASSWORD=change-me
+OPENCODE_REPOS=https://github.com/octocat/Hello-World.git
+GEMINI_API_KEY=your-gemini-key
+```
+
+Then export the same environment before starting the OpenCode container so the app and Docker use identical credentials:
+
+```bash
+set -a
+source apps/sim/.env
+set +a
+docker compose -f docker-compose.local.yml -f docker-compose.opencode.local.yml up -d --build opencode
+```
+
 4. Run migrations:
 
 ```bash
@@ -146,9 +279,10 @@ cd packages/db && bunx drizzle-kit migrate --config=./drizzle.config.ts
 
 ```bash
 bun run dev:full  # Starts both Next.js app and realtime socket server
+bun run dev:full:webpack  # Same, but using Webpack instead of Turbopack
 ```
 
-Or run separately: `bun run dev` (Next.js) and `cd apps/sim && bun run dev:sockets` (realtime).
+Or run separately: `bun run dev` (Next.js/Turbopack), `cd apps/sim && bun run dev:webpack` (Next.js/Webpack), and `cd apps/sim && bun run dev:sockets` (realtime).
 
 ## Copilot API Keys
 

diff --git a/apps/sim/.env.example b/apps/sim/.env.example
@@ -29,6 +29,25 @@ API_ENCRYPTION_KEY=your_api_encryption_key # Use `openssl rand -hex 32` to gener
 # VLLM_BASE_URL=http://localhost:8000    # Base URL for your self-hosted vLLM (OpenAI-compatible)
 # VLLM_API_KEY=                          # Optional bearer token if your vLLM instance requires auth
 
+# Internal OpenCode Service (Optional, opt-in)
+# NEXT_PUBLIC_OPENCODE_ENABLED=true         # Required to show the OpenCode block in the UI
+#                                           # Leave unset to keep the block hidden and preserve the default Sim UX
+# OPENCODE_BASE_URL=http://127.0.0.1:4096   # Use this when SIM runs on the host (for example, `bun run dev`) and OpenCode runs in Docker
+# OPENCODE_BASE_URL=http://opencode:4096    # Use this when SIM and OpenCode both run in Docker Compose
+#                                           # Or point this to any separate OpenCode deployment that implements the same auth contract
+# OPENCODE_PORT=4096
+# OPENCODE_SERVER_USERNAME=opencode
+# OPENCODE_SERVER_PASSWORD=change-me  # Required for the internal OpenCode service
+# OPENCODE_REPOS=https://github.com/org/ui-components,https://github.com/org/design-tokens
+# OPENCODE_REPOS=https://dev.azure.com/org/project/_git/repo  # Azure Repos over HTTPS also works
+# GIT_USERNAME=                       # Optional HTTPS git username for private repos, including Azure Repos
+# GIT_TOKEN=                          # Optional HTTPS git token/PAT for private repos, including Azure Repos
+# GITHUB_TOKEN=                       # Optional GitHub token fallback for private GitHub repos
+# OPENAI_API_KEY=                     # OpenCode can use any supported provider key from the environment
+# ANTHROPIC_API_KEY=                  # Optional if you prefer Anthropic for OpenCode
+# GEMINI_API_KEY=                     # Optional if you prefer Gemini for OpenCode
+# GOOGLE_GENERATIVE_AI_API_KEY=       # Optional explicit alias for OpenCode's Google provider; defaults from GEMINI_API_KEY in the optional compose overlays
+
 # Admin API (Optional - for self-hosted GitOps)
 # ADMIN_API_KEY=  # Use `openssl rand -hex 32` to generate. Enables admin API for workflow export/import.
                   # Usage: curl -H "x-admin-key: your_key" https://your-instance/api/v1/admin/workspaces
diff --git a/apps/sim/blocks/blocks/opencode.ts b/apps/sim/blocks/blocks/opencode.ts
@@ -1,7 +1,10 @@
-import { OpenCodeIcon } from '@/components/icons'
 import type { BlockConfig } from '@/blocks/types'
+import { OpenCodeIcon } from '@/components/icons'
+import { getEnv, isTruthy } from '@/lib/core/config/env'
 import type { OpenCodePromptResponse } from '@/tools/opencode/types'
 
+const isOpenCodeEnabled = isTruthy(getEnv('NEXT_PUBLIC_OPENCODE_ENABLED'))
+
 function coerceBoolean(value: unknown): boolean {
   if (typeof value === 'boolean') {
     return value
@@ -92,6 +95,7 @@ export const OpenCodeBlock: BlockConfig<OpenCodePromptResponse> = {
   category: 'tools',
   bgColor: '#111827',
   icon: OpenCodeIcon,
+  hideFromToolbar: !isOpenCodeEnabled,
   subBlocks: [
     {
       id: 'repository',

diff --git a/apps/sim/lib/core/config/env.ts b/apps/sim/lib/core/config/env.ts
@@ -413,6 +413,7 @@ export const env = createEnv({
     NEXT_PUBLIC_DISABLE_PUBLIC_API:        z.boolean().optional(),                   // Disable public API access UI toggle globally
     NEXT_PUBLIC_INBOX_ENABLED:             z.boolean().optional(),                   // Enable inbox (Sim Mailer) on self-hosted
     NEXT_PUBLIC_EMAIL_PASSWORD_SIGNUP_ENABLED: z.boolean().optional().default(true), // Control visibility of email/password login forms
+    NEXT_PUBLIC_OPENCODE_ENABLED:          z.boolean().optional(),                   // Show the OpenCode block and related UI when a compatible runtime is configured
     NEXT_PUBLIC_TURNSTILE_SITE_KEY:        z.string().min(1).optional(),           // Cloudflare Turnstile site key for captcha widget
   },
 
@@ -447,6 +448,7 @@ export const env = createEnv({
     NEXT_PUBLIC_DISABLE_PUBLIC_API: process.env.NEXT_PUBLIC_DISABLE_PUBLIC_API,
     NEXT_PUBLIC_INBOX_ENABLED: process.env.NEXT_PUBLIC_INBOX_ENABLED,
     NEXT_PUBLIC_EMAIL_PASSWORD_SIGNUP_ENABLED: process.env.NEXT_PUBLIC_EMAIL_PASSWORD_SIGNUP_ENABLED,
+    NEXT_PUBLIC_OPENCODE_ENABLED: process.env.NEXT_PUBLIC_OPENCODE_ENABLED,
     NEXT_PUBLIC_TURNSTILE_SITE_KEY: process.env.NEXT_PUBLIC_TURNSTILE_SITE_KEY,
     NEXT_PUBLIC_E2B_ENABLED: process.env.NEXT_PUBLIC_E2B_ENABLED,
     NEXT_PUBLIC_COPILOT_TRAINING_ENABLED: process.env.NEXT_PUBLIC_COPILOT_TRAINING_ENABLED,