Work offline

Run OCX without network access, from a local index and package store you prepared earlier.

Choose how strictly to avoid the network

Once the local index is populated and the package store holds the binaries you need, OCX runs without network access. Two flags control how strictly it avoids the network:

Mode	Flag	Source	Network?
Default	(none)	Local index	No (unless fetching a new binary)
Remote	--remote	OCI registry	Yes
Offline	--offline	Local index	Never

--offline prevents any network access for that command. If the local index does not have a requested package, the command fails immediately instead of querying a registry. Use it to verify that the current index and package store are self-sufficient before a build in a restricted or air-gapped environment.

To prove that, prepare while online, then repeat the build commands with --offline:

ocx index update kitware/cmake
ocx package install kitware/cmake:3.31
ocx --offline package install kitware/cmake:3.31

The last command succeeds without contacting a registry when the index and store hold everything the package needs. If anything is missing, it fails at once instead of querying a registry.

--remote queries the live registry directly without committing the result to the local index. Use it for one-off checks of currently available tags.

Each flag has an environment spelling for CI and container setups where the command line is not controlled. The flag takes precedence over its variable in both cases.

• OCX_OFFLINE set to a truthy value is the same as --offline. Tag to digest resolution must then come from the local index or from a digest-pinned identifier. An unpinned tag missing from the local index errors immediately.
• OCX_REMOTE is the same as --remote. It routes mutable lookups (tag list, catalog, tag to manifest resolution) to the registry.

The pure-query commands ocx index list, ocx index catalog and ocx package description pull do not persist what they read. Run ocx index update explicitly to refresh the snapshot. Digest-addressed reads still consult the local index first, since immutable content is safe to cache.

Set both and you get pinned-only mode: no registry contact and no local writes. A tag-addressed resolution that the local copy cannot satisfy errors instead of falling back. For ocx package verify, offline scopes to the Sigstore trust services (the Rekor key fetch and TUF), not the artifact registry. See air-gapped verification.

--index / OCX_INDEX only change which collection is read from. They are useful when consuming a bundled index copy from a GitHub Action or Bazel rule.

What the index resolves offline

The index resolves version choice offline, meaning which platform-manifest digest a tag points to. It is not a lock: ocx.lock already records the exact digest it pinned and never consults the index to read it back.

A tag’s local entry points at a dispatch object. That object is an OCI image index carrying the full platform to digest map, cached alongside the tag pointer and verified by digest. A digest-pinned reference (pkg@sha256:...) names the platform-manifest digest directly and has no dispatch object at all.

Either way, a git-committed .ocx/index/ resolves the tag’s version choice on a clean clone with no network. Fetching the actual manifest and layers still needs the registry the first time a given digest is installed, unless the package store is already warm.

What has to travel for a home copy to work offline

A CI cache restore, a container image layer or a devcontainer feature’s shipped cache copies $OCX_HOME between machines. That copy has to carry the stores that ocx package install, ocx package exec and a project’s ocx exec need to work with zero egress on the target machine. Copy the wrong subset and a command either silently reaches back out to the network or fails outright.

Three stores make a copy fully offline-capable: blobs/ (manifests), layers/ (extracted archives) and the local index (tag to digest resolution). packages/ does not need to be part of the copy, because it holds hardlink assemblies of layers/ content built locally at install time.

A fresh $OCX_HOME seeded with only blobs/, layers/ and index/ still installs, runs and toolchain-runs every package those three stores cover. OCX reconstructs packages/ on demand from the local layer cache, with no egress required.

Anything the copy is missing fails closed instead of reaching the network. --offline refuses with exit code 81 rather than falling through to a registry a restricted or air-gapped environment may not even reach.

Learn more

Indices In Depth: wire layout, dispatch objects, shipped copies. Storage In Depth: the layer store and how packages/ is assembled from it.

Refreshing the index

ocx index update <package> syncs the local index for a specific package:

• Bare identifier (e.g., cmake) downloads every tag.
• Tagged identifier (e.g., kitware/cmake:3.28) fetches only that single tag, ideal for lockfile workflows.

To refresh a whole registry rather than one package, ocx index sync <REGISTRY> refreshes every package that registry’s own catalog lists, each as if named bare.

On a fresh machine, ocx package install kitware/cmake:3.28 does not need an explicit index update first. When the local index has no entry for the requested tag, OCX resolves it against the registry, persists it and proceeds with the install.

Packages published through index.ocx.sh

A package identified as ocx.sh/<namespace>/<package> resolves through index.ocx.sh, a pointer index that tracks which physical registry hosts each package. Resolution and offline behavior work the same way as for a direct registry reference. Publisher signals like deprecated or yanked surface as warnings rather than being acted on silently.

Learn more

Indices In Depth: one format with many copies, the remote query path, index internals and the fresh-machine fallback. Indices In Depth: index.ocx.sh: why the identity is stable across registry moves, resolution pipeline, caching, status surfacing. Versioning In Depth: Locking: how ocx.lock pins independent of any index.