v2 standalone session initialization requires undocumented OPENCODE_TEST_HOME inside a workspace-scoped sandbox #52759

Description

OpenCode v2.0.22 cannot initialize a standalone session inside a macOS filesystem sandbox that permits the workspace and standard OpenCode directories but denies workspace parents and unrelated home directories.

Without environment overrides, the TUI fails during startup with HTTP 500. With OPENCODE_DISABLE_PROJECT_CONFIG=1, the TUI starts, but the first message fails with:

Session failed
Instruction initialization blocked by unavailable sources: core/instructions

The session works only after setting the undocumented test variable:

OPENCODE_DISABLE_PROJECT_CONFIG=1 \
OPENCODE_TEST_HOME="$PWD" \
opencode --standalone

A sandbox integration needs --standalone so the private server and tool execution remain inside the same sandbox. It needs a documented production mechanism for bounding configuration and instruction discovery without changing the real HOME.

This is related to #52290, but that report concerns Windows and an existing project without a filesystem sandbox. This report provides a deterministic macOS sandbox reproduction and an OPENCODE_TEST_HOME workaround.

Also related: #36837 and #36990.

Plugins

A nono sandbox integration plugin is installed. Nonfatal parent-directory probes were also observed with OPENCODE_PURE=1, although #36990 notes that v2 may not honor that variable consistently.

OpenCode version

2.0.22

Steps to reproduce

1. Run OpenCode under a macOS Seatbelt sandbox that grants:

   • the current workspace
   • ~/.config/opencode
   • OpenCode cache, data, and state directories

   Deny the workspace parents and unrelated home directories.

2. Run:

   opencode --standalone

   The TUI reports:

   UnknownError: An error occurred in Effect.tryPromise
   [cause]: ClientError: UnexpectedStatus: 500
   

3. Run:

   OPENCODE_DISABLE_PROJECT_CONFIG=1 \
   opencode --standalone

   The TUI starts, but the first message fails with:

   Instruction initialization blocked by unavailable sources: core/instructions
   

4. Run:

   OPENCODE_DISABLE_PROJECT_CONFIG=1 \
   OPENCODE_TEST_HOME="$PWD" \
   opencode --standalone

   The TUI and session work.

Screenshot and/or share link

The macOS sandbox attributes the attempted reads directly to the OpenCode process:

Sandbox: opencode deny file-read-data /Users
Sandbox: opencode deny file-read-data /Users/<user>
Sandbox: opencode deny file-read-data /Users/<user>/Work
Sandbox: opencode deny file-read-data /Users/<user>/.config
Sandbox: opencode deny file-read-data /System

Operating System

macOS 26.6.2

Terminal

iTerm2 with zsh