Factory definitions as code

Factory definitions as code let you manage a factory’s entire configuration as files in a Git repository. The files describe the factory’s repositories, agents, automations, runners, skills, and execution defaults, and they are the source of truth: when the files change, Warp updates the factory to match. Because the definition is version-controlled, every change to the factory gets the same treatment as a code change, with review, history, and rollback.

Live-managed and file-managed factories

Every factory manages its configuration in one of two ways:

• Live-managed - The configuration lives in the control room, and you edit it there directly. There are no definition files.
• File-managed - The configuration lives in definition files in a Git repository, and the files are the source of truth. The control room reflects what the files say.

A file-managed factory keeps its definition in one of two places:

• GitHub-backed - The definition lives in a directory you register in a GitHub repository you own. You change the factory the way you change code: open a pull request, let Warp’s check validate it, and merge.
• Warp-managed - The definition lives in a repository that Warp hosts for you. You edit it in the control room, and each save commits directly.

A factory can be created in either mode, and a live-managed factory becomes file-managed when you link a definition source. In every mode, the definition files own configuration only; the factory’s operational state stays in the control room.

Mode	Source of truth	Where you edit	How changes are reviewed and applied
Live-managed	Control-room state	Control room	Edits take effect directly in the control room. There are no files to sync until you link a definition source.
GitHub-backed	The registered directory on the production branch of your repository	Your GitHub repository; control-room settings are read-only and link to the files	Pull requests receive a validation check, and pushes to the production branch sync the factory. An admin can unlink the source to return the factory to live-managed.
Warp-managed	The Warp-hosted factory repository	The control room’s Code tab and supported control-room editors	Each edit validates, commits, and syncs in one step. The source cannot be unlinked or switched. A failed sync keeps the last successful definition active.

Editing a Warp-managed definition

For a Warp-managed source, the Code tab in the control room edits the definition files directly. Saves are safe against concurrent edits: if someone else committed a change after you loaded the files, Warp reports a conflict instead of overwriting the newer commit. Every save validates the whole definition and reports problems with the file and line where they occur.

For a GitHub-backed source, the control room does not provide an editor. It links to the registered directory in your repository instead.

Directory structure

A definition is a small tree of YAML and Markdown files. Each resource takes its name from its path: agents/reviewer/agent.md defines an agent named reviewer, and runners/linux-build.yaml defines a runner named linux-build. Files never declare kind or apiVersion fields.

factory.yaml
agents/
  foreman/
    agent.md
    skills/
      incident-triage/
        SKILL.md
  reviewer/
    agent.md
automations/
  labeled-issue/
    automation.md
runners/
  linux-build.yaml
skills/
  repository-conventions/
    SKILL.md

Skills live in two places: skills/ applies to the whole factory, while agents/<name>/skills/ applies only to that agent. A skill is a directory containing a SKILL.md, not a YAML field; see Skills for agents.

Resource reference

YAML keys are case-sensitive.

factory.yaml

factory.yaml names the factory and sets everything shared across it: the repositories it works in, factory-wide access, and the execution defaults agents inherit.

Field	Purpose	Rules
schemaVersion	Declares the definition schema.	Required. Must be v1alpha1.
name	Names the factory.	Required.
description	Describes the factory’s purpose.	Optional.
alias	Sets a display alias.	Optional. Must be unique in the workspace (case-insensitive).
credentialStrategy	Chooses whose credentials runs receive.	EXECUTOR uses the principal executing the run; CREATOR uses the user who created the run. Defaults to EXECUTOR.
repositories	Lists the GitHub repositories the factory works in, as owner and name pairs.	Required and non-empty.
secrets	Lists Warp-managed secret names granted to every agent.	Optional.
mcpServers	Maps server names to Warp MCP server warpId values, granted to every agent.	Optional.
cloudProviders	Configures GCP or AWS access.	GCP accepts projectNumber, workloadIdentityFederationPoolId, workloadIdentityFederationProviderId, and serviceAccountEmail; AWS accepts roleArn.
integrations	Declares connected factory integrations.	Optional. type accepts slack, linear, or jira. Declare at most one issue tracker: linear and jira are mutually exclusive, and omitting a tracker is valid. GitHub is not declared here; repository access comes from repositories and the connected GitHub App.
agentDefaults	Sets the execution defaults agents inherit: shared model or harness, runner, environmentId, secrets, mcpServers, and workerHost.	Required. Agents inherit any execution field they omit.
agentDefaults.workerHost	Sets the factory’s default execution host.	Optional. A non-empty value becomes the factory default; omitting or clearing it defers to the workspace default.

