> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Factories in production

> Operating autonomous production units — the Factory Manager, worker types, lifecycle, budget, and how token attribution flows.

Last updated 2026-11-11

·
applies to 2026-05-02

·
main

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](https://docs.gloo.com/forge/run/trust-fabric.md).

When to reach for something else

If you need a one-off agent dispatch (no team, no budget, no channel), use a workflow directly — factories carry overhead that is justified by recurring work. If you need a long-lived chat thread without coordinated production output, use a hybrid workforce channel without a factory shell — the channel can host agents and humans without the Manager pattern. Factories are for **recurring production** with team coordination, isolated dev environments, and per-factory cost attribution.

***

## What a factory is — six components

| Component | What it provides |
| - | - |
| **Factory Type** | Template defining the factory's purpose and default configuration |
| **Factory Manager** | A Convex-native Overseer agent that coordinates operations |
| **Team** | Workers (human and agent) assigned with defined positions |
| **Channels** | Chat channels scoped to the factory for real-time collaboration |
| **Dev Environments** | Isolated code execution via Vercel Sandbox for software factories |
| **Budget** | Allocated spend limits for the factory's operations |

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:

| Worker | What it does | Surface |
| - | - | - |
| Factory Worker | Implements coding tasks in an isolated sandbox and reports the resulting branch or pull request. | Dispatch-bound `sandbox_action`, isolated VM |
| Human Worker | Reviews PRs, approves decisions, provides domain input via chat channels. | Forge Console + Slack |
| Specialist Agent | Analysis, review, evaluation. Read-only agents that advise the Manager. | Copilot, analyst patterns |

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

| Status | What it means |
| - | - |
| `PROVISIONING` | Channels, manager agent, and dev environment being set up |
| `ACTIVE` | Fully operational — manager agent has a thread, channels are live |
| `PAUSED` | Temporarily suspended — no new work dispatched, existing work can complete |
| `ARCHIVED` | Permanently deactivated — historical data preserved for audit |

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](https://docs.gloo.com/forge/quickstart.md). 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](https://docs.gloo.com/forge/reference/conventions.md#requesting-scopes-at-token-mint)), or send a [Personal key](https://docs.gloo.com/forge/console/settings/personal-keys.md#choose-scopes) 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](https://docs.gloo.com/forge/console/settings/personal-keys.md#approve-and-administer-scopes)).

Pause a factory, with a reason for the audit trail:

```bash theme={null}
curl -sS -X POST "$FORGE_BASE/api/v3/factories/$FACTORY_ID/pause" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pause-factory-$FACTORY_ID-v1" \
  -d '{"reason": "Manager thread silent for three hours with work in flight"}' \
  | jq '.data | {status, previousStatus, changed}'
```

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:

```bash theme={null}
END=$(( $(date +%s) * 1000 ))
START=$(( END - 7 * 24 * 60 * 60 * 1000 ))
curl -sS "$FORGE_BASE/api/v3/factories/$FACTORY_ID/spend?startTime=$START&endTime=$END" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq '{totals: .data.totals, partial: .meta.partial}'
```

Over MCP, pause it with `forge_call_operation`:

```json theme={null}
{
  "operationId": "pauseFactory",
  "input": { "id": "<factory id>", "reason": "Manager thread silent for three hours with work in flight" },
  "idempotencyKey": "pause-factory-<factory id>-v1"
}
```

and read its spend with `forge_call_read_operation` (times in epoch milliseconds):

```json theme={null}
{ "operationId": "getFactorySpend", "input": { "factoryId": "<factory id>", "startTime": 1793491200000, "endTime": 1794096000000 } }
```

***

## Related

* [Trust Fabric in production](https://docs.gloo.com/forge/run/trust-fabric.md)
* [Budgets and cost](https://docs.gloo.com/forge/run/budgets-and-cost.md)
* [Observability](https://docs.gloo.com/forge/run/observability.md)
* [How the sandbox works](https://docs.gloo.com/forge/build/configure-sandbox.md#how-the-sandbox-works)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.