docs: Document private container registry pulls

[warp-agent-staging]

What this feature does

Self-hosted Docker and Kubernetes workers can pull worker, task, sidecar, and preflight images from an internal registry after those images are mirrored. Shipped in worker release v2026-09-18-23-15-02 (2026-09-18).

Summary

Adds a reference deployment for networks that cannot pull self-hosted worker images directly from public registries.

Changes

• Adds private-container-registry.mdx with an image inventory, multi-architecture Skopeo copy commands, non-root Docker credentials and socket access, safe Kubernetes secret creation, and Helm values.
• Documents Docker and Kubernetes image overrides in the worker reference.
• Replaces the incomplete Docker registry section with a link to the full deployment and adds Kubernetes and sidebar cross-links.

Content design plan

Target audience and their JTBD: An enterprise platform engineer deploying self-hosted workers into a restricted network who needs every supported workload image to come from an approved internal registry.

Problem statement: Existing pages mention registry credentials and the Kubernetes preflight image separately, but do not identify the full core image set or show how Docker and Kubernetes pull from a mirror.

Goals:

• The reader can inventory and mirror the core worker images without dropping image architectures.
• The reader can configure Docker and Kubernetes pulls with the correct credentials and image overrides.
• The reader can verify image references before blocking public-registry egress.

Purpose and value added: The page gives evaluators one deployable registry-isolation path while keeping backend pages focused on their primary setup.

Content type and model: Feature documentation (combined) because the reader needs image-selection context, mirror commands, backend configuration, and verification.

Skills and templates to use: draft_feature_doc and .agents/templates/feature-doc.md, with procedural guidance from draft_procedural.

High-impact scenarios: Covers the core Warp Agent with Docker and Helm deployments. Excludes registry-vendor setup, certificate distribution, and unsupported optional sidecars that have no deployable override.

Known limitations

• The Docker backend overrides only the core Warp Agent sidecar; it cannot rewrite arbitrary server-provided sidecars.
• The Kubernetes config supports coding_cli_sidecars, but the current Helm chart does not expose that field.
• The worker does not expose a stable pre-dispatch method to discover the exact version-matched Warp Agent tag. Operators must coordinate the mirrored tag with Warp and validate it during worker upgrades.
• Fully blocked public-registry egress is not supported for every optional harness or Computer Use run until all required sidecars have supported overrides.
• The containerized Docker example supports rootful Linux daemon sockets whose group has read and write access. Other Docker endpoints need their own access controls.

Unverified claims

None. Worker image identity, Docker credential lookup, daemon connection behavior, image override fields, pull policies, Helm values, pull-secret placement, sidecar behavior, and the listed limitations were verified against oz-agent-worker@530bbe934a632910dfe8818ab7b4c6027a3473ef, including Dockerfile, internal/config/config.go, internal/worker/docker.go, internal/worker/kubernetes.go, and charts/oz-agent-worker/.

Documentation risk

Risk: engineering-review-required
Rationale: Adds registry mirroring commands, Docker and Helm configuration, security-relevant egress guidance, and explicit unsupported cases.
Source files consulted: oz-agent-worker/Dockerfile@530bbe9, oz-agent-worker/internal/config/config.go@530bbe9, oz-agent-worker/internal/worker/docker.go@530bbe9, oz-agent-worker/internal/worker/kubernetes.go@530bbe9, oz-agent-worker/charts/oz-agent-worker/@530bbe9
Docs override: none

Verification

• python3 .agents/skills/style_lint/style_lint.py --changed — exited 0; reported inherited warnings in the existing Docker and Kubernetes pages.
• npm run build — passed.
• python3 .agents/skills/check_for_broken_links/check_links.py --internal-only — passed with 0 broken links.
• python3 .agents/skills/doc_quality_policy/check_compression_contract.py src/content/docs/platform/self-hosting/private-container-registry.mdx --content-type feature-doc — passed.
• Extracted and syntax-checked all nine documented Bash examples with bash -n.
• Registry, Docker daemon, and Kubernetes cluster integration tests were not run in this environment; configuration names and behavior were verified against the released worker source.

Co-Authored-By: Oz oz-agent@warp.dev

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs	Ready	Preview	Sep 21, 2026 4:57pm UTC

[warp-agent-staging]

This PR was generated with Warp.

Comment @warp-staging-factory on this PR to send it follow-up work.

  

[warp-for-oss]

@hongyi-chen

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[warp-for-oss]

Overview

This PR adds a private container registry deployment page for self-hosted Docker and Kubernetes workers, updates related self-hosting pages, and adds the page to the sidebar. The overall structure is useful, and the attached spec context contains no approved spec to compare against, but the new Kubernetes examples need fixes before merge.

Concerns

• The pull-secret command documents a registry token as a literal command placeholder; use a safer input pattern so the credential is not copied into shell history and the username/token placeholders are defined before use.
• The Helm values example uses BASE_IMAGE_TAG, but the page never defines that placeholder and the earlier mirror command creates agent-base:22.04.

Verdict

Found: 0 critical, 2 important, 0 suggestions

Request changes

Comment /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• PR body #774 § Documentation risk — [SUGGESTION] The risk section omits a Source files consulted: field per the doc-quality-policy.md template (source files are only listed in prose under '## Unverified claims'). Requested resolution: add Source files consulted: oz-agent-worker/Dockerfile@530bbe9, internal/config/config.go@530bbe9, internal/worker/docker.go@530bbe9, internal/worker/kubernetes.go@530bbe9, charts/oz-agent-worker/@530bbe9 to '## Documentation risk'.
• src/content/docs/platform/self-hosting/private-container-registry.mdx:198-201 — [NIT] The four 'Related pages' bullets use a plain hyphen '-' instead of the em dash '—' used by every other Related-pages list touched in this PR (managed-docker.mdx, managed-kubernetes.mdx, reference.mdx). Requested resolution: replace '-' with '—' in all four bullets for consistency.

Verdict

Approve with nits

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• src/content/docs/platform/self-hosting/private-container-registry.mdx:153 — [SUGGESTION] The Helm install step relies on git clone https://github.com/warpdotdev/oz-agent-worker.git, but a network that blocks public-registry egress (this page's premise) may also block GitHub. Requested resolution: add a note telling readers to pre-stage the repo/chart via an internal mirror before relying on this step.
• src/content/docs/platform/self-hosting/private-container-registry.mdx:47 — [NIT] The Skopeo copy example unconditionally mirrors busybox:1.36, which the table on line 19 scopes to the Kubernetes backend only. Requested resolution: add a short aside telling Docker-only readers they can skip this image.

Verdict

Approve with nits