Skip to content

Work offline

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

Choose where OCX reads from

Once the local index is populated and the object 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 object store are self-sufficient before a build in a restricted or air-gapped environment.

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

Terminal window
ocx index update nodejs/node
ocx package install nodejs/node:24
ocx --offline package install nodejs/node:24

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.

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 local index. 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 shipped 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 object 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 object store, 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.

Refreshing the index

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

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 nodejs/node:24 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, the public index, which 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.