- docs
- Publish and integrate
- Publish and integrate
- Integrations
- Docker
Docker
Official OCX container images live at ghcr.io/ocx-sh/ocx. Each image is the release binary from GitHub Releases placed on a slim base. Nothing is compiled in the image, so the ocx inside a tagged image is bit-identical to the archive of the same release. Images are published for linux/amd64 and linux/arm64 as multi-platform manifests, so docker pull resolves the right architecture automatically.
docker run --rm ghcr.io/ocx-sh/ocx ocx versionThe images bake in OCX_NO_UPDATE_CHECK=1: the OCX version is pinned by the image tag, so the self-update notice would be pure noise.
Images and Tags
Two images cover the practical spectrum. The default rides Debian for glibc compatibility with whatever else your build installs. The Alpine image carries the fully static musl build and stays small.
| Image | Base image | Binary | Use when |
|---|---|---|---|
trixie (default) |
debian:trixie-slim |
glibc (*-unknown-linux-gnu) |
You add packages via apt, or run glibc-linked tools |
alpine |
alpine:3 |
static musl (*-unknown-linux-musl) |
Small images, or as a universal COPY --from source |
Tags follow the Docker official images convention: version prefixes at every precision, with unsuffixed tags aliasing the default image.
| Tag | Image | Moves when |
|---|---|---|
0.9.2-trixie, 0.9-trixie, 0-trixie, trixie |
trixie | new release / weekly rebuild |
0.9.2-alpine, 0.9-alpine, 0-alpine, alpine |
alpine | new release / weekly rebuild |
0.9.2, 0.9, 0, latest |
trixie (alias) | new release / weekly rebuild |
0.9.2-trixie-20260708, 0.9.2-alpine-20260708 |
date-stamped | never — immutable |
All rolling tags, including the full X.Y.Z version tags, are re-pointed by a weekly rebuild that refreshes the base image. So security fixes in Debian or Alpine reach the images without waiting for the next OCX release. Only the latest release is rebuilt, so every other version keeps its tags on the base it shipped with.
Copy the Binary
The lightest way to use the images is not to base your image on them at all. Copy the binary out instead, the way uv documents for its images:
COPY --from=ghcr.io/ocx-sh/ocx:0.9.2-alpine /usr/local/bin/ocx /usr/local/bin/ocxThe -alpine image is the right source for this: its binary is fully statically linked, so it runs on any base. That includes Debian, Alpine, distroless and even scratch. The trixie image’s glibc binary works too, but only on glibc bases.
Bake a Project Toolchain
A project that pins its packages in ocx.toml and ocx.lock wants those exact packages inside its image. The wrong way is to resolve them when the container starts. Every cold start then depends on registry availability, needs credentials at runtime, and can drift from what was tested. The right way is to pull at build time and run offline afterwards.
FROM ghcr.io/ocx-sh/ocx:0.9.2
WORKDIR /app# Lockfile layer first — Docker caches the pull until the lock changes.COPY ocx.toml ocx.lock ./RUN ocx pull
COPY . .ENTRYPOINT ["ocx", "--offline", "exec", "--", "task", "serve"]ocx pull walks the lock file and downloads the digest-pinned packages of the default group for the image platform. An image that needs group tools passes -g all or -g <group>. It needs both files and touches nothing else, which makes it an ideal cache layer. ocx exec composes the project environment and replaces itself with the child process, so no wrapper lingers in the process tree. --offline turns any accidental network dependency into a hard error at start instead of a silent pull. If the image builds, it runs.
Reproducible Resolution
The project-toolchain build above runs a plain ocx pull, which resolves whatever a tag points to at pull time. If the tag drifted since you wrote the lock file, the build still succeeds, but with a version you never tested.
Swap in ocx --frozen pull to close that gap. Frozen freezes tag→digest resolution to what the lock file already pins. A tag missing from the lock errors instead of resolving fresh, so no unpinned version slips into the image. It is not a network ban: the digest-pinned blobs still download, and frozen only refuses to discover a new mapping. Paired with the --offline run already in that Dockerfile, drift becomes a hard error at build time rather than a silent swap.
Fully air-gapped builds
--frozen pull still reaches the registry for the digest-pinned blobs. For a build with no network at all, vendor a warm OCX_HOME into the build context. That is a directory populated by ocx pull. Then run the pull under --offline, which resolves entirely from that populated OCX home and never touches the network.
Resolving a bare tag like nodejs/node:24 deterministically without a lock file is a different mechanism. This is the GitHub Actions and Bazel case. Ship a copy of the index with the image and point OCX at it with OCX_INDEX. See Shipped copies.
Private Registries
ocx pull against a private registry needs credentials during docker build. Never bake them in with ENV or ARG, because both persist in image history. Use BuildKit secrets, which mount for a single RUN and leave no layer behind:
ENV OCX_AUTH_registry_example_com_TYPE=bearerRUN --mount=type=secret,id=ocx_token,env=OCX_AUTH_registry_example_com_TOKEN \ ocx pulldocker build --secret id=ocx_token,env=REGISTRY_TOKEN .The variable name encodes the registry host: every character that is not an ASCII letter or digit becomes an underscore, and case is kept (registry.example.com → registry_example_com, my-registry.example.com:5000 → my_registry_example_com_5000). The auth type itself is not secret and can stay a plain ENV. See OCX_AUTH_<REGISTRY>_TOKEN for the user/type companions.
Bootstrap Single Packages
To bootstrap a few packages in a Dockerfile without an application project, the same pattern shrinks to a minimal project. It takes two files declaring the packages, and the pull happens at build time with the identical caching behavior.
[tools]shellcheck = "ocx.sh/shellcheck/shellcheck:0.10"shfmt = "ocx.sh/shfmt/shfmt:3"Run ocx lock locally and commit both files. Then the project toolchain pattern applies unchanged. ocx exec -- <cmd> composes the environment for exactly that command: the binaries on PATH and the variables their packages declare.
For CI pipelines that run inside these images, see GitHub Actions or GitLab CI. They cover caching, matrix setups, and the full project-mode flow.