feat(opencode): add optional runtime overlay

PR-3761-BRANCH-STATUS.md

@@ -0,0 +1,136 @@
+# PR 3761 Branch Status
+
+## Purpose
+
+This note describes what each relevant branch contains and how responsibilities are split, so it is easier to see where changes overlap.
+
+PR: `https://github.com/simstudioai/sim/pull/3761`
+
+## Branches
+
+### `staging`
+
+Base branch for PR `#3761`.
+
+What it contains:
+
+- current shared integration baseline before OpenCode optional runtime lands
+- current default compose and deployment behavior
+- no PR-specific branch-only review fixes from this worktree
+
+What it does **not** contain yet:
+
+- the OpenCode branch work described below until PR `#3761` is merged
+
+### `feat/opencode-optional-runtime`
+
+Feature branch for PR `#3761`.
+
+Primary responsibility:
+
+- add the OpenCode integration and its optional runtime overlay without changing the existing default local/prod setups
+
+What it contains:
+
+- OpenCode block in Sim
+- OpenCode tools
+- OpenCode API routes
+- `apps/sim/lib/opencode`
+- wiring for `@opencode-ai/sdk` in Next/Vitest
+- async dropdown/combobox support needed by the integration
+- optional runtime files under `docker/opencode/`
+- `docker-compose.opencode.yml`
+- `docker-compose.opencode.local.yml`
+- deployment/runtime hardening for:
+  - `OPENCODE_REPOSITORY_ROOT`
+  - `OPENCODE_SERVER_PASSWORD`
+  - retry/session handling
+  - route error behavior
+  - OpenCode runtime config guards
+
+What this branch intentionally preserves:
+
+- `docker-compose.local.yml` stays as the default local setup
+- `docker-compose.prod.yml` stays as the default production setup
+- OpenCode remains hidden by default behind `NEXT_PUBLIC_OPENCODE_ENABLED`
+
+### `origin/feat/opencode-optional-runtime`
+
+Remote branch backing PR `#3761`.
+
+Expected relationship:
+
+- should match local `feat/opencode-optional-runtime`
+- if local and remote diverge, local work has not been pushed yet or remote changed externally
+
+## Overlap And Boundaries
+
+### Product / app layer
+
+Owned here in `feat/opencode-optional-runtime`:
+
+- OpenCode block/tool/route/lib implementation
+- editor support required by the OpenCode selectors
+
+Possible overlap area:
+
+- shared editor components like dropdown/combobox
+- these are not OpenCode-only files, but this branch touches them only where needed for OpenCode async option behavior
+
+### Runtime / deployment layer
+
+Owned here in `feat/opencode-optional-runtime`:
+
+- optional OpenCode container/runtime bootstrap
+- optional compose overlays
+
+Boundary:
+
+- this branch should not replace the default local/prod compose files as the main path
+- it only adds overlays and guards around the optional runtime
+
+### Review-fix layer
+
+Many follow-up changes in this branch are not separate features.
+
+They are:
+
+- hardening fixes
+- correctness fixes
+- small refactors
+- review-driven adjustments on top of the same OpenCode feature branch
+
+That means several files now contain both:
+
+- original feature work
+- later review fixes
+
+So if something feels like it is "overlapping", that is expected: the branch has accumulated refinement passes on top of the original OpenCode implementation rather than splitting them into separate branches.
+
+## Final Branch State
+
+At the end of this session:
+
+- current branch: `feat/opencode-optional-runtime`
+- base branch: `staging`
+- remote tracking branch: `origin/feat/opencode-optional-runtime`
+- local/remote divergence: none
+- worktree state: clean
+
+## Practical Reading Guide
+
+If you want to understand the branch quickly, read it in this order:
+
+1. `apps/sim/lib/opencode/`
+2. `apps/sim/app/api/opencode/`
+3. `apps/sim/app/api/tools/opencode/`
+4. `apps/sim/blocks/blocks/opencode.ts`
+5. `docker/opencode/`
+6. `docker-compose.opencode.yml`
+7. `docker-compose.opencode.local.yml`
+
+If you want to understand where overlap happened, check these shared files next:
+
+- `apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/components/sub-block/components/combobox/combobox.tsx`
+- `apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/components/sub-block/components/dropdown/dropdown.tsx`
+- `apps/sim/app/api/tools/opencode/prompt/route.ts`

README.md

@@ -63,13 +63,160 @@ 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.
+
+Quick deploy paths:
+
+##### Sim only
+
+- Do not set `NEXT_PUBLIC_OPENCODE_ENABLED`.
+- Do not set any `OPENCODE_*` variables.
+- Do not use `docker-compose.opencode.yml` or `docker-compose.opencode.local.yml`.
+- Start Sim with the normal upstream flow.
+
+##### Sim + OpenCode local overlay
+
+- Set `NEXT_PUBLIC_OPENCODE_ENABLED=true`.
+- Set `OPENCODE_SERVER_USERNAME` and `OPENCODE_SERVER_PASSWORD`.
+- Set `OPENCODE_REPOSITORY_ROOT=/app/repos` unless you intentionally changed the runtime root.
+- Set `OPENCODE_REPOS` to one or more HTTPS repository URLs.
+- Set at least one provider key such as `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, or `GOOGLE_GENERATIVE_AI_API_KEY`.
+- Set `GIT_USERNAME` and `GIT_TOKEN` or `GITHUB_TOKEN` if any repository is private.
+- For host-side `next dev`, also set `OPENCODE_BASE_URL=http://127.0.0.1:4096`.
+- Start with `docker compose -f docker-compose.local.yml -f docker-compose.opencode.local.yml up -d --build`.
+
+##### Sim + external OpenCode runtime
+
+- Set `NEXT_PUBLIC_OPENCODE_ENABLED=true`.
+- Set `OPENCODE_BASE_URL` to the external OpenCode server.
+- Set `OPENCODE_SERVER_USERNAME` and `OPENCODE_SERVER_PASSWORD` to the credentials expected by that server.
+- Set `OPENCODE_REPOSITORY_ROOT` to the same worktree root used by the external OpenCode deployment.
+- Set `OPENCODE_REPOS` to the repository catalog you expect the runtime to clone or expose.
+- Ensure the external runtime already has at least one provider key configured.
+- Ensure the external runtime can clone private repositories with the right git credentials if needed.
+- Verify `/global/health` and one real prompt before exposing the block to users.
+
+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_REPOSITORY_ROOT=/app/repos
+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_REPOSITORY_ROOT=/app/repos`
+  - 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
+  - defaults `OPENCODE_REPOSITORY_ROOT=/app/repos`
+  - requires `OPENCODE_SERVER_PASSWORD` to be set explicitly before `docker compose` starts
+
+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 `${OPENCODE_REPOSITORY_ROOT:-/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`, `OPENCODE_SERVER_PASSWORD`, and the matching `OPENCODE_REPOSITORY_ROOT`.
+
+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 +283,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 +313,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
 

apps/sim/.env.example

@@ -29,6 +29,26 @@ 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_REPOSITORY_ROOT=/app/repos       # Must match the repository root used by the OpenCode runtime, including external deployments
+# 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