- docs
- Look things up
- Look things up
- Concepts
- Storage
Storage
This page explains how OCX lays out its data directory as independent stores, and why each store exists.
Most package managers keep everything in a single mutable tree. Installing a new version silently replaces the old one, breaking anything that referenced the old path. They also hit the network on every operation, making offline use and reproducible CI awkward.
OCX takes the opposite approach. The data directory under ~/.ocx/ (configurable via OCX_HOME) is split into independent stores. Each owns one concern, each is content-addressed where it matters, and each can be reasoned about in isolation.
The task-oriented surface is how to embed a stable path. It covers what ocx package install produces, where to find binaries, and which paths are safe to embed.
Stores
Content-addressed storage, a local index, persistent state, stable symlinks, and download staging each get their own store under $OCX_HOME:
~/.ocx/packages/immutable, content-addressed assembled packageslayers/extracted OCI layers, shared across packages that reference the same layerblobs/raw OCI blobs: manifests, image indexes, referrersindex/local index collection, one subtree per source (see Index below)toolchain/the global toolchainโs rendered toolchain tree, described on the Toolchain Tree pageprojects/the GC project ledger read byocx clean: one symlink per registered project, pointing at its directory. Distinct fromstate/projects/<key>/state/persistent runtime state, one subdirectory per concernprojects/one subdirectory per project key: shell-activation consent and the render markertelemetry/the usage-telemetry installation id,installation-id, written only by an armed run that has a destinationupdate-check/throttle markers for the background update-check probemanaged-config/the managed-config tierโs own snapshot pinpatch-descriptors/per-repository record of whether a patch descriptor was found, re-checked by install, pull, lock, add, update and package testpatch-companions/per-repository companion tagโdigest pins, never in the local indexhost/the host-capability record,capabilities.jsonreferrers/per-registry cache of whether the registry supports the referrers APItrust_root/per-Rekor-host trust-root cache for offline verification
symlinks/stable symlinks safe to embed in shell profiles and configstemp/download staging, cleaned on successful installshims/generated launcher directories for deferred packages, described under Deferred packages.bin/the sharedocx-shimexecutable bloblocks/cross-process lock files, content-keyed and safe to delete when no OCX process is running. Also holds the project mutation mutex for every ocx.toml this machine has written to, scoped under project-mutate/
Each store has a single responsibility. Upgrading a package updates symlinks in symlinks/ and adds an entry to packages/, but never touches index/. The stores can be understood one at a time. The global toolchainโs toolchain/ directory is the rendered view of a toolchain, described on Toolchain tree.
Path component encoding
Registry names, repository names, and tags that appear as directory or file names are slugified before they become filesystem path components. Characters outside [a-zA-Z0-9._-] become underscores, so localhost:5000 becomes localhost_5000. That keeps the POSIX PATH separator (:) out of environment variables that embed these paths. Dots and hyphens are preserved so domain names (ghcr.io) and semantic versions (3.28.1) stay readable on disk.
Digest-addressed directories use a two-level shard (sha256/{2hex}/{30hex}/). Only 32 hex characters are encoded in the path. The full digest is written to a sibling digest file inside each entry and is the source of truth for identity.
Packages
When OCX installs a package, the actual files land in packages/. The critical design decision: the path comes from the contentโs SHA-256 digest, not from the package name or tag.
~/.ocx/packages/{registry}/sha256/ab/c123โฆ/one directory per unique package buildcontent/package files: binaries, libraries, headersentrypoints/generated launchers for declared entry points, one script per namemetadata.jsondeclared env vars and extraction optionsrefs/back-references to install symlinks, which guard against deletion
This content-addressed layout has two consequences:
- Automatic deduplication. If a rolling tag such as
nodejs/node:24and the minor tag it currently points at,nodejs/node:24.22, resolve to the same binary build, they share one directory on disk. Storage scales with the number of distinct builds, not the number of tags that reference them. - Immutability. A path under
sha256/<shard>/never changes its contents. It is safe to reference directly from scripts or cache layers that need a known, stable binary.
Generated Launchers
When a packageโs metadata.json declares a non-empty entrypoints object, OCX materializes a sibling entrypoints/ directory at install time. It holds a launcher for each entry: a POSIX .sh launcher for Unix shells and, on Windows, a native <name>.exe launcher with a one-line <name>.shim sidecar.
Each launcher carries the digest-addressed package root and re-enters via ocx launcher exec. Every invocation therefore runs under the same clean-environment guarantee as ocx package exec <package>.
Packages that declare no entry points never get an entrypoints/ directory. See the entry points guide for the publisher workflow.
Garbage Collection
The refs/symlinks/ subdirectory inside each package tracks every install symlink, including --link paths, that points to it. That directory is the GC root signal. ocx clean starts a reachability walk from every package with a live refs/symlinks/ entry and follows forward-refs through blobs, layers and packages.
How back-references work
When ocx package install nodejs/node:24 creates the symlink symlinks/โฆ/nodejs/node/candidates/24 โ packages/โฆ/sha256/ab/c123โฆ/, it simultaneously writes a back-reference entry inside the packageโs refs/symlinks/ directory. The link targets the package root, not content/, because consumers traverse <symlink>/content themselves. Removing the symlink via ocx package uninstall removes that back-reference entry.
ocx clean then builds a reachability graph across blobs, layers and packages. Packages with live refs/symlinks/ entries (and any profile content-mode references) are roots. A single BFS pass follows each packageโs forward-refs in refs/deps/, refs/layers/, and refs/blobs/. Packages, layers, and blobs that remain unreachable are deleted in one sweep.
A dependency is protected by the liveness of its dependents, not by a back-reference inside itself. OCX records each dependency as a forward-ref inside the dependent packageโs refs/deps/ directory, pointing at the dependencyโs content/. Nothing is written into the dependencyโs own refs/symlinks/. The same ocx clean sweep that removes the last dependent therefore also collects the unreachable dependency.
Layers
A package on disk looks monolithic, with one content/ directory under one digest. The bytes inside can still come from more than one upstream archive. Each archive is a layer. It is stored once in ~/.ocx/layers/ and shared across every package that references it.
~/.ocx/layers/{registry}/sha256/ab/c123โฆ/one directory per unique layer blobcontent/extracted layer files, the hardlink source for assembled packages
Layers enable a different kind of dedup than whole packages. A package directory dedups whole builds: two tags pointing at the exact same binary share one directory. A layer dedups parts of builds. A 200 MB shared base layer used by ten packages is downloaded, extracted, and stored exactly once.
Each packageโs content/ is then assembled by hardlinking files from one or more layer directories. The package looks complete even though no bytes were copied.
Multi-Layer Packages
When you call ocx package push, every positional argument after the identifier is a layer, and there can be zero or more. Each layer is either a path to a local archive file or a digest reference to a layer that already exists in the target registry. A push with zero layers is valid too. It produces a config-only OCI artifact, useful for referrer-only or description-only manifests. It requires --metadata, because there is no file layer to sniff a sibling metadata path from.
ocx package push -p linux/amd64 acme/mytool:1.2.3 base.tar.gz tool.tar.gzocx package push -p linux/amd64 acme/mytool:1.2.4 sha256:<hex>.tar.gz newtool.tar.gzLine 1 pushes a two-layer package: a shared base plus a package-specific top. Line 2 re-publishes with the base layer reused by digest, with no re-upload. The digest ref must spell out the original archive extension (.tar.gz / .tgz / .tar.xz / .txz), because OCI blob HEADs do not carry the media type, so OCX refuses to guess.
The order matters for the manifest descriptor list, but assembled content must not overlap. Two layers cannot contain the same file path. Overlap is rejected at install time with a clear error.
Index
When you run ocx package install nodejs/node:24, how does OCX know which binary to fetch? It looks up the tag 24 in the local index and finds the corresponding digest. Unlike the other stores on this page, the indexโs home is not fixed to $OCX_HOME. --index / OCX_INDEX can point it at an entirely different collection, and it defaults to index/ when neither is set.
~/.ocx/index/ocx.sh/one subtree per source, the local index collectionc/index.jsoncatalog:ns/pkg โ sha256(root)p/{ns}/{pkg}.jsonroot document: repository pointer, tags, publisher statusp/{ns}/{pkg}/o/sha256/{hex}.jsondispatch object: the filename is the objectโs own digest, never a platform manifest
The index is a collection. Each sourceโs subtree records what this host last resolved from that remote registry (or the public index). It is dispatch-only: a platform manifest is never copied into the index. The index holds only the tag โ digest pointer and the platform โ digest dispatch object it names, each verified against its own digest. A packageโs version choice therefore resolves offline from the index alone, with no other store or network access required.
When the tag names a manifest directly (a single-platform package), OCX checks the object store before the registry. An already-installed packageโs platform manifest was cached there at install time, so re-resolving it needs no network. Only a genuinely cold digest reaches the registry. The full design lives in Indices, Local index and Public index.
The index is never walked by ocx clean. See Garbage Collection above.
Shared digests
Two distinct platform keys pointing at the same manifest digest is legitimate, and OCX never rejects it. The canonical case is Rosetta 2. A publisher who ships only a darwin/amd64 build can also list that manifest under darwin/arm64. Apple Silicon hosts then install it and run it through x86-64 translation instead of finding no arm64 build.
The two keys differ. One names the binaryโs native architecture and the other a host that can run it by translation, but both may point at the same bytes. OCI image index entries are content-addressed. The digest identifies the bytes, and neither the spec nor OCX requires a one-to-one mapping between platform descriptors and content. A generic OCI client that deduplicates identical layers across platform entries relies on the same property.
Symlinks
Package paths embed the digest: ~/.ocx/packages/ocx.sh/sha256/ab/c123โฆ/. That path changes on every upgrade. You cannot put it in a shell profile, an IDE config, or a build file and expect it to still work next month.
symlinks/ solves this with stable symlinks whose paths never change. Only their targets are re-pointed when you install or select a new version.
~/.ocx/symlinks/{registry}/{namespace}/a repository is two segments, so it is two directories:nodejs/thennode/{package}/currentselected package root, set byocx package selectcontent/entrypoints/metadata.json
candidates/22pinned package root, created byocx package install nodejs/node:2224pinned package root, created byocx package install nodejs/node:24
Two symlink entries cover most uses, and ocx package install --link PATH adds a third handle at a path you choose. All three target the package root (packages/{registry}/{algorithm}/{2hex}/{30hex}/) rather than the content/ subdirectory. Consumers traverse into โฆ/content/ for files and โฆ/entrypoints/ for launcher scripts, or read โฆ/metadata.json directly.
candidates/{tag}: pinned to a specific version. Created by ocx package install and pointed at the exact digest that tag resolved to at install time. Several versions can coexist. The candidates for node 22 and 24 both remain until you explicitly uninstall one. Even if the registry re-pushes the 22 tag with a different binary, your candidate still points to the build you installed.
This slot is host-only. Installing a foreign platform (-p windows/amd64 on a non-Windows host, or --select of one) populates the object store but leaves both candidates/{tag} and current untouched. A resolver that ignores the platform therefore never hands you a package the host cannot run. Reference a foreign-platform install by its digest instead.
current: a floating pointer to whichever candidate you last selected. Set by ocx package select (or ocx package install --select in one step). It is never updated automatically, not when you install a newer version and not when you refresh the local index. This is intentional: tools referencing current should only change behavior when you decide they should.
When the selected package declares entrypoints, the composed environment emits a PATH export for {repo}/current/entrypoints. The environment comes from ocx package env or from the global toolchain activation eval "$(ocx --global env --shell=sh)". Every declared launcher becomes a top-level command. See Entry points for how launchers, PATH, and clean-env execution compose.
See Also
- Use stable paths: install, switch versions, embed stable paths
- Toolchain tree: how a rendered toolchain links, launches and stamps its tools
- Environment composition: toolchain activation: the
activateรpinnedmatrix and what a trampoline composes - Indices: the local index collection,
index.ocx.sh, locking, offline behavior - Entry points: generated launchers, synth-PATH, clean-env execution
- Dependencies:
refs/deps/forward-refs and reachability across the GC walk ocx clean: reference for the GC command