[warp-agent-staging]

What this feature does

Factory network controls restrict outbound access with factory-wide and per-agent policies. Allowances combine, denials take precedence, and built-in policies provide versioned host lists. Run diagnostics identify blocked hosts. Kubernetes support is pending. Availability is assumed live as explicitly requested; no stable client release is asserted for this server-backed feature.

Summary

Updates the existing Factory definition syntax reference, links it from infrastructure and security, and adds blocked-host API troubleshooting to the existing troubleshooting page. No new page, navigation change, host inventory, or tracking issue.

Content design plan

• Reader and job: A factory maintainer looking up definition fields to restrict outbound access for all agents or one agent.
• Gap today: The reference lacks network-policy syntax, composition/defaults, built-in names, and version discovery.
• Change: Add one reference section and agent-table entry, linked from infrastructure/security. Exclude built-in host inventories, backend setup, and unrelated rewrites.

Diagnostics follow-up

• Reader and job: A factory maintainer diagnosing failed network requests in an agent run.
• Gap today: Configuration is documented, but the troubleshooting page doesn't explain how to retrieve or interpret blocked-host diagnostics.
• Change: Add a symptom/cause/fix section to the existing troubleshooting page, linked from networkPolicy. Cover both API reads, optional timestamps, result interpretation, and policy remedies; exclude refresh mechanics and duplicate authentication setup.

The configuration update inherits draft_reference; diagnostics inherits draft_troubleshooting. The security page stays conceptual. Gate 0 availability follows the requester's explicit assume-live instruction rather than independent production evidence.

Validation

• npm run typecheck: passed, 0 errors (7 existing hints).
• npm run test:heading-vars: passed, 5 tests.
• npm run build: passed; existing route/plugin/bundle warnings.
• npm run test:heading-tocs: passed, 3,394 entries in 401 HTML files.
• npm run test:homepage-json-ld: passed.
• python3 .agents/skills/style_lint/style_lint.py --changed: 3 files, 9 warnings on pre-existing lines; none introduced.
• python3 .agents/skills/check_for_broken_links/check_links.py --internal-only: passed, 4,502 links in 400 files.
• check_compression_contract.py on the expanded reference and troubleshooting pages: passed. The unchanged conceptual page passed in the previous revision.
• git diff --check: passed.
• PR-body integrity: authored prose passes; the full-body repetition check flags duplicated long alt text and captions in the tool-generated screenshot block, retained verbatim. Documentation-risk contract passes.
• Initial factory/agent examples at 2bf303d1: validated with the configured server's v1alpha1 parser. State-dependent apply checks were not run. The same examples are rejected as unavailable by the production validator. The new deny-all example parses as an explicitly present empty YAML policy and matches the source resolver/tests; no new server-side or runtime-enforcement check was performed.
• Configured-server catalog request: returned the three documented policy names and version 1.0.0; production catalog request returned HTTP 401 for this run's credential.
• Chromium/Linux preview: rechecked the revised opening, deny-all instruction/example/scope caveat, catalog HTTP request, authentication link, and Kubernetes caveat. The general API reference link opens successfully and contains authentication guidance. Static screenshots below show documentation rendering, not runtime network enforcement.
• Trunk was not installed, so trunk check and trunk fmt were unavailable.

Diagnostics follow-up verification

• Exact GET paths, include_diagnostics=true, its default, bearer authentication, and shared diagnostics shape match PR 20901 at 4ba2b813. The displayed JSON passes JSON Schema and date-time validation against that revision. Code, message, host metadata, and timestamp meaning match the current emitter.
• Current-run requests to the configured server: dedicated diagnostics returned HTTP 200 with diagnostics: []; opted-in run details returned HTTP 200 but omitted diagnostics. The run-details addition and created_at remain source-verified, not live-verified. No blocked request was induced and no network-policy enforcement was tested.
• Baseline commands above were rerun successfully after npm ci. Final MDX was rebuilt; heading-TOC and JSON-LD checks passed again. Trunk remains unavailable. Dependency installation reported existing Babel engine and patch-version warnings; the build still passed.
• Chromium/Linux static preview: both requests and the complete JSON, interpretation, remedy, and missing/empty-result guidance rendered without clipping. The configuration cross-link reached the new symptom heading; the general API reference opened and showed bearer authentication guidance. Two current captures are included below. These prove documentation rendering, not API deployment or network enforcement.

Security-page cross-link verification

