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 onrunId 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 atokenEvents 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:- 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.
- 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.
- 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.
- 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.
- 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 theFORGE_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:
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:
forge_call_operation:
forge_call_read_operation (times in epoch milliseconds):

