- docs
- Start here
- Customize the install
Customize the install
This page covers the installer’s options, the supported shells, bare-binary setup, the session PATH and signature checks. It assumes OCX is installed.
Installer script options
The one-liners on the install page are thin per-shell bootstraps served by setup.ocx.sh. Each one detects your platform and resolves the latest release from the dist.json file, with no GitHub API call in the install path. It downloads the archive and verifies its SHA-256 against the manifest. Then it hands off to ocx self setup.
That command does the content-addressed self-install and writes the per-shell $OCX_HOME/env.* files. It also adds a managed block to your shell profile. Last, it registers a session PATH for the processes no profile reaches.
There is one installer per shell. A bash-only one-liner either fails to parse in fish, Nushell, Elvish or PowerShell, or leaves the profile unwired. Each script is written in its own shell’s dialect, so the one-liner parses natively and the managed block lands in the right profile file.
Options
The installer takes a few knobs. Pass them as flags after -s -- (POSIX sh), or as environment variables that work across every shell’s argument-passing quirks.
Skip every PATH modification. If you manage your PATH yourself, in a CI environment or a dotfile framework, pass --no-modify-path. The installer then touches neither your shell profile nor the session PATH:
curl -fsSL https://setup.ocx.sh/sh | sh -s -- --no-modify-pathYou can also set OCX_NO_MODIFY_PATH=1. Either way, add the two directories the installer would have registered to your PATH yourself, toolchain bin first: ~/.ocx/toolchain/active/bin, then ~/.ocx/symlinks/ocx.sh/ocx/cli/current/content/bin.
The flag persists. It writes [shell] modify_path = false to config.toml, so a later ocx self setup run skips both surfaces too until you change the key by hand.
The setting resolves through a four-rung ladder, most specific first:
--no-modify-pathonocx self setup.OCX_NO_MODIFY_PATH, where a truthy value turns modification off.[shell] modify_pathinconfig.toml.- The floor, where modification is allowed.
There is deliberately no --modify-path flag. The opt-out fails safe toward touching less of the machine, so setup only ever writes this key as false. To turn modification back on, set the key to true or remove it by hand.
The key gates the managed block in your profiles and the session PATH registration. It does not gate the env files ($OCX_HOME/env.*), which are written regardless. It merges scalar-wins-if-set across tiers: the nearest tier that sets it wins, in either direction. A managed tier therefore overrides your own $OCX_HOME/config.toml.
[shell]modify_path = falseThe opt-out suppresses both PATH surfaces on all three platforms. One surface is the managed block in your shell profiles. The other is the session-level registration: the Windows user environment, a systemd environment.d drop-in on Linux and a login LaunchAgent on macOS. The writers are never called. Each location still appears in the run summary with outcome skipped_opt_out, so you can see what was not touched.
OCX_NO_MODIFY_PATH follows the truthy rules. Only 1, y, yes, on and true, case-insensitive, enable it. An unrecognized non-empty value such as skip logs a warning and is read as false, so both PATH surfaces are written. An empty string is also false.
With the opt-out set, you give up reaching what no profile reaches. Activation through $OCX_HOME/env.* takes effect only in interactive PowerShell and POSIX shell sessions that source the login profile. The cmd.exe shell, desktop launchers, IDEs and background services never do. To make ocx-managed binaries visible to those, put the two directories above on PATH yourself. Use System Properties or Group Policy on Windows, an environment.d drop-in on Linux, or a LaunchAgent on macOS.
Leave completions to another framework. Set OCX_NO_COMPLETION=1 and ocx self activate skips the shell-completion injection at every shell start. The PATH prepend and the global toolchain environment still run. Use it when completions come from a framework such as oh-my-zsh or a Nix-generated completion store that OCX should not overwrite.
ocx shell completion generates the script regardless, unless it is called with --if-enabled. In that case this variable is the first rung of the policy that decides whether anything is printed.
Choose the profile files. --profile PATH (repeatable) names the shell profiles that receive the managed block. --no-profile writes none. The choice resolves through three rungs: the flags, then [shell] profiles, then the floor, which auto-detects the usual profile files for the current shell.
Absence and an empty list are different answers. An unset key re-detects the profiles on every run. An empty list, the shape --no-profile writes, means no profile blocks at all. A set list replaces auto-detection and is never unioned with it.
Passing either flag writes the key, so the choice applies to every later ocx self setup run, not only the one that typed the flag. --no-profile does not suppress the env files or the session PATH registration. Only modify_path = false (or --no-modify-path) does that. Tiers merge list-wins-if-set: the nearest tier that sets profiles replaces the whole list, a managed tier included. A tier that leaves the key unset never clears a list a lower tier set.
[shell]profiles = ["/home/alice/.bashrc", "/home/alice/.zshrc"]Pin a version. The OCX_INSTALL_VERSION env knob is the portable way to install an exact release. <VERSION> is the semver string with no leading v:
OCX_INSTALL_VERSION=0.5.0 curl -fsSL https://setup.ocx.sh/sh | shFor CI, the pinned, immutable URL is the most explicit form:
curl -fsSL https://setup.ocx.sh/sh/0.5.0 | shPowerShell needs the script compiled to a scriptblock so -Version binds to its parameter:
& ([scriptblock]::Create((Invoke-RestMethod 'https://setup.ocx.sh/pwsh'))) -Version 0.5.0Install a prerelease. The installer without a pin installs the highest stable version and never a prerelease. To install a prerelease, pin its exact version, such as OCX_INSTALL_VERSION=0.7.0-rc1.
Behind a corporate CA. The OCX_INSTALL_CA_BUNDLE env knob points the installer at a corporate root for its own downloads. Export OCX_EXTRA_CA_CERTS beside it. Then ocx self setup persists the certificate text as extra_ca_certs_pem in config.toml, so every later command trusts it too:
export OCX_INSTALL_CA_BUNDLE=/etc/pki/corp-root.pem OCX_EXTRA_CA_CERTS=/etc/pki/corp-root.pemcurl --cacert "$OCX_INSTALL_CA_BUNDLE" -fsSL https://setup.ocx.sh/sh | sh$env:OCX_EXTRA_CA_CERTS = 'C:\pki\corp-root.pem'irm https://setup.ocx.sh/pwsh | iexThe PowerShell installer’s own bootstrap download has no CA-bundle option. Unlike the POSIX installer’s --cacert above, nothing on the PowerShell side hands the corporate root to the script’s HTTPS fetch of the release archive. An OCX_INSTALL_CA_BUNDLE set for it only draws a warning, because the script forwards it as SSL_CERT_FILE, which no Windows client reads. That is why the block above does not set it.
Behind an intercepting proxy, install the root into the machine certificate store for that one download. Or use Download the binary instead to fetch the binary yourself and run ocx self setup directly. OCX_EXTRA_CA_CERTS still reaches ocx self setup in either case, by ordinary environment inheritance. Invoke-Expression/iex runs the downloaded script in the current session, so a variable set with $env: beforehand is visible to it (ocx-sh/www-setup#23).
Supported shells
setup.ocx.sh serves a separate installer per shell. Pipe the sh and fish URLs to their interpreter, and irm … | iex for PowerShell. Nushell and Elvish fetch their script themselves, with nu -c (http get …) and elvish -c (e:curl … | slurp). The POSIX sh installer covers every Bourne-family shell with one script.
| Shell | Installer URL | OS |
|---|---|---|
POSIX sh (bash, zsh, ash, ksh, dash) |
setup.ocx.sh/sh |
|
| PowerShell | setup.ocx.sh/pwsh |
|
| Nushell | setup.ocx.sh/nu |
|
| fish | setup.ocx.sh/fish |
|
| Elvish | setup.ocx.sh/elvish |
Bare-binary setup
The downloaded binary reaches the managed state through ocx self setup. The sections below cover what that command does and how to pin it.
What the setup command does
ocx self setup performs four steps in strict order:
- Bootstraps itself. It installs
ocx.sh/ocx/cli, the stable release unless you pass a version, into the content-addressed object store and wires thecurrentsymlink. The loose binary you downloaded is only needed for this step. Afterwards the managed copy in~/.ocx/takes over. - Writes the env files. It creates
$OCX_HOME/env.sh,env.fish,env.ps1,env.nuandenv.elv. These files are byte-identical across users. - Injects a source line. It adds a managed block to each detected shell profile. Re-running setup is safe, because the fence is idempotent.
- Registers a session
PATH. It writes$OCX_HOME/toolchain/active/binand the OCX installation’sbindirectory behind it into the session store of your platform.
If the bootstrap fails, for example because the registry is unreachable, the command returns a non-zero exit code and writes nothing.
When a profile is a symlink, setup writes the link’s target and leaves the link in place. The profile keeps its permission bits, owner and group. Where a replacement file could not keep the owner or group, OCX writes the existing file in place. A profile that cannot be written, such as one in a read-only directory or behind a dangling link, is skipped and reported with the outcome skipped_unwritable. Setup prints the lines to add by hand as a warning and still exits 0.
Besides the flags covered under Options, ocx self setup accepts these:
| Flag | Effect |
|---|---|
--toolchain-activate MODE |
Writes activate = "MODE" into $OCX_HOME/ocx.toml. MODE is env, bin or none, and it decides how the global toolchain reaches your shell. The file is created with only this key if it does not exist yet. |
--dry-run |
Shows what would be written without writing anything. Use it to preview which profiles are detected. |
--force |
Overwrites a fenced block whose contents were edited by hand. |
Pinned versions
When a job needs the same OCX build on every run, pass a version to ocx self setup. The version can be a tag, a digest, or both:
ocx self setup 0.9.2ocx self setup sha256:ab12cd34ef56...ocx self setup 0.9.2@sha256:ab12cd34ef56...Line 1 pins by tag: it resolves once and installs that release. Line 2 pins by digest, with no tag resolution. Line 3 pins by tag and asserts the exact content (immutability assertion).
The tag@digest form is the strongest guarantee. If the tag ever resolves to different content, for example because a digest was republished, the command fails with exit 65 and names both digests. There is no silent drift.
To get the digest for a version you trust, capture it from a prior run’s JSON output, then write the full pin into your CI config:
digest=$(ocx --format json self setup 0.9.2 | jq -r .bootstrap.digest)echo "ocx self setup 0.9.2@$digest"That digest round-trips. The next ocx self setup 0.9.2@<digest> call succeeds immediately (already_present) if the same version is already installed. Otherwise it downloads and verifies the exact content. When the requested version is already installed, ocx self setup is a no-op and exits 0. It rewrites the env files and managed blocks only when their content has drifted.
jq .status returns the overall run outcome. The bootstrap outcome sits under bootstrap.status and is already_present, pulled or would_pull.
Under --frozen, a tag-only pin resolves from the local index, and exits 81 if the tag is absent. Run ocx index update <package> without --frozen first, because an index update is refused under --frozen too. A digest-only pin works when the blobs are already cached. Both suit hermetic CI where the index is pre-populated.
Session PATH
A shell profile reaches login shells. It does not reach an IDE, a desktop launcher or a background service started outside any shell. Those inherit their environment from the session, and a PATH written into ~/.zshrc never gets there. So ocx self setup writes a session-level registration too, co-primary with the profile block rather than a fallback for it.
Two directories are registered, in this order. A global toolchain that pins ocx is what a session resolves, and the installed binary is the floor beneath it:
$OCX_HOME/toolchain/active/bin, the global toolchain’s trampolines.$OCX_HOME/symlinks/<ocx cli id>/current/content/bin, the directory the installedocxitself resolves from.
Where it is written
Each platform has exactly one store:
| OS | Store | Mechanism |
|---|---|---|
| Windows | HKCU\Environment, value Path |
Written as REG_EXPAND_SZ, then a WM_SETTINGCHANGE broadcast so running applications pick the change up. |
| Linux | $XDG_CONFIG_HOME/environment.d/ocx.conf (~/.config/environment.d/ocx.conf when XDG_CONFIG_HOME is unset) |
One environment.d line, PATH=…:$PATH. It is a prepend, so nothing another tool put on PATH is displaced. |
| macOS | ~/Library/LaunchAgents/sh.ocx.path.plist |
A RunAtLoad LaunchAgent labelled sh.ocx.path, published at mode 0644 (launchd refuses an agent with “dubious permissions”) and bootstrapped into the current GUI domain. |
The registration is idempotent by presence test, never by append. A second ocx self setup reports unchanged and the stored value does not grow.
A write failure is a warning, not an exit code. A store that cannot be written is reported and warned about, and setup still exits 0. Re-running retries it.
The one fatal refusal is an $OCX_HOME this platform’s format cannot spell. On Windows that is a % or ;. For environment.d it is a character the format cannot carry, and for the plist it is a ". That is checked before anything is written, so a refused run leaves the machine byte-identical and exits 78.
environment.d is read only by processes started under systemd --user. That is confirmed for GNOME and KDE Plasma Wayland. Neither LightDM (by default), SDDM nor a non-systemd desktop reads it. A Flatpak- or Snap-sandboxed application takes its PATH from the sandbox instead.
~/.pam_environment is deliberately not written, since it has been deprecated since pam_env 1.5.0. On every platform, terminals and applications that are already open see nothing until they are restarted.
Removing the session PATH
There is no ocx self uninstall yet (#413), so the registration is reversed by hand. One location per platform:
# Open the built-in editor, remove the two ocx segments from the user Path, and# save. Saving preserves the value's type and broadcasts the settings change,# which is why this is the recommended route.rundll32 sysdm.cpl,EditEnvironmentVariables
# Or from PowerShell, through the registry API rather than [Environment]:# [Environment]::SetEnvironmentVariable(..., 'User') always writes REG_SZ,# no matter what type the value had before. That is a permanent downgrade:# no %VAR% any tool adds to Path later will ever expand again. The registry# API below reads the value unexpanded and writes back the same type it read.# Unlike the built-in editor, it does not broadcast WM_SETTINGCHANGE, so# already-open terminals need a restart.# Read $root from a guarded expression, never bare $env:OCX_HOME: an empty# prefix would match every segment and strip the whole PATH.$root = if ($env:OCX_HOME) { $env:OCX_HOME } else { Join-Path $HOME '.ocx' }$key = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment', $true)$path = $key.GetValue('Path', '', 'DoNotExpandEnvironmentNames')$kept = ($path -split ';' | Where-Object { $_ -and -not $_.StartsWith($root, 'OrdinalIgnoreCase') }) -join ';'$key.SetValue('Path', $kept, 'ExpandString')$key.Close()rm ~/.config/environment.d/ocx.confOr $XDG_CONFIG_HOME/environment.d/ocx.conf when that variable is set. The change takes effect at the next login; the current session keeps its PATH.
Boot out the service, then delete its plist.
launchctl bootout "gui/$(id -u)/sh.ocx.path"rm ~/Library/LaunchAgents/sh.ocx.path.plistOCX’s own writer does not treat the two directions the same way. Registering the entries (ocx self setup) always writes REG_EXPAND_SZ, even over an existing REG_SZ value, because rustup once shipped REG_SZ here and broke %VAR% expansion for every other entry already on Path. Deregistering them preserves whatever type it read. Removal never promises to upgrade or downgrade a value it is not otherwise touching.
Both directions read the value unexpanded, so a foreign %…% reference already on Path is never flattened into whatever it resolves to at that moment. The built-in editor is the one form that both preserves the type and broadcasts the change.
Reversing the session PATH does not remove OCX. The managed shell-profile block, the $OCX_HOME/env.* env files and $OCX_HOME itself stay in place. The uninstall recipe covers them. Neither recipe touches a project’s own rendered toolchain. Delete .ocx/toolchain/, or the toolchain_dir root if one is configured, in every project where you have run ocx pull.
Verify the package signature
The release workflow signs every platform of ocx.sh/ocx/cli with a keyless Sigstore signature and attaches a CycloneDX SBOM. A downloaded archive carries a checksum, and the signed package ties the bytes to the workflow that built them.
ocx package verify checks the signature against the identity of that workflow. Without -p, the command resolves the host platform as ocx package install does:
ocx package verify ocx.sh/ocx/cli:<version> \ --certificate-identity https://github.com/ocx-sh/ocx/.github/workflows/release.yml@refs/heads/main \ --certificate-oidc-issuer https://token.actions.githubusercontent.comThe identity above is the release workflow. A version released before signing began carries its signature from the backfill workflow, so verify it with --certificate-identity https://github.com/ocx-sh/ocx/.github/workflows/backfill.yml@refs/heads/main instead.
Replace <version> with a release tag. ocx package sbom lists the attached SBOM and takes the same two flags to verify its signature:
ocx package sbom ocx.sh/ocx/cli:<version> \ --certificate-identity https://github.com/ocx-sh/ocx/.github/workflows/release.yml@refs/heads/main \ --certificate-oidc-issuer https://token.actions.githubusercontent.comPin the identity once instead of passing it on every call, as Trust signers with a policy describes.
Dev builds
Binaries published to the dev channel by the release workflow carry a channel: dev field and a version string with a build-metadata suffix, such as 0.3.2-dev+20260528143045. These are snapshot builds, not stable releases.
To identify whether your installed binary is a dev build, run:
ocx version --verboseThe channel: dev line appears in the verbose output when present. For scripting, read the report as JSON and pipe it through jq .channel:
ocx --format json versionThe channel field reads "dev" for dev builds and is absent for stable releases, so jq .channel prints null there. Include this output when filing bug reports. It helps distinguish issues introduced between stable releases.