Warp still parses the legacy providers key. The next time a Warp-managed edit rewrites the configuration, Warp saves it as cloudProviders.

In the control room, Settings lets you edit cloud providers for Warp-managed sources. For GitHub-backed sources, cloud provider settings are read-only and link to factory.yaml in the registered repository directory.

How access and defaults combine

Two different rules decide what an agent ends up with:

• Factory-wide access is additive. Top-level secrets and mcpServers in factory.yaml are granted to every agent. An agent cannot opt out of them.
• Defaults are replaceable. Values in agentDefaults apply only when an agent omits the field. An agent that sets its own secrets or mcpServers replaces the agentDefaults value, but the factory-wide entries still apply. Every other omitted execution field inherits from agentDefaults.

How workerHost resolves

workerHost follows the same three-way rule wherever it appears:

• Set a value to choose a host: warp for Warp-hosted execution, or the ID of a connected self-hosted worker.
• Omit the field to inherit from the level above.
• Set an empty or null value to skip inheritance and use the workspace default.

Choosing a model or harness

Fields that accept a model or harness take one of two mutually exclusive forms. model on its own is shorthand for the Warp Agent harness, serialized as type oz:

model: auto

The shorthand is equivalent to:

harness:
  type: oz
  model: auto

Use the harness form for a third-party harness or advanced settings:

harness:
  type: codex
  model: gpt-5.3-codex
  reasoningLevel: high
  auth:
    source: managedSecret
    secretName: CODEX_API_KEY

A harness mapping accepts type, model, reasoningLevel, and auth. For auth, set source: managedSecret with a secretName, or source: workerEnvironment with no secretName; workerEnvironment requires that the effective workerHost is a self-hosted worker. Type oz does not accept explicit auth or reasoningLevel. See supported harnesses and cloud agent secrets.

agents/<name>/agent.md

An agent file combines YAML frontmatter with a Markdown body. The frontmatter configures how the agent runs; the body is the prompt that carries the role’s durable instructions.

Field	Purpose	Rules
description	Describes the role.	Optional.
agentType	Classifies the role.	CUSTOM, FOREMAN, TRIAGE, SPEC, IMPLEMENT, REVIEW, or VERIFY. MAIN is an alias for FOREMAN.
credentialStrategy	Chooses whose credentials this agent’s runs receive.	Overrides the factory-level strategy.
model or harness	Selects the runtime and model.	Mutually exclusive. Overrides agentDefaults.
runner	Names a runner defined under runners/ or an existing runner.	Overrides agentDefaults.runner.
environmentId	References an existing environment.	Overrides agentDefaults.environmentId.
secrets	Grants role-specific secrets.	Replaces agentDefaults.secrets. Factory-wide secrets from factory.yaml still apply.
mcpServers	Grants role-specific MCP servers.	Replaces agentDefaults.mcpServers. Factory-wide servers from factory.yaml still apply.
workerHost	Selects this agent’s execution host.	Set a value to override, omit to inherit agentDefaults.workerHost, or clear to use the workspace default.

A valid definition contains exactly one foreman: an agent with agentType: FOREMAN or its alias MAIN. The foreman is the factory’s entry point and the default target for automations that omit agent. Validation fails if a definition declares no foreman or more than one.

automations/<name>/automation.md

An automation file also combines YAML frontmatter with a Markdown body. The frontmatter declares when runs start and how they execute; the body is the run prompt.

Field	Purpose	Rules
enabled	Turns the automation on or off.	Optional.
agent	Names the agent that handles runs.	Optional. Must name a declared agent. Defaults to the foreman.
model or harness	Selects execution for automation runs.	Mutually exclusive. Overrides the target agent.
runner	Selects compute for automation runs.	Overrides the target agent’s runner.
environmentId	Selects the environment for automation runs.	Overrides the target agent’s environment.
secrets	Selects secrets for automation runs.	Overrides the target agent’s secret list.
mcpServers	Selects MCP servers for automation runs.	Overrides the target agent’s MCP map.
workerHost	Selects the execution host for automation runs.	Set a value to override, omit to inherit from the target agent, or clear to use the workspace default.
triggers	Declares the events or schedules that start runs.	Required and non-empty. Each entry uses provider, event, an optional filter, and an optional schedule with name and cron.

