Skip to content

Use stable paths

Use this page to give an editor, script or shell a package path that survives upgrades.

Pick a path mode

Package-root paths are content-addressed and change on every upgrade, so never embed them in an IDE config or shell profile. Embed a symlink instead. Four modes cover every case:

Mode Flag Path Auto-install Use case
Package root (default) (none) ~/.ocx/packages/…/<digest>/ no (run ocx package install or ocx package pull first) CI, scripts, one-shot queries
Candidate symlink --candidate ~/.ocx/symlinks/…/candidates/<tag> no Pin a specific tag in editor or IDE config
Current symlink --current ~/.ocx/symlinks/…/current no “Always selected” path in shell profiles or IDE settings
Your own link --link <PATH> <PATH> no A path your build or repository chooses, such as ./.tools/node

All three symlink modes target the package root directly. Consumers traverse one level in: …/content/ for files, …/entrypoints/ for launchers, or …/metadata.json to read the metadata. The current symlink exists only after you run ocx package install --select nodejs/node:22 once, and --current fails until then.

// .vscode/settings.json: path survives every upgrade
{ "eslint.runtime": "~/.ocx/symlinks/ocx.sh/nodejs/node/current/content/bin/node" }
~/.bashrc
# ~/.bashrc: always resolves to the selected version
export PATH="$HOME/.ocx/symlinks/ocx.sh/nodejs/node/current/content/bin:$PATH"

When ocx package install --select nodejs/node:22 runs later, current is re-pointed. The IDE and the shell pick up the new version with no config edits.

When a build tool wants the package at a path of its own, let OCX write the link there:

Terminal window
ocx package install --link ./.tools/node "nodejs/node:24"

The link keeps the package safe from ocx clean for as long as it exists. A link you create yourself with ln -s does not. ocx clean may remove the package behind it. Delete the link when you no longer need the package, and the next ocx clean reclaims it.

For automation, ocx package which prints the resolved package root directly:

Terminal window
ocx package install --select "nodejs/node:24"
ocx package which --current "nodejs/node:24"
ocx package which --candidate "nodejs/node:24"

--candidate, --current and --link fail immediately if the required symlink is absent. They never auto-install, and neither does the default package-root mode: ocx package which locates a package and downloads nothing. A digest component in the identifier is rejected.

How the Windows launcher works

On Windows, ocx package install and ocx package select generate two files per entry point in the package’s entrypoints/ directory:

File Role
<name>.exe Native launcher, the sole Windows entry point for all callers
<name>.shim One-line sidecar carrying the absolute package root

There is no .cmd launcher. .EXE is always present in the default Windows PATHEXT. Bare-name resolution in cmd.exe, PowerShell and Git Bash therefore finds <name>.exe with no PATHEXT configuration.

The .exe launcher reads <name>.shim at invocation time. It then calls CreateProcessW directly to spawn ocx launcher exec, and it does not route through cmd.exe. Caller arguments never pass through a second cmd.exe parse, which closes the BatBadBut / CVE-2024-24576 class of argument-injection vulnerability.

The launcher is unsigned, which does not affect CI, Bazel or dev containers. SmartScreen can warn on an interactive download.

Activate tools with direnv

For direnv-driven projects, ocx direnv init writes an .envrc file that calls ocx direnv export on each cd. The stateless export block is re-evaluated by direnv whenever ocx.toml or ocx.lock changes.

Terminal window
ocx init
ocx add "nodejs/node:24"
ocx direnv init

This routes through the project toolchain, so the binaries on $PATH match the digests locked in ocx.lock. You need no ambient installs and no manual export statements.