- docs
- Start here
- Pin a toolchain
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.
mkdir my-project && cd my-projectocx initcreated /home/you/my-project/ocx.tomlocx add nodejs/node:24Binding Group Digestnode default sha256:...ocx exec -- node --versionv24.22.3ocx add resolved the tag to a digest, wrote ocx.lock and added one line to 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.
git initgit add ocx.toml ocx.lockgit commit -m "Pin Node.js with ocx"On a fresh clone, one command downloads the locked packages:
ocx pullocx exec -- node --versionThey 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.
cd .. && cd my-projectnode --versionv24.22.3This 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.
ocx lock --checkocx --frozen pullocx exec -- node --versionocx 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.
ocx --offline exec -- node --versionv24.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
- Put a tool on your
PATHeverywhere with the global toolchain. - Publish your own tool to any OCI registry.
- Provision Bazel or a dev container with the same pin. The OCX VS Code extension, also on Open VSX, brings the toolchain into your editor.
- Build container images with the locked tools.
- Install a package.