See triggers and integrations for event sources.

runners/<name>.yaml

A runner file defines compute, not agent behavior.

Field	Purpose	Rules
description	Describes the workload the runner supports.	Optional.
setupCommands	Commands that initialize the sandbox.	Ordered list.
instanceShape	Sets compute capacity.	Uses vcpus and memoryGb.
platform	Sets the operating system and architecture.	Uses os and arch. Linux adds linux.dockerImage; macOS adds mac.version.

The control room’s Runners page lists the effective runners in every mode. For a Warp-managed source, creating or editing a runner there writes runners/*.yaml for you. For a GitHub-backed source, runner controls are read-only and link to the runner directory in your repository. See cloud agent runners and cloud agent environments for execution behavior.

Example factory definition

This example defines a small factory: one repository, a foreman, an automation triggered by a GitHub label, and a Linux runner.

factory.yaml

schemaVersion: v1alpha1
name: payments-factory
description: Processes approved work for the payments service
alias: payments
credentialStrategy: EXECUTOR
repositories:
  - owner: ACME
    name: PAYMENTS_SERVICE
agentDefaults:
  model: auto
  runner: linux-build
  environmentId: PAYMENTS_ENVIRONMENT_ID

ACME is the GitHub organization, PAYMENTS_SERVICE is the repository name, and PAYMENTS_ENVIRONMENT_ID is the ID of an existing environment.

agents/foreman/agent.md

---
description: Routes approved payments work through the factory
agentType: FOREMAN
secrets:
  - SENTRY_AUTH_TOKEN
mcpServers:
  sentry:
    warpId: SENTRY_MCP_SERVER_ID
---

Own each work item from intake through human handoff.

Confirm the request is ready before dispatching implementation. Require
repository validation and independent review before marking work complete.

The foreman inherits model, runner, and environmentId from agentDefaults. Its Sentry secret and MCP server are role-specific; moving them to factory.yaml would grant them to every agent in the factory.

automations/labeled-issue/automation.md

---
enabled: true
agent: foreman
triggers:
  - provider: github
    event: issue_labeled
    filter:
      repos: [ACME/PAYMENTS_SERVICE]
      labels: [factory-ready]
---

Review the labeled issue and decide the next required stage. Preserve the
issue's acceptance criteria and return unresolved product questions to a human.

runners/linux-build.yaml

description: Linux runner for payments builds and tests
setupCommands:
  - corepack enable
instanceShape:
  vcpus: 4
  memoryGb: 8
platform:
  os: linux
  arch: x86_64
  linux:
    dockerImage: ubuntu:22.04

Validation and synchronization

Warp treats the definition as a single unit: it parses, validates, and resolves a change as a whole, and only a fully valid tree becomes the active definition. If any step fails, the factory keeps running on the last successful definition. An invalid change never partially applies.

flowchart LR
  Change["Definition change"] --> Parse["Parse and validate"]
  Parse -->|Valid| Resolve["Resolve dependencies"]
  Resolve -->|Valid| Apply["Apply desired state"]
  Apply -->|Success| Active["Active definition"]
  Parse -->|Failure| Last["Keep last successful definition"]
  Resolve -->|Failure| Last
  Apply -->|Failure| Last

Validation rejects:

• Unknown fields, duplicate YAML keys, unsupported file paths, and malformed frontmatter.
• YAML anchors, aliases, and explicit tags.
• A schemaVersion other than v1alpha1.
• A missing repositories list or agentDefaults block, an automation without triggers, or a definition without exactly one foreman.
• References that do not resolve, including agents, runners, environments, secrets, MCP servers, models, and harness settings.

Every diagnostic identifies the source file and line that caused it.

GitHub pull request checks

For GitHub-backed sources, every pull request that targets the production branch receives a warp/factory-config (<directory>) check for each registered path. The check annotates invalid fields or references and summarizes the changes it would apply. A push to the production branch starts synchronization.

Warp-managed direct synchronization

For Warp-managed sources, supported control-room edits commit directly to the Warp-hosted repository, then validate and sync; there is no separate pull request step. Branch-based review gating is limited and is not a general workflow for these edits. If synchronization fails, the commit remains in the repository, and the factory keeps running on the last successful definition while you repair it.