[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, Docker and Kubernetes configuration, a standalone preflight-image pull check, and retained task-Job verification.
• Documents Docker and Kubernetes pull policies and image overrides in the worker reference.
• Aligns rootful Linux Docker socket access across the quickstart, reference, security, and troubleshooting pages. It narrows the container command to Linux and points macOS and Windows users to host binaries because Docker Desktop socket behavior was not source-verified.

Content design plan

Target audience and their JTBD: An enterprise platform engineer deploying self-hosted workers into a restricted network who needs the core workload images 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 Warp Agent runs with Docker and Helm deployments. Excludes registry-vendor setup, certificate distribution, Computer Use, and third-party harness images.

Known limitations

• Computer Use and third-party harnesses require additional images. Coordinate those workloads with Warp before blocking public-registry access.
• Docker sidecar pulls do not use registry credentials. Authenticated sidecar repositories require pre-pulled local images with image_pull_policy: "Never"; otherwise, the repository must allow anonymous reads.
• The quickstart and containerized Docker example target rootful Linux. On macOS or Windows, run the worker as a host process and configure its Docker endpoint; that path was not integration-tested for this PR.

Unverified claims

None — worker image identity, host binary availability, authenticated task-image pulls, unauthenticated Docker sidecar pulls, local-only Never pull behavior, minimum Docker-configuration releases, image overrides, Helm values, pull-secret placement, preflight Job behavior, and sidecar tags were verified against oz-agent-worker@19f897d934a898f04b8d30ae993d2e94b3e6fe18, its published releases and assets, warp-server@6ce1e1cb06b73402f83a736a39e2664cc2c8dab4, the official Skopeo and Kubernetes registry-authentication references, and the public Warp Agent tags page.

Documentation risk

Risk: engineering-review-required
Rationale: Adds registry mirroring commands, Docker and Helm configuration, security-relevant egress guidance, and the requirement to pre-pull authenticated Docker sidecar images. The existing managed Kubernetes page remains above the feature-doc budget because it combines backend setup, configuration reference, and operations; this revision keeps its preflight correction concise rather than restructuring the page.
Source files consulted: oz-agent-worker@19f897d: Dockerfile, main.go, internal/config/config.go, internal/worker/{docker,kubernetes,worker}.go, charts/oz-agent-worker, published release assets; warp-server@6ce1e1c: config/prod.yaml, logic/ai/ambient_agents/workers/selfhosted/websocket.go, logic/cloud_environments.go
Docs override: none

Verification

• python3 .agents/skills/style_lint/style_lint.py --changed — passed with 0 issues.
• python3 .agents/skills/check_for_broken_links/check_links.py --internal-only — passed with 0 broken links across 4,318 internal links.
• python3 .agents/skills/doc_quality_policy/check_compression_contract.py — passed for the private-registry feature page, quickstart, and managed Docker page. The managed Kubernetes page reports 1,982 words against the 1,500 feature-doc budget; its origin/main baseline is already 1,963 words, so this targeted correction does not split the existing combined setup, reference, and operations page.
• python3 .agents/skills/create_pr/check_pr_body.py /tmp/pr774-body.md --require-lead-section "## What this feature does" and python3 .agents/skills/doc_quality_policy/check_pr_contract.py --body /tmp/pr774-body.md — passed for 8 changed files and 0 VERIFY markers.
• Extracted and syntax-checked all 31 Bash examples on the revised private-registry, managed-Docker, quickstart, and reference pages with bash -n — passed.
• Parsed the standalone preflight Job manifest and verified its image, pull secret, pull policy, command, pre-install ordering, and file-based registry Secret creation against private-registry-values.yaml — passed.
• Verified the documented oz-agent-worker API-key Secret name against the chart helper and Deployment template — passed. Helm was unavailable, so helm template was not run.
• npx -y node@24.11.0 scripts/generate-openapi-json.mjs and npx -y node@24.11.0 --stack-size=16384 node_modules/astro/bin/astro.mjs build — passed; Pagefind indexed 396 HTML files and the server build completed.
• npm run build with the environment's default Node stack — failed in the unrelated global /_llms-txt/support.txt generator with Maximum call stack size exceeded; the expanded-stack build above completed.
• trunk check — unavailable because Trunk is not installed in this environment.
• Registry, Docker daemon, Kubernetes cluster, and macOS or Windows host-process integration tests were not run; configuration names and behavior were verified against the current worker and server 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	Oct 6, 2026 7:32pm 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

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• src/content/docs/platform/self-hosting/private-container-registry.mdx:140 — [IMPORTANT] "Confirm the worker logs show the private task and sidecar references" does not hold at the default log level: the Kubernetes backend logs the task image only at debug level (oz-agent-worker internal/worker/kubernetes.go:200) and the Helm chart defaults worker.logLevel to info. Requested change: tell readers to set worker.logLevel: debug for the test run, or drop the log claim and rely on the Pod image inspection (for Docker, cite the Pulling image and Reusing local image info lines).
• src/content/docs/platform/self-hosting/private-container-registry.mdx:67 — [SUGGESTION] image_pull_policy: "IfNotPresent" with the mutable warp-agent:latest sidecar contradicts the line 23 advice to refresh the mirror regularly, because hosts that already hold the image keep the old copy. Requested change: note that refreshed latest images reach only hosts that pull them and recommend Always or a pinned tag, or choose a policy that matches the refresh advice.
• src/content/docs/platform/self-hosting/private-container-registry.mdx:99 — [SUGGESTION] tag: WORKER_TAG is a literal YAML placeholder while the page defines WORKER_TAG only as a shell variable and uses YOUR_WORKER_RELEASE_TAG in the git clone at line 116; TASK_POD at line 144 is never explained. Requested change: use one placeholder name for the release tag across the skopeo, Helm values, and clone steps, and add a sentence before the kubectl get pod command explaining TASK_POD.
• src/content/docs/platform/self-hosting/private-container-registry.mdx:116 — [SUGGESTION] The Helm install runs git clone https://github.com/warpdotdev/oz-agent-worker.git on a network the page assumes cannot reach public registries, so GitHub may also be blocked. Requested change: tell readers to fetch charts/oz-agent-worker for the release tag ahead of time and use an internal copy of the chart in this step.
• src/content/docs/platform/self-hosting/private-container-registry.mdx:159 — [SUGGESTION] The caveat that the Warp environment image controls the task image and the worker does not rewrite its registry host appears at lines 71, 128, and 159, which violates the AGENTS.md Say it once rule. Requested change: keep the full statement at line 71 and shorten lines 128 and 159 to a one-line pointer to the environment-image step.
• src/content/docs/platform/self-hosting/managed-kubernetes.mdx:199 — [SUGGESTION] "Warp-hosted agents instead use the private-registry credential assigned to their runner" is off-topic on the Kubernetes backend page, has no blank line separating it from the RBAC paragraph, duplicates private-container-registry.mdx line 10, and depends on warp-server source this review could not verify. Requested change: keep only the self-hosted imagePullSecrets sentence here, add a blank line before it, and leave the hosted-runner statement on the private-container-registry page.

Verdict

Request changes

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• src/content/docs/platform/self-hosting/private-container-registry.mdx:115-126 — [IMPORTANT] The helm upgrade --install step never creates or references the API key Secret. The chart defaults warp.apiKeySecret.create to false and reads WARP_API_KEY from the pre-existing Secret oz-agent-worker, so the worker pod cannot start and the log check at line 135 never succeeds. Requested change: add a step that creates the Secret in warp-oz before installing (or set warp.apiKeySecret.create and value), or link to the warp.apiKeySecret.* values in the Managed: Kubernetes page.
• src/content/docs/platform/self-hosting/private-container-registry.mdx:130 — [SUGGESTION] The ## Verifying registry isolation section covers only the Kubernetes backend, but the page also configures the Docker backend, which has no verification path. Requested change: rename the heading to name Kubernetes, or add a short Docker verification (for example, worker logs showing the pulled image names).
• src/content/docs/platform/self-hosting/managed-kubernetes.mdx:200 — [SUGGESTION] The added sentence 'Self-hosted task pods use the registry credentials in imagePullSecrets.' does not name the setting and sits between the RBAC and instance-shape paragraphs. Requested change: name kubernetesBackend.podTemplate.imagePullSecrets, link to the private container registry page, and move the sentence next to the pod template or preflight discussion.
• src/content/docs/platform/self-hosting/managed-docker.mdx:110 — [SUGGESTION] The 'Common CLI flags' block uses --group-add "$DOCKER_SOCKET_GID" without defining the variable in that block, while the registry example later computes the GID inline with stat. Requested change: define DOCKER_SOCKET_GID in this block or point to the earlier definition, and use one pattern in both places.

Verdict

Request changes

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• src/content/docs/platform/self-hosting/quickstart.mdx:44 — [IMPORTANT] stat -c '%g' is GNU syntax, but line 22 says Docker Desktop on macOS works for testing, and macOS stat rejects -c, so --group-add fails. The same command was added at reference.mdx:39 and managed-docker.mdx:62, :109, and :210. Requested change: scope these examples to a rootful Linux daemon and give macOS and Windows Docker Desktop users a working alternative or a pointer to the Homebrew or binary install, confirmed with engineering.
• src/content/docs/platform/self-hosting/managed-kubernetes.mdx:205 — [IMPORTANT] Compression contract: the page is 2035 words against the 1500 feature-doc budget (1963 before this PR, +72), yet the PR body says the check passed for both managed backend pages and gives no justification for the overage. Requested change: correct the claim and add a justification to the PR body, or trim the added preflight text; do not split the page to fix it.
• src/content/docs/platform/self-hosting/private-container-registry.mdx:11 — [SUGGESTION] "Self-hosted workers use registry credentials from your Docker or Kubernetes infrastructure." is vague and restates later sections. Requested change: delete it or replace it with the specific fact the reader needs before the image inventory.
• src/content/docs/platform/self-hosting/private-container-registry.mdx:24 — [SUGGESTION] The page tells readers to pin the worker image but mirrors and configures the mutable warpdotdev/warp-agent:latest tag, and the server-sent tag could not be verified against warp-server. Requested change: confirm latest is the supported tag and add one sentence on why it is not pinned and whether a digest is supported.
• src/content/docs/platform/self-hosting/private-container-registry.mdx:75 — [SUGGESTION] The Docker verification only says to confirm the run succeeds, so it doesn't show that no image still comes from a public registry, unlike the Kubernetes section. Requested change: add a step that shows which task and sidecar images the worker used, or state that this section doesn't verify image sources.
• src/content/docs/platform/self-hosting/private-container-registry.mdx:115 — [SUGGESTION] defaultImage only applies when the run has no Warp environment image (the server-provided image takes precedence in defaultImageForTask), but this section doesn't say so, unlike the Docker section. Requested change: add that sentence here before the egress-blocking guidance.
• src/content/docs/platform/self-hosting/reference.mdx:173 — [NIT] startupPreflightJob in kubernetes.go also applies ImagePullPolicy to the preflight image. Requested change: change "task and sidecar images" to "task, sidecar, and preflight images".

Verdict

Request changes

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• src/content/docs/platform/self-hosting/private-container-registry.mdx:57-71 — [CRITICAL] The Docker backend pulls the Warp Agent sidecar and additional sidecars with no registry credentials (oz-agent-worker docker.go:611 passes an empty auth string; getRegistryAuth is used only for the task image at docker.go:129). Setting sidecar_image: registry.internal.example.com/warp/warp-agent:latest while the text says Docker credentials apply will fail with pull access denied on any authenticated registry. Requested change: state that Docker sidecar pulls are unauthenticated, so the mirrored warp-agent repository must allow anonymous pulls (or give a supported pre-pull and pull-policy alternative). Correct the Docker troubleshooting entry at lines 216-217 and the verification guidance to match, and update the 'Unverified claims' and 'Documentation risk' sections.
• src/content/docs/platform/self-hosting/managed-docker.mdx:191 — [CRITICAL] The rewritten 'Private Docker registries' intro removed the previously accurate statement that sidecar images come from public registries and need no authentication, and now implies the worker's Docker credentials cover all pulls. Requested change: restore that distinction and link to the registry page's sidecar anonymous-pull requirement.
• src/content/docs/platform/self-hosting/security-and-networking.mdx:71 — [SUGGESTION] The edit replaced 'Ensure appropriate access controls on the host' with only mounting instructions, so the Docker backend section no longer warns that socket access is host-privileged. Requested change: keep a one-sentence caution that access to the Docker socket is equivalent to elevated host access, alongside the new group-ID instructions.
• src/content/docs/platform/self-hosting/managed-kubernetes.mdx:206 — [SUGGESTION] The preflight paragraph adds implementation detail (root init container versus image volume mount) on a page already at 2,005 words against the 1,500-word feature-doc budget; the overage is justified in the PR body, but this detail is not something the reader can act on. Requested change: shorten the sentence to what is checked and how to override the image, and link to the reference page for the rest.

Verdict

Request changes

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• src/content/docs/platform/self-hosting/private-container-registry.mdx:59 — [SUGGESTION] The containerized worker flow logs in with a dedicated docker --config "$WORKER_DOCKER_CONFIG" directory, but the plain docker pull that follows doesn't read it, so the sidecar pre-pull can fail with pull access denied. Requested change: name the credentials the pre-pull needs, for example by showing sudo docker --config "$WORKER_DOCKER_CONFIG" pull ... for that case.
• src/content/docs/platform/self-hosting/private-container-registry.mdx:62 — [SUGGESTION] image_pull_policy and sidecar_image under backend.docker exist only in recent worker releases, but neither this page nor reference.mdx states a minimum version. Requested change: add the minimum worker release (the PR body says v2026-09-18-23-15-02) to the Docker section so readers on older pinned tags don't hit config validation errors.
• src/content/docs/platform/self-hosting/private-container-registry.mdx:229 — [NIT] The ### Kubernetes reports ImagePullBackOff`` heading has no blank line before its paragraph, unlike the Docker heading above it (markdownlint MD022). Requested change: insert a blank line after the heading.
• src/content/docs/platform/self-hosting/managed-docker.mdx:73 — [SUGGESTION] The Docker Desktop sentence (and the matching change at quickstart.mdx:22) replaces the earlier "Docker Desktop works for testing" claim, but none of the cited source files cover Docker Desktop socket permissions and ## Unverified claims says None. Requested change: cite the evidence in the PR body, or add a VERIFY marker and list it under ## Unverified claims.
• src/content/docs/platform/self-hosting/managed-docker.mdx:191 — [SUGGESTION] The explanation that sidecar pulls don't use registry credentials and that authenticated sidecar repositories need pre-pulled images appears here, in private-container-registry.mdx (Docker section and Troubleshooting), and in the PR's known limitations. Requested change: keep the full explanation on the private-container-registry page and reduce this paragraph to a one-line pointer.
• src/content/docs/platform/self-hosting/managed-kubernetes.mdx:206 — [SUGGESTION] The page is 2,000 words against the 1,500-word feature-doc budget. The overage is justified in the PR body, so it is not blocking. Requested change: when touching the preflight paragraph, drop a sentence, for example the trailing use_image_volumes pointer that the reference page already covers.

Verdict

Approve with nits

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• src/content/docs/platform/self-hosting/quickstart.mdx:22 — [SUGGESTION] "rootful Docker daemon" is unexplained at first use, and removing the Docker Desktop line leaves macOS and Windows readers with no path; the next section's stat -c '%g' is GNU stat and fails on macOS. Requested change: define "rootful" in a clause, point those readers to the Homebrew or binary install (managed-docker Option 2), and note the GNU stat limitation.
• src/content/docs/platform/self-hosting/managed-docker.mdx:25 — [SUGGESTION] The edit drops the statement that Docker Desktop works for testing and that the worker host can use any OS, and the PR body does not record why. Requested change: record the reason in the PR body, and add a one-line statement of what macOS and Windows hosts should do or confirm none is intended.
• src/content/docs/platform/self-hosting/managed-kubernetes.mdx:206 — [SUGGESTION] The page is 1,989 words against the 1,500 feature-doc budget (justified in the PR body as a pre-existing overage), and the rewritten sentence "Failure stops the worker before tasks" is clipped. Requested change: restore plain wording such as "If preflight fails, the worker exits before accepting tasks."
• src/content/docs/platform/self-hosting/reference.mdx:165 — [SUGGESTION] Docker sidecar_image first shipped in worker release v2026-08-28-21-43-14 and Docker image_pull_policy in v2026-08-20-16-38-31, but the reference entries state no minimum release, so readers on older workers get a rejected config key. Requested change: add the minimum release to both entries.
• src/content/docs/platform/self-hosting/private-container-registry.mdx:86 — [SUGGESTION] The Docker section sets worker.yaml options but never shows how the containerized worker receives that file, and the mirrored worker image needs registry credentials on the host to be pulled. Requested change: add the --config-file flag with a mount (linking to the reference config-file section) and a sentence on authenticating the host before docker run.
• src/content/docs/platform/self-hosting/private-container-registry.mdx:183 — [SUGGESTION] "The connection message confirms that the worker passed Kubernetes API, RBAC, and Pod admission checks..." explains what the log line already shows. Requested change: keep only the sentence that the test run verifies registry credentials, or delete the paragraph.

Verdict

Approve

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• src/content/docs/platform/self-hosting/private-container-registry.mdx:182 — [SUGGESTION] kubectl logs --follow never exits, so a reader following the page top to bottom stays in this command. Requested change: tell the reader to press Ctrl+C once Successfully connected to server appears, or drop --follow and add --tail so the command returns.
• src/content/docs/platform/self-hosting/private-container-registry.mdx:92 — [SUGGESTION] The Kubernetes configuration is a sequence of about six dependent actions (create Secrets, write values, package the chart, copy it, extract it, install) presented as unnumbered code blocks. Requested change: put these actions in a numbered list so the order and the expected outcome of each step are clear.
• src/content/docs/platform/self-hosting/private-container-registry.mdx:82 — [SUGGESTION] "Refresh the mirror regularly" already appears in the Images to mirror section at line 22. Requested change: keep it in one place and delete the repeat here, keeping only the new point that the sidecar uses the mutable latest tag.
• src/content/docs/platform/self-hosting/managed-docker.mdx:25 — [SUGGESTION] This change removes the documented Docker Desktop on macOS and Windows testing path, and the PR body's Changes list does not mention it. The replacement host-process path was not integration-tested, per the PR body. Requested change: say in the PR body that the prerequisite is deliberately narrowed, or keep a short statement of what is and is not verified for macOS and Windows hosts.
• src/content/docs/platform/self-hosting/managed-kubernetes.mdx:206 — [SUGGESTION] This page is about 1,993 words against the 1,500-word feature-doc budget. The overage is justified in the PR body and pre-dates this PR (1,963 words on main), so it does not block. Requested change: plan a follow-up that moves the configuration reference or operations material onto its own page.

Verdict

Approve with nits

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• src/content/docs/factories/self-hosting/private-container-registry.mdx:73 — [SUGGESTION] "run docker login registry.internal.example.com on the host" does not say which account performs the login, and the surrounding steps use a separate sudo docker --config "$WORKER_DOCKER_CONFIG" config for task-image credentials. Requested change: state that this login applies to the account that runs docker run for the worker image (use sudo docker login if run with sudo) and is separate from the dedicated task-image Docker config.
• src/content/docs/factories/self-hosting/managed-kubernetes.mdx:206 — [SUGGESTION] The page is 1,982 words against the 1,500-word feature-doc budget; the overage is pre-existing (1,963 on main) and justified in the PR body, so it does not block. Requested change: track a follow-up deletion-only cut pass or move pod template and operations material to a separate reference or operations page instead of adding more content to this page.

Verdict

Approve

[joeywangzr]

Not sure if this is true, prod sends a static tag, so there shouldn't be a verion-matched tag