- docs
- Look things up
- Look things up
- Concepts
- Shell integration
Shell integration
Every time you sit down at a shell, OCX has to answer two questions before it can put anything on PATH. It asks should this project’s binaries be here at all, and are they still the right ones. The first question is about consent — a project’s ocx.toml can name any OCI registry, and nothing stops a clone from naming an attacker’s. The second is about staleness — an ocx --global add or an ocx update run five minutes ago should not need a fresh terminal to take effect. This page covers the mechanism that answers both: the per-prompt shell hook and the consent model that gates it. When a shell does not pick up its tools, Shell problems covers what to check.
From inert to active
A freshly cloned repository with an ocx.toml you have never seen has to stay inert the moment you cd into it. Nothing runs at clone time, because OCX never executes package code during install. The risk is still real: the first binary invocation in that directory would put whatever ocx.toml names in front of node, cargo, or git on PATH. The history of mise is the cautionary tale. GHSA-436v-8fw5-4mj8 shipped for four months. A project’s own trust-control settings were read before the trust check that was supposed to gate them. A malicious repository could therefore self-declare itself trusted.
OCX closes that ordering gap structurally. The only project-supplied bytes read before consent is established are a directory walk and the lock file’s own source list. The check itself needs that much to decide whether to proceed. ocx.toml is never parsed until consent says yes. A fresh clone with no consent stamp, no matching grant, and no lock at all changes nothing and prints one hint line. See Consent grants for exactly what makes a project stop being inert.
Once a project is consented, OCX keeps the composed environment converged with what is declared, at every prompt, without an eval step you run by hand. The global toolchain needs no consent at all, since $OCX_HOME/ocx.toml is your own file. cd into a consented project and its locked binaries land on PATH at the next prompt, and the variables its packages declare are set. cd back out and both leave again. Add a package to the global toolchain from another terminal. The shell you are already sitting in picks it up on its next prompt too.
The recordings below run in a shell that carries no hook yet, so each one types the eval "$(ocx self activate --shell=bash)" line by hand. ocx self setup instead writes a profile block that sources the $OCX_HOME/env.sh file. That env file runs ocx self activate once, at shell start. The commands before it are only the scaffolding that scenario needs. Everything after it — the ocx: +PATH and ocx: -PATH summaries — is the hook reconciling on its own at the next prompt, with no eval of yours involved.
The activation env files
ocx self setup writes one thin env file per shell family into $OCX_HOME. Each env file calls ocx self activate at shell start, which delegates the runtime logic to the binary: the PATH prepend, completion injection and the global toolchain environment. The env files are byte-identical across users; no install-time substitution occurs.
| File | Shell | Wired by |
|---|---|---|
$OCX_HOME/env.sh |
bash, zsh, dash, ash, ksh | a managed block in ~/.profile, ~/.bashrc, ~/.zprofile and ~/.zshrc, plus ~/.bash_profile when it exists; ZDOTDIR moves the zsh files |
$OCX_HOME/env.fish |
fish | $XDG_CONFIG_HOME/fish/conf.d/ocx.fish, else ~/.config/fish/conf.d/ocx.fish |
$OCX_HOME/env.nu |
nushell | $XDG_DATA_HOME/nushell/vendor/autoload/ocx.nu, else ~/.local/share/nushell/vendor/autoload/ocx.nu; auto-sourced |
$OCX_HOME/env.elv |
elvish | a managed block in $XDG_CONFIG_HOME/elvish/rc.elv, else ~/.config/elvish/rc.elv |
$OCX_HOME/env.ps1 |
PowerShell | a managed block in $PROFILE |
Each env file resolves OCX_HOME at runtime with the shell’s own assign-if-unset syntax (: "${OCX_HOME:=$HOME/.ocx}" in POSIX shells). Activation therefore works in a fresh shell where OCX_HOME was never exported. The managed block in your profile uses the same ${OCX_HOME:-$HOME/.ocx} fallback, because it sources env.sh, which is what exports OCX_HOME. It existence-guards the source so a login shell never errors on a missing file. OCX_HOME also decides where ocx self setup writes the env files. Set it to a non-default path before running setup and the env files and the object store share that root.
The state carrier
The shell hook needs to remember, from one prompt to the next, exactly what it applied. Otherwise it cannot tell “a value OCX wrote” from “a value you typed,” and reverting one would risk clobbering the other. That memory lives in one private environment variable, __OCX_ENV_STATE. It travels with the shell like any other variable, so a subshell or a nested bash -c inherits it along with the environment it describes.
The value has two parts. A plaintext header carries the narrowing policy the invocation was started with (n=offline, n=frozen and the like) and the OCX home (h=). A compressed payload follows with the values OCX applied, the policy it received and the session selection. The header stays readable so a consumer that cannot decode the payload still honors the policy.
It is a deliberate exception to the private __OCX_* convention. A child process cannot mutate its parent’s environment any other way, so this one has to cross into your interactive shell. With a documented repair gesture it is a user-facing contract, whatever its name looks like. The whole __OCX_* namespace is still reserved: a package cannot declare one and --env cannot set one.
Two variables cross into every OCX descendant: __OCX_ENV_STATE and OCX_BINARY_PIN. The pin is the stable install path when the running OCX is the installed one, and the running binary otherwise. Launcher forwarding covers what else a child inherits.
The value is capped at 8,169 characters. Past that, OCX sheds the least useful parts in a fixed order, and the affected scope’s binaries stop being revertible for the rest of that session (one line printed once, not on every prompt). unset __OCX_ENV_STATE makes the shell forget everything.
An unreadable value, whether from another major version or garbled, is never an error. Its header still narrows, so an offline shell stays offline. OCX prints one warning, and the hook stands down once with one notice. Missing state is treated like a first prompt: OCX rebuilds what it knows from the project files on disk.
Per-shell coverage. A real per-prompt hook fires on every prompt without you doing anything. It needs an append-safe extension point in the shell’s own prompt machinery. Not every shell has one:
| Shell | Per-prompt hook | What it reconciles |
|---|---|---|
| bash, zsh | PROMPT_COMMAND / precmd_functions append |
global + project |
| fish | --on-event fish_prompt |
global + project |
| PowerShell | wraps prompt, restoring the previous definition |
global + project |
| nushell | pre_prompt hook, appended to your own |
global + project — nushell cannot evaluate text, so OCX hands the hook a data plan that it applies; the guard is the same as elvish’s, directory and signal variables only |
| elvish | $edit:before-readline append |
global + project — guard is carrier-and-$pwd only; unlike the presence guard of the other shells, it neither compares watch-set mtimes nor notices a deleted file |
| ash, dash, ksh, Batch | none — no append-safe prompt-hook point exists | shell start only, both scopes |
The four shells in the last row still activate correctly the moment the shell starts, because the initial compose is unaffected. Nothing re-checks after that. If you add a global package or cd into a consented project mid-session in such a shell, open a new one to see it. Nushell and elvish reconcile both scopes at every prompt, same as bash, zsh, fish, and PowerShell, but with a narrower guard. See Elvish’s guard.
Nested projects switch, they do not stack
At any prompt exactly one project is in effect. The walk from your working directory upward stops at the nearest ocx.toml (or at the first .git/ boundary it crosses). Whatever a farther ancestor declares is never read.
That matters the moment a repository holds a second ocx.toml below its first. Examples are a test/ tree that pins its own uv and pytest, a website/ that pins its own bun, and a vendored sub-repository with a toolchain of its own. Standing at the root, the root’s binaries are on PATH. cd test/ and they are gone. The prompt reconciles this as a switch: the root’s contributions are retired and test/’s applied in one pass. The summary line names the project you landed in, ocx: ~PATH (test). cd .. and the root’s binaries come back the same way. Consent follows the same line. The inner project is its own project, so the outer one’s stamp does not cover it. Only a subtree path grant over the enclosing directory reaches both.
If a nested project needs a package the enclosing one declares, declare it there too. ocx add inside test/ writes it into test/ocx.toml. That file plus its ocx.lock is the whole answer for everything beneath it. ocx exec follows the same walk, so it composes the nearest file’s lock alone. To run against the enclosing project from inside the nested one, name it, as in ocx --project .. exec -- node --version.
To keep the tools already loaded and add another group in front of them, nest an explicit exec, as in ocx exec -- ocx --project test exec -- pytest. Every ocx exec layers what it was asked for over the environment it finds.
Inherited scopes
A shell started by ocx --project P exec -- bash inherits P’s environment from the exec, and the hook never recomposes a scope the environment already carries. The shell composes nothing inside P, the global toolchain included. cd into another project Q and the hook layers global and Q on top. Leaving Q removes them again.
An exec-spawned shell keeps the environment it started with. Editing P’s ocx.toml changes nothing there, because the hook does not look at P again. Start a new ocx exec to pick the edit up.
A fixed-project ocx shell
ocx shell opens a fixed-project session, fixed to the project it was opened in. It keeps the groups of its project that you consented to and refreshes them when that ocx.toml or ocx.lock changes. Values from --with and --env stay for the life of the session. On cd into another project the shell prints one notice and applies nothing.
The session PATH beside the hook
The per-prompt hook can only run where there is a prompt. An IDE, a desktop launcher and a background service each start without one, so nothing in the mechanism above ever reaches them. That is why a PATH that is right in the terminal can be wrong everywhere else on the same machine.
ocx self setup answers that separately. It writes two directories — the OCX installation’s bin directory and $OCX_HOME/toolchain/active/bin — into the one store per platform that a whole login session reads, once, at install time. That registration is not the hook and does not depend on it. Every process started afterwards inherits those directories whether or not it ever runs a shell. The stores, the per-platform mechanisms and the six limits the registration does not promise are in the user guide and the command-line reference.
The two mechanisms then share one PATH. Three things decide how they fit.
The shell hook cannot drop them
Both session directories are in the shell hook’s desired set on every prompt, in every activate mode — none included. That is not a courtesy to the installer; it is what stops the two mechanisms from fighting.
$OCX_HOME is an owned prefix, and the repair pass removes every segment under an owned prefix that the desired set does not contribute. Both directories sit under $OCX_HOME. So an arm that composed nothing and returned early without them would not leave them alone. It would delete the registration ocx self setup had just written, at the first prompt of the first shell. They are session-level facts rather than activation decisions. The shell hook treats them as such even when it has been told to activate nothing at all.
Where they sit on PATH
Front to back, a converged PATH reads:
- the project scope’s composed entries (
envmode only) - the project’s
<home>/toolchain/active/bin(binmode only) $OCX_HOME/toolchain/active/bin- the OCX installation’s
bindirectory - the global toolchain’s composed entries
The session block sits between the two toolchains, and that position is the contract rather than an arrangement. Putting it after both would place the global toolchain’s composed entries ahead of a project’s own trampoline directory. A globally installed node would then shadow the project’s. That is the inversion strict isolation exists to forbid.
Within the session block the install directory comes last. ocx reads like every other name: the most specific toolchain that pinned it answers for it. The installed binary is the floor beneath both. A toolchain may pin ocx itself, because nothing refuses the name. An order that kept the installed binary in front would leave such a pin rendered and permanently unreachable. The bare-word ocx a trampoline falls back to when no install path exists is not what the ordering defends. A rendered trampoline bakes an absolute ocx path. The one remaining bare-name case is settled where the lookup happens, by excluding trampoline directories from it.
What bin mode costs a prompt
In bin mode the shell hook emits a project’s <home>/toolchain/active/bin only when a render marker exists for that home. The directory must also still hold exactly what the marker recorded. The check is one directory read plus one stat per entry, and a content hash only for the entries the cheap comparison already found suspect. No compose, no metadata read, no network — that budget is most of why bin mode exists.
It is set equality in both directions: every name the marker records must be present, and every name present must be recorded. A one-way lookup over the marker’s own keys would pass the moment each recorded entry matched. That is precisely the case the gate is built for. A hostile clone can force-commit one extra trampoline beside an otherwise legitimate tree. Every filesystem condition on that walk is a mismatch rather than an error. Examples are an unreadable trampoline directory, an entry that vanished mid-walk. Others are an entry replaced by a symlink after a good render and a name that is not UTF-8. The entry is withheld and PATH does not change.
The active link the path runs through is held to the same standard, and to the same effect. It is a mismatch, not a new failure mode, when the link is absent, not a link, or points anywhere other than shells/default. There is one symptom and one remedy for every state on this list.
A mismatch and a missing marker have one behaviour, so they get one sentence. The prompt emits nothing for that project and prints the line that names the fix:
ocx: /work/acme/api: its toolchain has not been rendered for this lock; run `ocx pull` hereThe stale window between a lock change and the next ocx pull is designed, not something that line apologises for. The prompt path never prunes, and none may be added. Pruning here would be a whole-directory delete inside a repository-writable tree, running before every command you type, with no --dry-run in front of it. The stale trampolines stay exactly where they are, and the render that replaces them is a command you ran on purpose.
Consent grants
A project activating on cd would pull whatever ocx.toml names onto PATH with no confirmation. That is the same shape of risk mise’s GHSA-436v-8fw5-4mj8 exploited, just aimed the other direction. Instead of a project declaring itself trusted, a project here would simply be trusted by default. OCX refuses that default. Activation requires one of three independent grants; without any of them, a project is inert regardless of what it declares.
Only projects are gated. The global toolchain is always consented — $OCX_HOME/ocx.toml, its [env], and every package it locks. It is your own file, on your own machine, so it needs no grant, and no [shell.consent] entry can withhold it. It composes on every prompt even while the project you are standing in is inert. It also composes when that project has a config of its own. That is why a fresh clone going inert does not take your global packages with it.
- A consent stamp — written by
ocx shell allow, and byocx initfor the project it creates (pass--no-consentto skip it). It is also written automatically the first time you runocx add,ocx remove,ocx lock,ocx update,ocx upgrade,ocx pull, orocx execagainst a project. Running a mutating OCX command in a directory is itself consent. It records which OCI sources that project’s lock resolved against at the time. Re-running one of those commands after the lock picks up a source outside the stamped set re-confirms. Ordinary growth inside already-consented sources does not. The stamp lives under$OCX_HOME/state/— remove it withocx shell revoke, or delete the file; either simply makes the project inert again until you consent afresh. A machine driving those commands against a checkout nobody chose declines the stamp withOCX_NO_CONSENT=1, or per-command with--no-consentonocx init,ocx pullandocx exec. The flag outranks the variable, so a single step opts back in with--consent.ocx shell allowignores both — it is the gesture the variable exists to tell automation apart from. Because a stamp is a grant that noconfig.tomlrecords,ocx shell statenames which of the three clauses activated a project, and when a stamp was written.ocx cleandoes this for you once a project’s directory is confirmed gone, in the same pass that garbage-collects its packages. See Remove and clean up for the full behavior. - A path grant — a canonicalized directory an operator has pre-authorized, without knowing in advance what that checkout will resolve against. This is the devcontainer feature and CI-image case: the image build knows the checkout path but not its eventual lock contents. An entry naming one directory grants that directory alone. A trailing
/*grants that directory and everything beneath it, matched component-wise so/workspaces/acme/*never reaches a/workspaces/acme-evilsibling. A subtree entry also activates a repository cloned into that tree later, with no further gesture. Unlike a namespace grant, a path grant, subtree or exact, opens the project’s own[env]table too, since that table has no publisher to hold accountable. Entries are compared as written — write the canonical path, not a symlinked route to it. A leading~is the one exception: it expands to the current user’s home directory, the same interpolation git’s ownsafe.directoryapplies. The expansion stops at the~itself, so it does not turn the rest of the entry into a canonical path.~/dev/*wheredevis a symlink onto another mount still misses the project it appears to cover. - A namespace grant — a set of OCI sources (
<registry>/<org>) an operator trusts, without knowing every path a matching project might be checked out to. This is the fleet case: pre-approveocx.sh/acme-corponce, and a project whose packages all came from inside that namespace activates. What is matched is not the lock’s text. The object store records, for every package it fetched, the coordinate it resolved and got digest-verified content for. The grant is decided against that record: a lock namingocx.sh/acme-corp/anythingbuys nothing unless this machine genuinely fetched those digests underocx.sh/acme-corp. The practical consequence is that a namespace grant activates a project whose packages this machine has already fetched. That is a warm shared store, which is the fleet case. The project stays inert on a cold one until the firstocx pull. That pull writes a consent stamp anyway, unless it declined to, underOCX_NO_CONSENTor--no-consent.ocx shell statenames the gap when a lock’s claim and the store’s record disagree. A namespace grant also stops at the package boundary. It authorizes the packagesocx.lockresolved, never the project’s own[env]table inocx.toml, because that table has no publisher to hold accountable. A baretype = "path"entry works from clone content alone, with no registry involved. A namespace-granted project that declares[env]still gets its packages. OCX withholds the table and prints a hint naming the fix. Runocx pullthere once, or list this exact directory in[shell.consent] paths. The directory entry must be exact, not a subtree grant. The pull also writes a consent stamp, unlessOCX_NO_CONSENTor--no-consentdeclines it. In that case the pull leaves the project exactly as inert as it found it. See What consent does not cover for what it still does not buy.
Path and namespace grants are independent and additive. Either alone is sufficient, and neither constrains the other. An absent or empty grant means nothing is authorized, never “everything is.” Neither grant ever writes a consent stamp. Drift for a namespace grant is re-checked on every prompt against the current lock. A path grant is deliberately drift-blind, since an operator naming a checkout in advance cannot enumerate its future sources. The configuration tiers a grant can live in, and the rules for parsing and merging its entries, are in Consent grammar.
Declining the stamp from automation. Running a mutating command in a directory is normally consent, which is right for a person at a keyboard. A Bazel repository rule, a CI job or a generated launcher makes the same gesture on someone’s behalf. The stamp it leaves would authorize that project’s [env] table on every later cd once the hook is installed. OCX_NO_CONSENT is how automation declines that question. The eight commands that record a stamp (add, remove, lock, update, upgrade, pull, exec and init) then run without writing one. Nothing else changes: the pull still pulls and the lock is still written. The variable is forwarded to child ocx processes, ocx exec --clean included, so a script that itself calls ocx pull inherits the same answer. ocx exec --no-consent sets it on the child’s environment too, because a command line does not cross a spawn. The reverse is deliberately not true. ocx exec --consent answers for the one project it targets and does not clear a variable the child would otherwise inherit. So refusal inherits downward and permission does not.
Do not export it in your interactive profile. A stamp records the sources its lock resolved against, and growing the lock past that set re-confirms by re-recording. With the variable exported, that never happens. ocx add pulls in a package from a source the stamp does not cover, and nothing re-stamps. The project you were working in is inert at the next prompt. Set it in the pipeline, image or build rule that needs it. ocx shell state names the state and ocx shell allow clears it.
What consent does not cover
Consent answers one question: may this project’s toolchain reach my PATH at all. It does not answer a second, related one: did the identity I expect actually publish these bytes. Within an already-consented namespace, whoever can publish gets code in front of your PATH with no signal from the consent mechanism. That is accepted by design, because content-hash re-confirmation on every ordinary git pull or ocx update would train users to click through prompts without reading them. That is worse.
A namespace grant sits inside that same residual, and it is deliberately not decided by the lock. ocx.lock is project-supplied text, and a clone can name any source it likes. Matching a namespace pattern against it would let a clone borrow a trusted organization’s name for content that never came from there. The grant is decided instead against the object store’s own record of the coordinate each locked digest was materialized under on this machine. A lock is text a clone’s author writes; the record takes an act of pulling here under that name. On a machine that has not seen the content those coincide. The bytes come off the wire under that name, and publishing into a listed organization needs that organization’s publish credential. Where the object store already holds the digest they do not: one ocx pull naming the granted organization writes the record with no registry in the loop. The record is evidence about what this machine did, not about what a registry attested. That is also why there is no whole-registry pattern. ocx.sh/* and a bare ocx.sh are both refused at parse. A grant spanning every organization on a host trusts every publisher on it wherever anyone can register. List organizations one at a time.
What the grant still cannot tell you is whether the expected identity published those bytes. A credential inside a listed organization is enough. The record says which coordinate the digest was fetched under, never who signed it. The record is that coordinate as you named it. If you have configured a [mirrors] entry or an index that redirects it, the bytes came from your own routing rather than from the upstream host. The content is digest-verified either way, and who published it is the same open question. That is the residual above, and the control for it is the [[trust.policy]] below.
The real control for that residual already exists and answers the right question: an operator [[trust.policy]] plus ocx package verify. Consent decides whether to run a project’s toolchain at all; a Sigstore signature decides whether the expected identity published what you are about to run. They are deliberately separate mechanisms — folding signature verification into the consent stamp would produce one system doing both jobs worse.