Installation & Setup
Relevant source files
The following files were used as context for generating this wiki page:
OCX provides multiple pathways for installation and project initialization, ranging from automated shell scripts to manual builds from source. The setup process is designed to handle platform detection, environment configuration, and global profile initialization to ensure a seamless developer experience across macOS, Linux, and Windows. Sources: README.md:16-18, packages/cli/scripts/install.sh
Automated Installation
The primary method for installing OCX on Unix-like systems (macOS and Linux) is via an automated shell script. This script automates platform detection, version resolution, binary downloading, and checksum verification. Sources: packages/cli/scripts/install.sh:8-12, README.md:20-22
Platform and Architecture Detection
The installer identifies the operating system and CPU architecture to fetch the correct binary. It specifically handles Rosetta 2 on macOS and identifies the need for baseline builds if AVX2 instructions are missing. Sources: packages/cli/scripts/install.sh:58-106
| Parameter | Supported Values |
|---|---|
| OS | darwin, linux, windows |
| Architecture | arm64, x64 |
| libc | glibc, musl (Alpine Linux) |
| Optimization | standard, baseline (No AVX2) |
Sources: packages/cli/scripts/install.sh:58-120
Installation Flow
The following diagram illustrates the sequence of operations performed by the install.sh script:
The script uses curl with built-in retries and verifies the integrity of the downloaded binary against a .sha256 manifest. Sources: packages/cli/scripts/install.sh:163-220
Package Manager Installation
For cross-platform support (including Windows) or for users preferring JavaScript package managers, OCX can be installed via npm. Sources: README.md:23-25
# Global installation via npm
npm install -g ocx
Project Initialization
Once the CLI is installed, projects must be initialized to utilize OCX features. Initialization can target either a local project or global configuration profiles. Sources: README.md:52-54, AGENTS.md:154-156
Local Project Initialization
Running ocx init creates the necessary directory structure for managing components within a specific repository. Sources: README.md:52-54, AGENTS.md:154-156
ocx init
Global Profile Initialization
Global profiles allow for portable configurations that work across any repository without modifying the repository itself. Initialization of the global environment is required before creating profiles. Sources: README.md:104-106, AGENTS.md:160-162
ocx init --global
Setup from Source (Development)
Developers contributing to OCX or building custom binaries follow a different setup path using the Bun runtime (v1.3.5+). Sources: AGENTS.md:6-10, CONTRIBUTING.md:46-52
Prerequisites
- Runtime: Bun v1.3.5+
- Build System: Turbo
- Language: TypeScript (Strict Mode)
Sources: AGENTS.md:6-11, examples/registry-starter/AGENTS.md:10-12
Build Commands
To set up the development environment, clone the repository and install dependencies using Bun: Sources: CONTRIBUTING.md:46-52
git clone https://github.com/kdcokenny/ocx
cd ocx
bun install
# Build all packages
bun run build
# Build CLI specifically
cd packages/cli
bun run scripts/build.ts
Sources: CONTRIBUTING.md:54-61, AGENTS.md:14-20
Environment Configuration
OCX utilizes specific environment variables to override default behaviors and manage profile selection. Sources: AGENTS.md:107-110, README.md:204-208
| Variable | Description |
|---|---|
OCX_PROFILE | Sets the active profile, bypassing the default selection. |
OPENCODE_BIN | Specifies a custom path to the OpenCode binary. |
OCX_VERSION | Used by the installer to force a specific version. |
OCX_INSTALL | Used by the installer to set a custom installation directory. |
Sources: README.md:204-208, packages/cli/scripts/install.sh:11-13, AGENTS.md:139-142
Configuration Cascade
OCX merges configuration from multiple levels. The setup follows this priority order (highest to lowest):
- Command line flags (e.g.,
-p profile_name) - Environment variables (
OCX_PROFILE) - Profile-specific configuration (
~/.config/opencode/profiles/) - Global base configuration (
~/.config/opencode/ocx.jsonc) - Local project configuration (
.opencode/ocx.jsonc)
Sources: AGENTS.md:112-120, README.md:121-125
Verification
After installation and setup, the configuration can be verified using the following commands: Sources: AGENTS.md:154-159, README.md:136-140
# Verify CLI is in PATH and working
ocx --help
# Show the current merged configuration and its sources
ocx config show --origin
Installation is considered successful when the ocx binary is executable and the global or local ocx.jsonc files are correctly resolved. Sources: README.md:136-140, packages/cli/scripts/install.sh:317-320