Skip to main content
The alias is ocx opencode. Put -p, --profile <name> before the native command or arguments. Other arguments are passed to OpenCode subject to the routing rules below.

​
Profile and executable selection

Profile selection is --profile, then OCX_PROFILE, then the global default set with ocx profile use. Missing or unknown selections fail with an actionable error; the current project never chooses a profile. The executable comes from profile bin, then OPENCODE_BIN, then opencode on PATH. OCX checks that it identifies itself as OpenCode 2.0.3 or newer within V2. Help and version requests are forwarded, but still use the selected profile and supported executable. OCX keeps the working directory, forwards terminal input/output, and returns the native process’s exit status. Interrupt and termination signals are forwarded to the launched process. It does not maintain a background daemon pool.

​
Why a private server

Native OpenCode normally connects local clients to a shared service. OCX launches applicable commands with a private native server so the selected profile determines that session’s configuration. See OpenCode’s service documentation. Do not pass --server or disable standalone behavior through OCX. User-wide service administration belongs to the native command directly.

​
Supported routing

These routes are tested against OpenCode 2.0.3: serve runs a foreground profile server. ACP uses native standalone behavior. For mcp add, use the native --global option when you want to target the selected profile rather than the project. In the tested release, these commands lack the routing needed for the profile launcher and are refused:
  • Native agent administration, debug config, and debug agents.
  • plugin list, plugin check, and plugin update.
  • mcp list, mcp auth, and mcp logout.
  • User-wide service, pair, upgrade, update, and uninstall commands.
Use ocx oc --profile work api ... for supported profile API operations, or the native CLI directly for user-wide operations. Running a refused command directly does not make it profile-specific.

​
Configuration and data

OCX points OPENCODE_CONFIG_DIR at the profile and sets native project discovery from projectConfig. OpenCode reads the files itself. Provider credentials, session history, and other native data storage remain shared; a private server is not a separate account or filesystem sandbox. See profiles for instruction discovery, configuration for environment precedence, and troubleshooting for version and routing errors.