diff --git a/src/content/docs/factories/factory-as-code.mdx b/src/content/docs/factories/factory-as-code.mdx index 41aa71e62..166f346e6 100644 --- a/src/content/docs/factories/factory-as-code.mdx +++ b/src/content/docs/factories/factory-as-code.mdx @@ -194,6 +194,104 @@ Repository substitutions for benchmark starting states. Each entry requires `sou **Optional.** Names of [managed secrets](/factories/secrets/) granted to every agent, in addition to secrets declared by an agent. +### `networkPolicy` + +**Optional.** +Restricts outbound network access for factory runs. Declare `networkPolicy` at the root of `factory.yaml` for every factory agent, or in an agent's frontmatter for that agent. + +If neither scope declares a policy, outbound access is unrestricted. Once either scope declares a policy, hosts not allowed by the combined policy are blocked, except for services required for the platform to function. + +```yaml title="factory.yaml" +schemaVersion: v1alpha1 +name: payments-factory +repositories: + - owner: acme + name: payments-service +agentDefaults: + model: auto +networkPolicy: + extends: warp/package-registries@1.0.0 + allowedHosts: + - api.example.com + deniedHosts: + - blocked.example.com +``` + +| Field under `networkPolicy` | Description | +| --- | --- | +| `allowedHosts` | Optional list of hostnames or literal IP addresses to allow. | +| `deniedHosts` | Optional list of hostnames or literal IP addresses to remove from user-configured allowances at either scope, including built-in policies. | +| `extends` | Optional built-in policy reference, or list of references, in the form `@`. | + +Host entries don't accept URLs, ports, CIDRs, or wildcards. Hostnames are normalized to lowercase. + +An omitted or `null` policy contributes no restrictions at that scope. A policy containing only `deniedHosts` is not an unrestricted-access denylist. + +For failed requests, see [network troubleshooting and blocked-host diagnostics](/factories/troubleshooting/#network-requests-fail-during-a-run). + +#### Factory and agent scope + +Factory and agent allowances combine; the agent policy doesn't replace the factory policy. A denial at either scope takes precedence over an allowance at either scope, including hosts supplied by `extends`. + +For example, this agent adds access to a documentation service but cannot re-allow the host denied in `factory.yaml` above: + +```markdown title="agents/reviewer/agent.md" +--- +agentType: REVIEW +networkPolicy: + allowedHosts: + - docs.example.com + - blocked.example.com +--- + +Review pull requests against the service documentation. +``` + +Policies cannot block services required for the platform to function, even through `deniedHosts`. Warp adds the required access for the run, including its repository forges, configured MCP servers, image registry, and agent data storage. + +#### Denying all outbound access + +To deny all outbound network access except required platform services, set an empty policy in `factory.yaml` and remove any `allowedHosts` or `extends` from agent policies: + +```yaml title="factory.yaml" +networkPolicy: {} +``` + +An empty policy contributes no allowed hosts. Allowances from the other scope still apply, so an empty agent policy does not cancel factory allowances. + +#### Built-in policies and versions + +Built-in policies supply reusable allowed-host lists: + +| Policy name | Purpose | +| --- | --- | +| `warp/claude-code` | Inference and authentication services for Claude Code. | +| `warp/codex` | Inference and authentication services for Codex. | +| `warp/package-registries` | Package registries and source or release downloads used by development toolchains. | + +Use an exact version such as `warp/package-registries@1.0.0` to pin the policy. A semantic-version range such as `warp/claude-code@^1` selects the highest matching version; `warp/codex@latest` selects the highest stable version. + +To combine policies, use a list: + +```yaml +networkPolicy: + extends: + - warp/package-registries@1.0.0 + - warp/claude-code@^1 +``` + +Query `GET /api/v1/networking/policies` on the {VARS.WARP_PLATFORM_API} for available policy names and versions. For authentication, see the [API reference](https://docs.warp.dev/api). + +```http +GET https://app.warp.dev/api/v1/networking/policies +``` + +The response groups policies by `name`, with `latest_version` and a `versions` list. Each version includes `version`, `is_latest`, and `allowed_hosts`. The catalog excludes the platform's required-service allowances. + +#### Kubernetes support + +Network controls for the self-hosted Kubernetes backend are pending. Don't rely on `networkPolicy` to restrict Kubernetes task pods. + ### `mcpServers` **Optional.** @@ -402,6 +500,7 @@ All frontmatter keys are optional. | [`agentType`](#agenttype) | The agent's role. | | `credentialStrategy` | Overrides the factory-level [`credentialStrategy`](#credentialstrategy). Omit it to keep the agent's current setting. | | `spawnableBy` | Agents allowed to start this agent. Omit it to allow only the foreman, use an empty list to allow none, or list exact agent names. | +| `networkPolicy` | Combines with the factory's [`networkPolicy`](#networkpolicy); denials at either scope take precedence over user-configured allowances. | | `model`, `harness` | Override the corresponding [`agentDefaults`](#agentdefaults). Set at most one. | | `runner`, `environmentId`, `secrets`, `mcpServers`, `workerHost`, `computerUseModel` | Override the corresponding [`agentDefaults`](#agentdefaults), subject to each field's inheritance rules. | | `idleTimeoutMinutes` | Keeps a completed session available for follow-up for 1 through 60 minutes. Omit it or use `null` to inherit. Without an inherited or run-level value, Warp uses 10 minutes, or 60 minutes for an orchestrated child run. | diff --git a/src/content/docs/factories/infrastructure-and-security.mdx b/src/content/docs/factories/infrastructure-and-security.mdx index 18e288d6c..7dc587094 100644 --- a/src/content/docs/factories/infrastructure-and-security.mdx +++ b/src/content/docs/factories/infrastructure-and-security.mdx @@ -31,6 +31,12 @@ With managed self-hosting, repository checkouts, commands, and sandbox files sta ![Self-hosted data security and boundaries diagram showing what stays in customer infrastructure, what Warp retains, and what transits Warp to model providers](../../../assets/agent-platform/data-security-boundaries.png) +## Network controls + +Restrict outbound access with [`networkPolicy` in the factory definition](/factories/factory-as-code/#networkpolicy). The reference covers factory and agent scope, deny precedence, built-in policies, and pending Kubernetes support. + +For failed network requests, [fetch and interpret blocked-host diagnostics](/factories/troubleshooting/#network-requests-fail-during-a-run). + ## Runners A runner selects the operating system, architecture, sandbox image, and vCPU and memory shape. The factory's [definition](/factories/factory-as-code/) supplies repositories, setup commands, and secrets. The factory definition sets the default runner with `agentDefaults.runner`. Individual agents and automations can override that default. diff --git a/src/content/docs/factories/troubleshooting.mdx b/src/content/docs/factories/troubleshooting.mdx index 592f84d4a..99af4bf7f 100644 --- a/src/content/docs/factories/troubleshooting.mdx +++ b/src/content/docs/factories/troubleshooting.mdx @@ -2,13 +2,13 @@ title: Troubleshooting Warp Factories description: >- Fix factory setup problems, events that don't start work, and runs that - stall or need stopping. + stall, need stopping, or can't reach network hosts. sidebar: label: "Troubleshooting" --- import { VARS } from '@data/vars'; -Fix the problems teams hit most often when setting up a factory and running their first work through it. Each entry below names the symptom you'd see in the {VARS.FACTORY_WEB_APP}. +Fix problems with factory setup, event routing, and runs. Use the {VARS.FACTORY_WEB_APP} to inspect work, or fetch network diagnostics through the API. ## Setting up a factory @@ -98,6 +98,50 @@ If a new matching event still doesn't reach the factory, [contact support](https **Fix:** Confirm that the **Implement** agent is enabled on the factory, that the code host connection still grants write access to the target repository, and that the work item actually reached the building stage. Branch protection rules apply to everything the factory pushes. +### Network requests fail during a run + +**Cause:** A factory or agent [network policy](/factories/factory-as-code/#networkpolicy) blocks hosts outside its allowed set. This can prevent package downloads, API calls, or inference requests. + +**Fix:** + +1. Fetch diagnostics for the affected agent run through the {VARS.WARP_PLATFORM_API}. Replace `RUN_ID` with its `run_id` from `GET /agent/runs`, not the factory or work item ID. For authentication, see the [API reference](https://docs.warp.dev/api). Your account must have access to the run. + + ```http + GET https://app.warp.dev/api/v1/agent/runs/RUN_ID/diagnostics + ``` + + To include the same `diagnostics` array alongside the full run details instead, set `include_diagnostics=true`: + + ```http + GET https://app.warp.dev/api/v1/agent/runs/RUN_ID?include_diagnostics=true + ``` + + Run details omit `diagnostics` by default. + +2. Find entries with `code` set to `network/egress_blocked`. For example, the diagnostics endpoint returns: + + ```json + { + "diagnostics": [ + { + "code": "network/egress_blocked", + "message": "Network access to packages.example.com blocked", + "data": { + "blocked_host": "packages.example.com" + }, + "timestamp": "2026-10-28T15:00:00Z", + "created_at": "2026-10-28T15:00:02Z" + } + ] + } + ``` + + `data.blocked_host` identifies the blocked hostname or IP address. The optional `timestamp` is when the blocked request occurred; the optional `created_at` is when the diagnostic was recorded. Diagnostics are warnings, not the run's outcome. The `state` field in run details reports that outcome. + +3. If the run needs that host, add it to `allowedHosts` in the factory or agent policy. Review `deniedHosts` at both scopes and remove any conflicting entry: a denial overrides an allowance, including a built-in policy. [Apply the definition change](/factories/factory-as-code/#where-the-definition-lives), start a new run, and confirm the request succeeds. + +If an opted-in run-details response omits `diagnostics`, use the dedicated diagnostics endpoint. An empty `diagnostics` array means no diagnostics were returned; it doesn't prove that every host is reachable. Check the failed command's output for other causes, and use the [API error reference](/factories/api-and-sdk/troubleshooting/errors/) for authentication or access errors. + ## Related pages * [**Warp Factories quickstart**](/factories/quickstart/) - Create a factory and submit your first work item.