- integrations
- Dev Containers
- Guides
- Restore the project toolchain on create
Restore the project toolchain on create
This page shows how to get the tools pinned in your project’s ocx.toml into a dev container.
Afterwards, ocx exec -- <tool> and a bare <tool> in a new terminal run the locked version.
The restore needs no option: the default feature entry does it.
The options pull and pullGroups change it.
What the restore does
After the container is created, the feature runs ocx pull as the remote user in the workspace folder.
The command reads ocx.toml and ocx.lock and fetches the locked tools into the private store ~/.ocx of that user.
The result depends on which project files exist.
| Project files in or above the workspace | What happens |
|---|---|
No ocx.toml |
Nothing. The feature stays silent. |
ocx.toml and ocx.lock |
The locked tools are fetched. |
ocx.toml without ocx.lock |
A warning is printed and the container still starts. |
The restore never fails container creation. A Codespaces prebuild runs the same step, so a prebuild already holds the tools.
Commit the project files
Commit both ocx.toml and ocx.lock.
The lock pins each tool to an exact digest, so every container restores the same builds.
{ "image": "mcr.microsoft.com/devcontainers/base:ubuntu", "features": { "ghcr.io/ocx-sh/devcontainer-features/ocx:1": {} }}With both files in the workspace, run the pinned tool after the container starts.
$ ocx exec -- jq --versionjq-1.8.2A missing lock prints this warning during creation.
Run ocx lock in the project, commit ocx.lock, and rebuild.
ocx-feature: warning: ocx pull failed with exit code 78. attempted: /usr/local/bin/ocx pull fix: run "ocx lock" in the project and commit ocx.lockRestore specific groups
Tools in ocx.toml live in the top-level [tools] table, the default group, or in named [group.<name>.tools] tables.
The pullGroups option takes a comma-separated list and passes it to ocx pull --group=<groups>.
An empty value restores the default group only.
A named list replaces the default, so it restores only the groups it names.
Add default to the list to keep the top-level tools.
New terminals put the same groups on PATH.
{ "image": "mcr.microsoft.com/devcontainers/base:ubuntu", "features": { "ghcr.io/ocx-sh/devcontainer-features/ocx:1": { "pullGroups": "default,ci" } }}An unknown group name prints a warning with exit code 64 and the hint probably an unknown group in the pullGroups option.
The container still starts.
Skip the restore
Set pull to false to fetch nothing on create.
The feature still installs ocx, and you restore by hand with ocx pull when you want the tools.
{ "image": "mcr.microsoft.com/devcontainers/base:ubuntu", "features": { "ghcr.io/ocx-sh/devcontainer-features/ocx:1": { "pull": false } }}Activate the tools in every terminal
The option shellActivation is on by default.
A new interactive shell that starts inside a project under consentPaths puts the project tools on PATH, composed once when the shell starts.
The tools are those of the default group, or of the groups in pullGroups when that option is set.
bash -ic 'command -v jq'The command prints a path inside .ocx/toolchain/links/default/jq/content/ of the project.
Four limits apply.
PATHis not refreshed at each prompt or oncd. Afterocx addorocx pull, open a new terminal or run the tool throughocx exec -- <command>.- Non-interactive shells, such as
sh -lc '...', do not get the tools onPATH. - Without
pullGroups, only the default group is onPATH. Run tools from other groups withocx exec -g <group> -- <command>. - A project outside
consentPathsactivates nothing. Useocx exec -- <command>orocx shellthere.
Projects under /workspaces/* activate without a prompt, which is a trust decision.
What the feature trusts explains it and says how to narrow the list.
An empty consentPaths value activates nothing.
If the tool is missing in a new terminal, see Error: the tool is not on PATH outside consentPaths.
See the tools in VS Code
The feature adds the extension ocx-sh.ocx to customizations.vscode.extensions.
The extension activates on workspaces that contain an ocx.toml, so it does nothing in other projects.
It puts the project tools on PATH for the editor’s own processes, such as language servers.
To also apply them to integrated terminals, set the VS Code setting ocx.env.applyToTerminals to true.
When the restore fails
A failed restore prints one warning that names the exit code, the command and a fix. The container still starts.
Lifecycle commands lists each exit code with its fix.
The most common one is exit code 78, which means ocx.lock is missing, and the fix is ocx lock followed by a commit of the file.
When the restore runs as root and ocx.lock, .ocx or the project directory belongs to another user, the feature skips the pull and warns.
The same check covers a project that OCX_PROJECT names.
Run ocx pull as the project owner instead.
Next steps
- Run ocx as root, a named user or a split user explains whose store receives the tools.
- Pin or upgrade the ocx version controls the ocx version itself.
- Prebuild the container in Codespaces and CI warms the store before anyone opens the container.
- Fix a lock or permission error matches each restore warning to its fix.