Skip to main content

​
Usage

​
Description

Launch OpenCode with resolved configuration and profile support. OCX merges profile settings, discovers instruction files, applies pattern filtering, and spawns OpenCode with the final configuration.

​
Flags

-p/--profile, -v/--verbose, and --no-rename are OCX-owned flags. Other arguments and flags pass through to OpenCode. Use -- to pass OpenCode flags that conflict with OCX (e.g., ocx oc -- --help forwards help to OpenCode).

​
Examples

​
Launch with Default Profile

​
Launch with Specific Profile

​
Skip Window Renaming

​
Use Environment Variable

​
Use the Short Alias

​
Pass Flags to OpenCode

​
Profile Resolution Priority

Profiles are resolved in this order (first match wins):
  1. profile field in .opencode/ocx.jsonc — Project-specific profile
  2. --profile / -p flag — Explicit CLI specification
  3. OCX_PROFILE environment variable — Session-level profile
  4. default profile — If it exists
  5. No profile — Base configurations only

​
How It Works

  1. Profile Resolution: Resolves profile using the priority order above.
  2. Instruction Discovery: Discovers instruction files in priority order.
  3. Pattern Filtering: Applies exclude/include patterns from profile.
  4. Launch OpenCode: Spawns with profile configuration and discovered instructions.
Registry Isolation: Global base config registries (~/.config/opencode/ocx.jsonc) are only used for downloading profiles, never for components. When using a profile, registries come from the profile config. This isolation prevents global registries from injecting components into all projects.

​
Prepared Profile Cache

Profile launches retain their merged configuration and OpenCode-managed dependencies under $XDG_CACHE_HOME/ocx/opencode/v1 (default: ~/.cache/ocx/opencode/v1; relative XDG paths are ignored). Unchanged source inputs reuse the same installation directory. Changes to effective files, visibility policies, project identity, or the OpenCode executable/version select a new generation. OCX continues resolving launch settings into OPENCODE_CONFIG_CONTENT each time. Concurrent sessions lease separate persistent slots within a generation, so dependency installation cannot race in a shared directory. Exiting releases the slot and retains its manifest, lockfiles, and node_modules. OCX never installs these dependencies itself or copies source node_modules. Profile symlinks are snapshotted after overlay validation so generated files cannot write through them into the source profile. Inactive slots unused for 30 days are pruned at most once daily when that profile/project identity is prepared again; active leases are retained. Interrupted launcher leases are conservatively left unavailable until pruning. Cache contents are rebuildable and can be removed while no launches are using them. Custom launchers that reject, time out, or return no version for --version still launch with the requested arguments. OCX uses a fresh cache generation for these launches because dependency compatibility cannot be verified without the OpenCode version.

​
Custom OpenCode Binary

To use a custom OpenCode binary, set the bin option in your profile’s ocx.jsonc:
Resolution order:
  1. bin in profile’s ocx.jsonc
  2. OPENCODE_BIN environment variable
  3. opencode (system PATH)

​
See Also