• Added one descriptive link from Network controls on the security page to the existing blocked-host troubleshooting section. Prior prose is unchanged.
• Reran npm run typecheck, npm run test:heading-vars, npm run build, npm run test:heading-tocs, and npm run test:homepage-json-ld: all passed (0 type errors, 5 heading-variable tests, 409 pages, and 3,449 TOC entries).
• style_lint.py --changed: 10 warnings on pre-existing lines; none introduced. Internal-link check: 4,631 links in 408 files, no broken links. Conceptual compression and git diff --check passed. Trunk remains unavailable.
• Generated HTML contains the exact destination and anchor. Chromium/Linux rendered the security link without clipping; clicking it reached Network requests fail during a run and both diagnostics requests. Only the changed security section was captured; the final screenshot below is current.

Source grounding and editorial verdict

Source revision: warp-server@98acfaf46d72e3f59300e374eee33dcfe4923cdd. The published production v1alpha1 JSON Schema confirms field placement, accepted keys, and host-format constraints. The parser and its tests confirm factory/agent placement and reject agentDefaults; the runtime resolver and tests confirm union-minus-denials, empty policies, and required-service allowances. The built-in registry and catalog handler/OpenAPI confirm names, selectors, authentication, and response fields. Kubernetes pending support follows the explicit request; pod-level enforcement was not tested. No private rollout details or built-in host inventories are included.

The definition reference owns configuration details; the infrastructure and security page links to it. Review revision 22d154d7 removes the extra placement caveat, makes deny-all configuration explicit without cancelling other-scope allowances, and delegates authentication guidance to the general API reference.

Diagnostics source revision: warp-server@0c022b5f83fd419c10eeb38aad7d5d21fe5c3173, plus warp-server PR 20901 at 4ba2b81303f3d28009c30e379c0f054a62aaf395 (open during initial verification; merged on 2026-10-30 as 519653c1; production deployment unverified). router/handlers/public_api/agent_diagnostics.go, agent_webhooks.go, public_api/src/base.yaml, logic/ai/ambient_agents/diagnostics/diagnostics.go, and workers/namespace/network_policy.go ground the routes, run access, response shapes, warning code, host metadata, and timestamps. PR tests cover ordinary/false opt-out, explicit opt-in, empty arrays, omitted fields on read failures, and serialization.

The existing troubleshooting page owns the diagnostic workflow; the definition reference links to it instead of acquiring a procedure. The new section distinguishes missing from empty diagnostics and warnings from run outcome. It preserves configuration semantics and prior review wording, adds no comments or internal implementation narrative, and passed a deletion-only concision review.

Unverified claims

• PR 20901's run-details opt-in and created_at have not been observed live. That source PR has merged; confirm production deployment before publishing this API addition. Availability remains the requester's explicit assume-live drafting premise, not a claim of verified rollout.

• Production availability is assumed live per the request, not verified: production example validation reports the capability unavailable, and the catalog request could not authenticate with this run's credential. The configured-server checks do not establish production rollout.

• Kubernetes support is documented as pending per the request; no Kubernetes runtime verification was performed.

Documentation risk

Risk: engineering-review-required
Rationale: Adds configuration examples, network/security semantics, API behavior, and platform-support claims. Production availability follows an explicit drafting assumption.
Source files consulted: diagnostics handlers, emitter, OpenAPI and tests at warp-server 0c022b5f83fd419c10eeb38aad7d5d21fe5c3173 and PR 20901 at 4ba2b813; original configuration sources at warp-server 98acfaf46d72e3f59300e374eee33dcfe4923cdd: logic/factoryfile/v1alpha1.go, logic/factoryfile/schema/common.go, logic/ai/ambient_agents/networking/network_policy.go, policyregistry/{registry.go,builtins.go} in that directory, router/handlers/public_api/networking.go, public_api/src/base.yaml; published v1alpha1 JSON Schema.
Requested engineering reviewers: none
Engineering review status: pending
Docs override: none

Ownership resolution returned only an engineering team, not one human owner. Per the docs review-routing policy, no team or fallback reviewer was requested. bnavetta commented on 2bf303d1; the three requested changes are addressed in 22d154d7 and await review. The PR remains a draft.

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

The final screenshot shows the security-page cross-link. Screenshots 6–7 show the diagnostics revision; 3–5 show unchanged deny-all/catalog content. The first two are historical initial-draft captures.

Computer-use screenshots (8)

networkPolicy syntax example and field table

Built-in policy versions, API discovery, and Kubernetes support subsection

Denying all outbound access subsection with networkPolicy: {} example and cross-scope caveat

Full view: Denying all outbound access instruction, networkPolicy: {} example, cross-scope caveat with surrounding reference context

Policy catalog GET example, API reference link, and pending Kubernetes support text

Blocked-host API requests.

Blocked-host diagnostic response.

Security-page diagnostics link.

[vercel]

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

Project	Deployment	Actions	Updated
docs	Ready	Preview	Oct 30, 2026 12:10pm UTC

[warp-agent-staging]

This PR was generated with Warp.

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

  

[warp-agent-staging]

@bnavetta, your GitHub account is not connected to Warp. Connect your GitHub account.