docs: Document external orchestrator deployments

[warp-agent-staging]

What this feature does

Self-hosted workers can hand runs to external schedulers in two supported ways: one Direct worker per job with --one-shot, or a long-lived Command backend that dispatches a versioned task payload. Shipped in worker release v2026-09-18-23-15-02 (2026-09-18).

Summary

Adds a reference deployment for teams that use an external CI system, Kubernetes controller, or internal scheduler to allocate agent compute.

Changes

• Adds external-orchestrators.mdx with architecture guidance, a one-shot Direct example that disables the CLI idle period, and the released Command backend example.
• Documents the Command backend, --one-shot, and one_shot in the self-hosted worker reference.
• Adds sidebar placement and cross-links from the Direct and unmanaged pages.

Content design plan

Target audience and their JTBD: A platform engineer who already has an internal scheduler and needs Warp to route and track runs without replacing that compute lifecycle.

Problem statement: Existing self-hosting pages describe long-lived managed workers or unmanaged CLI invocation, but do not show the supported bridge between Warp routing and externally allocated jobs.

Goals:

• The reader can choose between one-shot Direct workers and the Command backend.
• The reader can route one run to an externally allocated worker.
• The reader can connect the released Command backend example to an existing job API.

Purpose and value added: This page gives enterprise evaluators a concrete supported starting point without expanding the main backend setup pages into another deployment walkthrough.

Content type and model: Feature documentation (combined) because the reader needs both pattern selection and a working setup.

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

High-impact scenarios: Covers one worker per CI, VM, or pod job and a long-lived dispatcher for an existing runtime API. Excludes implementation details for customer-specific schedulers and unmanaged runs that do not need Warp routing.

Unverified claims

None. Worker flags, config fields, idle timeout precedence, dispatch behavior, and shutdown reporting were verified against oz-agent-worker@530bbe934a632910dfe8818ab7b4c6027a3473ef, including main.go, internal/config/config.go, internal/common/task_utils.go, internal/worker/command.go, internal/worker/direct.go, and examples/command-backend/.

Documentation risk

Risk: engineering-review-required
Rationale: Adds a new self-hosting workflow with CLI flags, lifecycle behavior, and Command backend configuration.
Docs override: none

Verification

• python3 .agents/skills/style_lint/style_lint.py --changed — exited 0; reported inherited warnings in managed-direct.mdx and unmanaged.mdx, plus a glossary suggestion for the new table label.
• 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/external-orchestrators.mdx --content-type feature-doc — passed.
• Extracted and syntax-checked both documented Bash examples with bash -n.

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 20, 2026 5:56pm 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]

@warp-agent-staging[bot]

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 new self-hosting documentation page for external orchestrator deployments, updates the worker reference for the Command backend and one-shot Direct mode, and adds sidebar and related-page links.

Concerns

• No blocking concerns found in the changed diff.
• The supplemental security pass found no diff-backed security findings.
• The pre-verdict audit found no added code comments or tests to review.
• No approved or repository spec context was available, so there is no implementation/spec drift to assess.

Verdict

Found: 0 critical, 0 important, 0 suggestions

Approve

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

• src/content/docs/platform/self-hosting/external-orchestrators.mdx:9 — [SUGGESTION] The intro calls the second pattern a 'long-lived Command worker', but every other reference on this page and in reference.mdx calls it the 'Command backend'. Requested change: rename to 'Command backend' for consistency.
• src/content/docs/platform/self-hosting/external-orchestrators.mdx:32-34,76-79,113-116 — [SUGGESTION] Bulleted list items use a plain hyphen after bold terms/links, while every sibling page in platform/self-hosting/ (quickstart.mdx, managed-direct.mdx, reference.mdx, index.mdx, monitoring.mdx, troubleshooting.mdx) uses an em dash ('—') in this position. Requested change: switch to em dash for consistency with the rest of the section.
• src/content/docs/platform/self-hosting/external-orchestrators.mdx:17 — [NIT] style_lint flags the bolded table term "One-shot Direct worker" as not present in the terminology glossary. Requested change: add the term to .agents/references/terminology.md or rephrase to reuse an existing glossary term.

Verdict

Approve with nits