Skip to content

Pin a toolchain

By the end of this page a project pins Node.js, teammates and CI run the identical build, and it still builds with no network. It assumes OCX is installed. The same file format pins the tools of a repository and, as $OCX_HOME/ocx.toml, your global toolchain. This page walks through the repository.

Pin and run the tools

Every clone of this repository should build with the same Node.js, with nothing installed machine-wide.

Pin Node.js and run it
Terminal window
mkdir my-project && cd my-project
ocx init
created /home/you/my-project/ocx.toml
Terminal window
ocx add nodejs/node:24
Binding Group Digest
node default sha256:...
Terminal window
ocx exec -- node --version
v24.22.3

ocx add resolved the tag to a digest, wrote ocx.lock and added one line to ocx.toml:

ocx.toml
#:schema https://ocx.sh/schemas/project/v1.json
[tools]
node = "ocx.sh/nodejs/node:24"

Go deeper: project toolchain guide and the project file reference.

Share the pin

A teammate who clones the repository gets your build with one command. Commit both files first. git init starts a repository in this new directory; skip it in an existing one.

Commit the pin
Terminal window
git init
git add ocx.toml ocx.lock
git commit -m "Pin Node.js with ocx"

On a fresh clone, one command downloads the locked packages:

On a fresh clone
Terminal window
ocx pull
ocx exec -- node --version

They run the same bytes you did. Go deeper: lock and reproduce and run project tools.

Use them from your shell

Inside the repository, node is the pinned one. Outside, your shell finds whatever node it found before.

Enter the repository
Terminal window
cd .. && cd my-project
node --version
v24.22.3

This needs the shell hook, which ocx self setup wires into your profile, and your consent, which ocx init and ocx add recorded for this project. The hook puts the locked tools on PATH and sets the variables their packages declare at the next prompt, and takes both away when you leave. Go deeper: shell integration and shell troubleshooting.

Run the same tools in CI

A CI job must refuse a stale lock and build with exactly the locked tools.

CI commands
Terminal window
ocx lock --check
ocx --frozen pull
ocx exec -- node --version

ocx lock --check fails when ocx.toml and ocx.lock disagree. --frozen resolves tags from the local index only and never fetches an unknown tag. Go deeper: GitHub Actions, GitLab CI and unattended CI.

Build without the network

An air-gapped runner, or a laptop on a plane, still builds from what is on disk.

Offline
Terminal window
ocx --offline exec -- node --version
v24.22.3

--offline forbids every network call, so the command works only for packages already downloaded. Go deeper: work offline and corporate mirrors.

Keep tools current

Move to another Node.js version on purpose, never by accident. ocx update re-resolves the tags in ocx.toml into ocx.lock. ocx upgrade moves the tag in ocx.toml itself. Go deeper: update tools, ocx update and ocx upgrade.

Everyday commands

Command What it does
ocx status Show whether the lock matches the project file
ocx add / ocx remove Add or drop a tool in ocx.toml
ocx lock Resolve new or changed tools and rewrite ocx.lock
ocx update Re-resolve tags to their current digests
ocx exec Run a command with the locked tools
ocx --global add Put a tool on PATH in every shell
ocx clean Remove packages no project or install references

Next steps