Skip to main content
This page is for operators standing up and operating factories — autonomous production units where humans and AI agents collaborate on projects through governed workflows, real-time chat, and shared dev environments. A factory is the operating context where work happens. For the dispatch path used by Factory Manager and Factory Worker, see Trust Fabric in production.

What a factory is — six components

Factories are provisioned from blueprints — higher-level templates that capture team composition, channel structure, environment specs, and budget limits into repeatable packages. Blueprints build on factory types, adding concrete staffing and configuration defaults.

The Overseer model — three worker types

The Factory Manager does not write code. It orchestrates only. Three worker types do the actual work: The Factory Manager receives work requests, decomposes them into tasks, assigns to workers, monitors progress, and manages PRs. Coordination flows through the factory’s chat channels — the chat thread is the coordination history, the audit trail is the formal record. Output of a typical factory cycle:
  • Pull Request — branch → changes → tests → PR
  • Chat Thread — full coordination history
  • Cost Attribution — token spend per worker per task

Factory lifecycle — four phases

Pausing a factory is the right move when you need to halt work without destroying state. Existing in-flight work drains; new dispatches block. Resuming returns the factory to ACTIVE with no provisioning step. Archiving is permanent. The factory’s channels, manager thread, and budget records are preserved for audit, but no new work can be assigned. This is the operating equivalent of agent.archived for the factory shell.

Development tasks — the work the factory tracks

Factories track work through a task board: backlog → assigned → in-progress → in-review → complete. Tasks can be assigned to humans or agents. Each task links to workflow runs for traceability — when an agent executes a task, the resulting run is associated with the task record. This linkage is the operating bridge. The task board shows “what is being worked on.” The workflow runs show “how it is being executed.” The cost attribution shows “what it is costing.” All three views are joinable on runId and taskId.

Token attribution — every spend rolls up

Every token event generated within a factory — by any agent, for any workflow step — is attributed to that factory through a fan-out pipeline. When a tokenEvents row is written, the pipeline fans it out to factoryTokenEvents, creating a factory-scoped copy of the event with the factoryId attached. This attribution chain is what powers Analytics → Cost → Factories in Forge Console. The tab shows cost-per-factory over time, sorted by spend, so operators can see which factories consume the most resources without manual aggregation. The attribution chain end-to-end: LLM call → tokenEvents (raw) → fan-out → factoryTokenEvents (factory-scoped) → costAggregates rollup → Analytics → Cost → Factories The factoryTokenEvents table uses a by_factory index for efficient per-factory queries. Cost aggregates with scope="factory" are produced during the hourly rollup cron, so the Factories tab reflects spend with at most a 1-hour lag.

Operator runbook

When you stand up and operate a factory:
  1. Pick a blueprint, not a from-scratch config. Factory blueprints encode “how we run this kind of factory” — staffing levels, default channels, budget defaults. From-scratch configuration is how you accumulate inconsistencies across factories.
  2. Set the budget tight, not loose. Factory budgets are the cleanest enforcement point for “how much will this team cost.” Over-budget factories block dispatch via the budget gates — you find out about over-spend the moment it would happen, not at the end of the month.
  3. Watch the Manager’s thread. The Factory Manager’s persistent thread is where the Manager records its decisions, decompositions, and escalations. If the thread is silent for hours when work is in flight, something is wrong — probably a worker hung or a tool call that did not return.
  4. Use chat channels as the coordination record. All worker-to-worker communication runs through the factory’s chat channels. The chat thread is the coordination history; the audit trail is the formal record. Do not let coordination drift into out-of-band channels (DMs, Slack, email) that are not captured.
  5. Archive, do not delete. When a factory’s work is done, archive — do not destroy. The audit history, cost attribution, and chat threads are how you answer “what did this factory cost and produce” months later.

Do it over the API

These calls use the FORGE_BASE set up in the Raw HTTP tab of the quickstart. The quickstart’s ACCESS_TOKEN does not carry every scope they need, so mint it again with scope=switches:use factories:read cost:read from an app whose roles hold them (see Requesting scopes at token mint), or send a Personal key whose scopes include them; switches:use is elevated, so tick Include elevated permissions when you choose the key’s scopes (see Approve and administer scopes). Pause a factory, with a reason for the audit trail:
This needs switches:use at the factory’s home; a Forge agent is always refused. Steps already running finish, and pausing a paused factory answers changed: false. POST /api/v3/factories/{factoryId}/resume takes a reason the same way. Read the factory’s token spend for the last seven days. The window is at most 30 days, and the read needs both factories:read and cost:read at the factory’s home. meta.partial is true when more than 10,000 events fell in the window; data.coveredFrom then says where the sum starts:
Over MCP, pause it with forge_call_operation:
and read its spend with forge_call_read_operation (times in epoch milliseconds):