- docs
- Look things up
- Glossary
Glossary
Packages and storage
back-reference
A link inside a package’s refs/ directory that records who uses the package, so garbage collection keeps it.
See Storage.
candidate
A symlink at symlinks/<registry>/<repo>/candidates/<tag>, created by install, that keeps one installed version of a package reachable.
See Storage.
companion package
A package that a patch descriptor names, whose environment entries OCX layers onto every matching target package.
See Patches.
current symlink
The one symlink per repository that points at the selected candidate; ocx package select and install --select move it.
See Storage.
deferred package
A package whose download waits until one of its commands first runs, chosen with the lazy-mode key.
See Deferred packages.
entry point
A named command a package declares in its metadata; OCX generates a launcher for it so the command runs from PATH.
See Entry points.
execution record
One JSON file OCX writes just before it starts a binary, naming each package’s manifest digest and the environment inputs of that launch.
See Execution records.
garbage collection
The sweep ocx clean runs: it deletes every stored object that no symlink, project lock or dependency still reaches.
See Storage.
install
Download a package into the object store. ocx package install also creates its candidate symlink; project commands such as ocx add install without one.
launcher
A generated executable that starts one entry point through ocx launcher exec, with the package root baked in; a native .exe on Windows.
See Launcher forwarding.
launching frame
One route into OCX that writes an execution record: exec, package exec, launcher exec or a shim.
See Launcher frames in records.
materialize
Make a package’s files present on disk by downloading and extracting its layers into the object store.
See Deferred packages.
native launcher
The Windows .exe form of a launcher, the one executable every Windows caller can start.
See Entry points.
object store
The content-addressed directories under the OCX home that hold every downloaded blob, extracted layer and assembled package, keyed by digest.
See Storage.
OCX home
The directory where OCX keeps its stores, local index, state and global toolchain: $OCX_HOME, or ~/.ocx when unset.
See Environment.
package
A versioned set of pre-built files plus metadata, stored as OCI artifacts in a registry and installed by OCX as one unit.
See Storage.
package metadata
The metadata.json document a package carries: how OCX extracts it, its environment entries, dependencies and entry points.
See Metadata.
package root
The directory of one assembled package in the object store; its content/ subdirectory holds the package’s files.
See Storage.
patch
An operator-published overlay that changes the environment a package runs in, without changing the package itself.
See Patches.
patch descriptor
A small JSON document in a registry that names which companion packages apply to which target packages.
See Patches.
patch snapshot
The file ocx patch freeze writes, pinning every patch to an exact digest for reproducible builds.
See Maintain patch companions.
pin
Fix a reference to one exact value, such as a tag to a digest or a trust policy to one signer identity.
See Dependencies.
shim
A placeholder executable written for a deferred package; its first run downloads the package, then starts the real binary.
See Deferred packages.
sidecar
A file stored next to an archive or blob to carry its metadata, such as the metadata.json beside a bundle.
See Bundle a release.
sink
The directory that receives execution records; configuring one is what turns recording on.
See Execution records.
trampoline
A generated executable in a toolchain tree’s active/bin that re-enters ocx exec against its own project when it runs.
See Toolchain activation.
OCI and registries
annotation
A key-value string on an OCI manifest, such as org.opencontainers.image.source, that tools and catalogs read.
See Publish a package.
blob
Any content a registry stores by digest: a layer archive, a config or a manifest.
See Storage.
content-addressed
Stored under a name derived from the content’s own digest, so identical bytes are stored once and never change in place.
See Storage.
descriptor
A small JSON record inside an OCI manifest that names other content by media type, digest and size.
See github.com.
digest
A SHA-256 hash of exact bytes, written sha256:<hex>; unlike a tag, it names one piece of content forever.
See Versioning.
fallback tag
The sha256-<hex> tag that holds referrers on a registry without the Referrers API.
See Signing.
identifier
The string that names a package, registry/repository[:tag][@digest], with the default registry filled in when omitted.
See Find packages and versions.
image index
An OCI manifest that lists one platform manifest per platform under a single tag, so each host picks its own build.
See Publish for several platforms.
layer
One archive of files in a manifest, addressed by its digest; OCX extracts each layer once and shares it between packages.
See Storage.
manifest
An OCI JSON document that describes one stored artifact: its config and its layers, each by digest.
See Dependencies.
namespace
The path segments of a repository before the package name, such as acme in ocx.sh/acme/widget.
See Find packages and versions.
OCI
The Open Container Initiative, whose specifications define the registry protocol and artifact formats OCX stores packages in.
See opencontainers.org.
platform manifest
The manifest of one platform’s build, listed in an image index; dependency pins and lock entries name its digest.
See Publish for several platforms.
referrer
An artifact, such as a signature or SBOM, that names another manifest as its subject, so a registry lists it beside that manifest.
See Signing.
registry
A server that speaks the OCI distribution protocol and stores repositories of tags, manifests and blobs, such as GHCR or Docker Hub.
See github.com.
registry name
The first segment of an identifier, such as ocx.sh; a mirror or the public index may route it to another storage host.
repository
A named collection of tags and manifests inside a registry, such as nodejs/node; one repository holds one package.
See Find packages and versions.
tag
A mutable, human-readable name in a repository, such as 3.28 or latest, that points at one manifest digest.
See Versioning.
Platforms
AMFI
Apple Mobile File Integrity, the macOS kernel module that checks code signatures independently of Gatekeeper.
See Platform problems.
any platform
The platform any: a build with no platform requirement, used where no exact platform match exists.
See Publish for several platforms.
code signature
A macOS seal embedded in a binary; Apple silicon refuses to run a binary whose signature does not match its bytes.
See Platform problems.
CPU variant
The OCI platform.variant field, a CPU sub-architecture such as v8 for arm64; unrelated to package variants.
See Versioning.
dynamic loader
The program, such as ld-linux.so or the musl loader, that loads a dynamically linked Linux binary and its libraries.
See Platform problems.
Gatekeeper
The macOS check that stops downloaded apps and binaries without an approved signature from running.
See Platform problems.
gcompat
An Alpine package that lets some glibc binaries run on musl; the loader is still musl’s own.
See Platform problems.
glibc
The GNU C Library, the libc of Ubuntu, Debian, Fedora and most other Linux distributions.
See Publish glibc and musl builds.
libc
The C library a Linux binary links against, glibc or musl; OCX records the requirement as a libc feature.
See Publish glibc and musl builds.
libc feature
The libc.glibc or libc.musl entry in a platform’s os.features, stating the libc a Linux build requires.
See Publish glibc and musl builds.
Mach-O
The executable file format of macOS.
See Platform problems.
musl
A small libc used by Alpine Linux and static builds; a glibc binary does not run on it without help.
See Publish glibc and musl builds.
PATHEXT
The Windows variable listing the extensions a shell appends to a bare command name, such as .EXE and .BAT.
See Platform problems.
platform
The operating system and CPU a build targets, written os/arch, optionally refined by a CPU variant and a libc feature.
See Platforms.
quarantine flag
The com.apple.quarantine attribute macOS sets on downloaded files, which makes Gatekeeper check them.
See Platform problems.
static binary
A binary that carries its libraries inside it and needs no libc from the host.
See Publish glibc and musl builds.
WASI
The WebAssembly System Interface; OCX gives each WASI version its own platform, such as wasip1/wasm.
See Publish for several platforms.
Indices
announce
Publish a package’s registry tags into its index entry, as a change request on the index repository.
See Announce a package.
claim
Register a package in an index for the first time, through a reviewed change request. The claimed unit is the package.
See Announce a package.
dispatch object
The image index a tag resolved to, stored verbatim in the local index under its own digest.
See Local index.
frozen
A mode, set by --frozen or OCX_FROZEN, in which tags resolve only from the local index and an unknown tag fails.
See Lock and reproduce builds.
index
A catalog that maps each package’s tags to digests, so OCX can choose a version without asking the registry.
See Indices.
index repository
The Git repository on a forge that stores an index’s files; claims and announcements arrive there as change requests.
See Announce from CI.
keep tag
A digest-named __ocx.keep tag a push writes for each platform manifest, so a deleted tag cannot leave the manifest unreachable.
See Indices.
local index
A copy of an index under the OCX home, recording what this host last resolved. It changes only when a command refreshes it.
See Local index.
offline
A mode, set by --offline, in which OCX makes no network request at all and fails on anything not already local.
See Work offline.
owner
A login:id pair in a root document that may announce the package; the numeric id is the half that counts.
See Announce a package.
public index
index.ocx.sh, the hosted index for the ocx.sh registry name; it points each package at the registry that stores it.
See Public index.
remote index
The live source a resolve queries over the network: the registry itself, or an index service such as index.ocx.sh.
See Indices.
root document
A package’s top-level entry in an index: its repository pointer, tags, owners and declared publishers.
See Public index.
shipped copy
A local index subtree packaged inside a tool release and selected with OCX_INDEX, so that tool resolves offline.
See Indices.
yank
A publisher’s mark on a tag that OCX refuses to install by default; the tag itself stays in the registry.
Projects
activation
Applying a toolchain to a shell, set per project by activate: env sets PATH and the package variables, bin only PATH, none nothing.
See Toolchain activation.
binding
One entry in a [tools] table: a local name on the left, the identifier it resolves to on the right.
See Project groups.
global toolchain
The user-wide ocx.toml and ocx.lock in the OCX home, reached only with --global and never mixed into a project.
See Project toolchain.
group
A named subset of a project’s bindings, declared as [group.<name>.tools], so a host downloads only the tools it needs.
See Project groups.
lock file
ocx.lock, written by ocx lock beside ocx.toml: it pins every binding to per-platform digests, so later commands skip the registry.
See Project toolchain.
project
A directory tree whose root holds an ocx.toml; commands run inside it resolve against that file and its lock file.
See Project toolchain.
project commands
The commands that read ocx.toml and ocx.lock and take binding names, such as ocx add and ocx lock. The ocx package commands take identifiers.
See Run project tools.
render
Write or refresh the toolchain tree from the lock file, as ocx pull and ocx add do.
See Toolchain render.
render marker
A file under $OCX_HOME/state/ that records which lock and entries a toolchain tree was last rendered from.
See Toolchain tree.
toolchain
The set of bindings an ocx.toml declares, each a local name that resolves to one package.
See Toolchain tree.
toolchain tree
The directory <project>/.ocx/toolchain/ that OCX renders from the lock file: stable links and trampolines for every binding.
See Toolchain tree.
Environments
closure
A package together with all its transitive dependencies, which composition walks deepest first.
See Environments.
composition
Building one runtime environment from the environment entries of a package and its dependencies, in dependency order.
See Environments.
edge visibility
The visibility of one dependency, choosing which of that dependency’s surfaces reach the package that depends on it.
See Declare dependencies.
entry visibility
The visibility of one environment entry in package metadata, choosing the surfaces it joins.
integration key
The reverse-DNS name that keys one entry in a package’s integrations block, such as com.microsoft.vscode. OCX does not enforce the shape.
See Integrations.
interface surface
The part of a package’s environment that consumers see when they run the package or depend on it.
See Environments.
private surface
The part of a package’s environment that only its own launchers see at run time, selected with --self.
See Environments.
strict isolation
The rule that global toolchain packages never compose into, supplement or replace a project’s resolved environment.
See Environments.
topological order
An order in which every dependency comes before the packages that need it.
See Dependencies.
visibility
Which surface an environment entry or a dependency reaches: the interface surface, the private surface, both or neither.
See Environments.
Configuration
config tier
One place OCX discovers settings: the system, user, OCX home or managed tier. A later tier overrides an earlier one.
See Configuration.
default registry
The registry name OCX puts in front of an identifier that names none: ocx.sh unless configured otherwise.
kill switch
OCX_NO_CONFIG=1, which skips discovered config files and the managed config; locked system-tier sections and explicitly named files still load.
See Configuration.
ladder
An ordered list of sources OCX checks strongest first for one setting or credential; the first match wins.
See Toolchain activation.
managed config
Corporate settings published as an ordinary OCX package. Each host keeps a synced copy and layers it over its config files.
See Configuration.
mirror
A [mirrors] entry that sends all traffic for one registry host to a replacement endpoint, with no fallback to the origin.
operator
The person who configures OCX on many hosts and publishes the patches or managed config they use.
Shell
CI output file
A file a CI runner reads to carry variables and PATH entries to later steps, such as GitHub’s GITHUB_ENV; ocx env --ci appends to it.
See Run OCX unattended in a pipeline.
consent
Permission for the shell hook to activate a project; a fresh clone stays inert until a path grant, namespace grant or consent stamp covers it.
See Shell integration.
consent stamp
The file ocx init, ocx add and ocx shell allow write, recording which sources a project’s lock file resolved against at consent.
See Shell integration.
env file
One thin file per shell family, such as $OCX_HOME/env.sh, that ocx self setup writes and the shell profile sources.
See Shell integration.
managed block
The marked section OCX writes into a shell profile and later updates or removes, leaving the rest of the file untouched.
See Shell integration.
session path
The login-session PATH entry ocx self setup registers, so IDEs and services that never read a shell profile still find OCX.
See Shell integration.
shell hook
The per-prompt function OCX adds to a shell, which recomposes the environment, PATH and the package variables, after a cd or a lock change.
See Shell integration.
Publishing
build receipt
The <stem>-receipt.json file ocx package create writes beside a bundle, which push and test read back.
See Publish a package.
build tag
A tag with a _build suffix, such as 3.28.1_20260301, that by convention the publisher never re-pushes.
See Versioning.
bundle
The build output a publisher pushes: one archive of the package’s files plus its metadata sidecar.
See Bundle a release.
cascade
Moving a new release’s rolling tags along with it, so pushing 3.28.1 also moves 3.28, 3 and latest.
See Versioning.
change request
A pull request on GitHub or a merge request on GitLab: the form in which claims and announcements reach an index.
See Announce a package.
forge
A Git hosting service such as GitHub or GitLab, where index repositories and their change requests live.
See Announce from CI.
package description
The README, logo, title and keywords attached to a repository with ocx package description push, stored as an OCI manifest.
promote
Copy a package’s platform manifests and blobs byte for byte from one repository to another with ocx package copy.
See Promote packages between environments.
publisher
The person or CI job that builds a package and pushes it to a registry.
See Publish packages.
rolling tag
A tag such as 3.28, 3 or latest that moves forward to the newest matching release.
See Versioning.
semver
Semantic Versioning: versions written MAJOR.MINOR.PATCH, where each part signals breaking, additive or fix changes.
See Versioning.
snapshot build
A pre-release tag meant to be deleted later, such as a canary or nightly, marked ephemeral when announced.
See Snapshot tracks.
Starlark
A small, deterministic, Python-like language; ocx package test --script runs package tests written in it.
See Write script tests.
track
One line of tags that cascade together, such as one variant’s releases or a pre-release line like 0.5.0-canary.
See Snapshot tracks.
variant
A build flavor of one package, such as slim or debug, published under a tag prefix like slim-1.2.3.
See Versioning.
Signing
attestation
A signed statement about a package, such as provenance or an SBOM, bound to the exact manifest digest it describes.
See Attach attestations and SBOMs.
cosign
Sigstore’s command-line signing tool; OCX signatures and attestations interoperate with it.
See cosign parity.
declared publisher
A signer identity listed in a package’s root document; OCX accepts its signatures as it would a matching trust policy.
See List publishers in the index.
DSSE
Dead Simple Signing Envelope: the JSON wrapper that signs an attestation’s payload together with its type.
See cosign parity.
Fulcio
Sigstore’s certificate authority: it exchanges an OIDC token for a short-lived X.509 certificate naming the signer identity.
See Self-hosted Sigstore.
in-toto
A supply-chain metadata framework; its statement format carries an attestation’s subject digest and predicate.
See cosign parity.
keyless signing
Signing with a throwaway key whose certificate Fulcio binds to an OIDC identity, so no long-lived key exists.
See Signing.
OIDC
OpenID Connect: the token standard CI systems and identity providers use to prove a signer’s identity to Fulcio.
See Sign a release.
predicate
The body of an attestation: the document, such as an SBOM, whose bytes the in-toto statement wraps.
See Attach attestations and SBOMs.
purl
Package URL, a standard identifier string; execution records name packages as pkg:oci purls whose version is the digest.
See Records and SBOMs.
Rekor
Sigstore’s append-only transparency log; each logged signature gets a Signed Entry Timestamp that verifiers check.
See Self-hosted Sigstore.
SAN
Subject Alternative Name: the certificate field that holds the signer identity, such as a workflow URL or an email address.
See Signing.
SBOM
Software bill of materials: a list of the components inside a package, attached to it as a referrer.
See Attach attestations and SBOMs.
SCT
Signed Certificate Timestamp: proof embedded in a Fulcio certificate that a certificate-transparency log recorded it.
See Signing.
SET
Signed Entry Timestamp: Rekor’s signed promise that a signature entered its transparency log at a given time.
See Signing.
signer identity
The OIDC identity a signing certificate names, such as a CI workflow URL, which a trust policy pins.
See Signing.
Sigstore
An open signing service: Fulcio issues short-lived certificates, Rekor logs every signature, and verifiers check both.
See Signing.
Sigstore bundle
The JSON envelope that holds a signature, its certificate and its transparency-log proof, pushed as a referrer.
See Signing.
SLSA
Supply-chain Levels for Software Artifacts: a framework whose provenance format records how and where a package was built.
See Sign a release.
trust policy
A [[trust.policy]] entry naming the signer identities OCX accepts for every package under one registry scope.
See Trust signers with a policy.
trust root
The Sigstore keys and certificates a verifier trusts: the Fulcio CA, the Rekor key and the CT log keys.
See Signing.
TUF
The Update Framework, the protocol Sigstore uses to distribute and rotate its trust root.
See Signing.
Security
credential helper
A Docker-style program that hands registry credentials to tools on request, configured in ~/.docker/config.json.
See Authenticate with a private registry.
SSRF
Server-side request forgery: tricking a tool into contacting internal addresses for an attacker, which OCX guards against when following redirects.
See Publish a package.
trust store
The CA certificates OCX trusts for TLS: the compiled-in Mozilla roots plus the host’s own store.
Machine interface
detail slug
A short, stable machine-readable name for a failure cause, carried in an error document’s error.detail.
See Machine interface.
error document
The JSON object a failing command prints on stdout under --format json, naming the exit code and a detail slug.
See Machine interface.