> ## 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.

# System architecture

> How Forge is built: one durable store behind every interface, where code runs, durable runs and agent dispatch, scheduled jobs, sandboxes, providers, files and model tiers.

This page explains how Forge is built and what that means for the work you run on it. For what
Forge is and how its parts fit together, start with the [overview](https://docs.gloo.com/forge.md).

## One source of truth

Forge keeps its state, its run orchestration, its governance decisions and its evidence in one
durable backend, built on Convex. Forge Console, the HTTP API and the Forge MCP server are
interfaces to that state, not separate copies of it. A change made through one is visible through
the others.

| Layer | What it does |
| - | - |
| Interfaces | Forge Console, the HTTP API and MCP. Each keeps its own credentials and transport. |
| Control | Resolves who is calling, their roles and grants, token scopes, emergency stops, policy and budgets. |
| Orchestration | Starts runs on a pinned version, finds the steps that are ready, and advances the graph from recorded results. |
| Execution | Runs agent turns, procedures and sandbox commands, and calls external services through capability providers. |
| Evidence | Stores results, decisions, usage and audit events before anything downstream relies on them. |

Authority is always decided on the server. What a screen shows, what a token's scope names, or
what a provider returns is not by itself permission to change anything.

### Why a transactional, reactive backend

Three properties of the backend shape how Forge behaves:

| Property | What it means for you |
| - | - |
| **Transactional writes** | A governance check and the state change it guards happen atomically. A step cannot be marked running unless its concurrency limit passes in the same transaction, and an audit entry is written with the decision it records. |
| **Live subscriptions** | Forge Console subscribes to the records it shows. When a step completes or an approval resolves, every open Console sees it without refreshing. |
| **Durable workflows** | The orchestrator runs as a durable workflow. If the backend process restarts, a run resumes from its last committed step. |

### What runs where

| Part | Runs in | Owns |
| - | - | - |
| Control plane | Forge's backend | Workflow graphs and versions, orchestration, agent composition, Trust Fabric, budgets, run history and audit, agent and skill definitions, chat and memory, factories |
| Inline agent turn | Forge's backend | The model call and allowed tool calls, using the shared agent-turn core |
| Detached agent turn | A sandbox VM | The same turn core, reporting back through authenticated platform callbacks |
| Sandbox commands and procedures | A sandbox VM | Governed isolated code execution within declared file and network boundaries; results return to Forge |

Durable ownership always stays with the control plane: a detached turn or a sandbox command does
its work in a VM, but its outcome counts only once Forge has recorded it.

## The control path

Every request is authenticated, then checked against the caller's roles and grants, narrowed by
the credential's scopes, and evaluated against emergency stops and policy. The result is a
refusal, a hold that waits for a person, or a recorded operation. The HTTP API and MCP use the
same server-side checks as Forge Console; neither trusts what the client claims about itself. Read
[Credentials and access](https://docs.gloo.com/forge/get-started/credentials-and-access.md) and
[Trust Fabric](https://docs.gloo.com/forge/concepts/trust-fabric.md).

## Durable execution

A run's state lives in the backend, not in a running process. When a run starts, Forge records the
published version it uses. It then finds the steps whose inputs are ready, checks each one with
Trust Fabric, runs it, validates the output and records the result before moving on. Because every
step is recorded, a deploy or a crashed process does not lose a run: it continues from the last
recorded step.

Waiting is part of the model. When a step needs a person, Forge creates a human task and the run
waits, using no model tokens, until an authorized answer arrives. Read
[Workflows and runs](https://docs.gloo.com/forge/concepts/workflows-and-runs.md) and the
[workflow execution flow](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md).

The orchestrator itself uses no model tokens; it is deterministic state management. It loads the
pinned graph, dispatches the steps that are ready, evaluates routers, joins parallel branches, hands
person-assigned steps to people, records outputs, applies each step's retry rules, and checkpoints
as it goes.

### Agent dispatch

Every place that runs an agent — a chat turn, a factory operation, a copilot analysis, a workflow
node — prepares it the same way:

1. Resolve who launched the work, its inputs, and the caller's current authority.
2. Apply that surface's governance checks. Preparing an agent's configuration does not by itself
   authorize it to run.
3. Compose the agent's configuration from its definition: prompt, permitted skills and tools,
   and model.
4. Run the turn inline or detached.
5. Record messages, outputs, usage and completion evidence under the run.

An agent turn runs either inline in the backend or in a detached VM, chosen from the node's
declared timeout: above the 8-minute inline budget the whole turn runs detached. The run detail
shows where each agent step ran; see
[Detached agent turns](https://docs.gloo.com/forge/build/configure-sandbox.md#detached-agent-turns).

A structured turn streams its answer against the declared output contract and then validates the
final text. A separate schema-constrained call runs only to repair a reply that does not parse.
Repair is not a step retry and is not permission to repeat a tool's effect.

An agent definition's `executionModel` is `"native"`, which is also the default when you omit it.
Older records with no value still compose. The retired values `"managed"` and `"cloud"` are
refused when the agent is composed; that refusal does not mean detached turns are unavailable.

### Scheduled platform jobs

Forge runs scheduled jobs to keep runs moving and data tidy:

| Area | Jobs | Frequency |
| - | - | - |
| Execution hardening | Workflow watchdog, step timeout enforcement | Every 2 minutes / every 60 seconds |
| Workflow schedules | Start scheduled workflows that are due | Every 60 seconds |
| Human tasks | Follow-ups, escalation, cancellation at the final due date | Every 5 minutes |
| Cost analytics | Hourly and daily rollups, weekly compaction | Hourly / daily / weekly |
| Budgets | Daily, weekly and monthly envelope resets | On each envelope's schedule |
| Retention | Token events (90 days), audit events (365 days), callback deduplication (24 hours) | Daily / hourly |
| Registries | Built-in skill, tool and platform agent sync | Daily |
| Memory | Session memory compaction, promotion to long-term memory | Every 6 hours / weekly |

Workflow schedules are evaluated by polling every minute rather than by each run scheduling the
next one. A failed tick is retried on the next one, so a schedule cannot silently break after a
single error. Watch every job's last run under **Platform → Schedules**.

## Sandboxes

A **sandbox** is an isolated, short-lived VM for running code: building a repository, running
tests or executing a script. Code that should not run inside Forge's backend, such as
agent-generated or untrusted code, runs there.

An agent reaches a sandbox only through the `sandbox_action` tool, and only when the step it is
running has sandbox access. The VM is created when the agent first needs it. The step's binding
fixes what it may do there: the permitted commands, files, network access and lifetime. The
sandbox capability decides which provider supplies the VM; the foundation provider is Vercel
Sandbox. See sandbox sessions and snapshots under **Production → Sandboxes**, and read
[Configure a sandbox](https://docs.gloo.com/forge/build/configure-sandbox.md).

## Capability providers

Forge reaches external services through **capabilities**. A capability domain is a typed contract,
such as inference, embeddings, secrets or file hosting. A **provider record** connects a domain to
one provider and its credential. Forge code calls the contract, never a vendor SDK directly, so you
can change a provider without changing workflows or agents.

In a single-dispatch domain, provider order follows one rule: **an enabled provider becomes active;
the foundation provider serves only when no other provider is enabled.** A fanout domain
(`notifications`, `human_interaction`) delivers to every enabled provider, its foundation included,
so enabling Slack adds a delivery channel rather than replacing Forge's own. The foundation is the provider Forge pins for a
domain. It always stays in the domain's provider records, ordered after every provider you enable.
Forge never silently switches from one provider to another.

Forge has 20 capability domains. Ten have a foundation provider; ten have none. Four of those ten
ship with providers already enabled, though none is pinned: `inference` (Anthropic, OpenAI, Google
and Gloo), `embeddings` (OpenAI), `synchronized_knowledge` (Freshservice) and `secrets_store`
(Forge's own store). An enabled provider can still need a credential before its calls succeed.

> [tab] With a foundation
>
> | Domain | Foundation |
> | - | - |
> | `blackboard` | `forge` |
> | `file_hosting` | `forge` |
> | `human_interaction` | `forge` |
> | `knowledge` | `forge` |
> | `llm_fallback_chains` | `forge` |
> | `network` | `forge` |
> | `notifications` | `forge` |
> | `project_management` | `forge` |
> | `publish` | `forge` |
> | `sandbox` | `vercel` |

> [tab] Without a foundation
>
> `inference`, `embeddings`, `synchronized_knowledge` and `secrets_store` ship with providers
> enabled. The other six stay **listed, unconfigured** until you enable a provider. Until then, a
> call to one fails with an error that names the domain; it does not fall back to a stand-in.
>
> * `inference`
> * `embeddings`
> * `source_control`
> * `org_structure`
> * `secrets_store`
> * `chat_syndication`
> * `coding_agent`
> * `telemetry_export`
> * `synchronized_knowledge`
> * `typed_judgments`

Removing a provider never deletes your Forge data. Manage providers under
**Platform → Capabilities**, and read [Capabilities](https://docs.gloo.com/forge/concepts/capabilities.md).

## Files

Agents store and read files through two tools. `file_put` stores a file and returns its file ID;
`file_get` reads only the files the current step is authorized to read. A step that declares file
outputs can write workflow outputs only under the output keys it declared. Steps pass file IDs to
each other, not file contents, so access to a file is checked every time it is read. A declared file
output is satisfied only by a file ID that `file_put` recorded for this run; raw content or an
invented ID is refused. Read
[Files and bindings](https://docs.gloo.com/forge/architecture/files-and-bindings.md).

## Model routing tier

An agent usually names a **model routing tier** rather than a model. Its `tier` field names the tier, from cheapest to
most capable: `nano`, `low`, `mid`, `high` or `frontier`. At dispatch, Forge resolves the tier to
a concrete model, and a fallback chain names the models to try next if that model is unavailable.
An agent with no tier uses the model it names in `model.default`. Skill minimums
and tenant caps still apply. See models under **Platform → Models** and fallback chains under
**Platform → Fallback Chains**, and read [LLM routing](https://docs.gloo.com/forge/architecture/llm-routing.md).

The routing tier is not the agent's kind (system, worker or personal); see
[Workforce](https://docs.gloo.com/forge/concepts/workforce.md#agents).

## Failure and recovery

* A refusal ends that attempt. Fix the authority or the input before you try again.
* A hold is durable waiting, not a failure.
* Forge retries transient execution only where a step's retry rules allow it. A write whose result
  is unknown is reconciled before another attempt.
* Steps with external effects record the effect, or reserve it, first, so recovery does not repeat
  a business action.
* Forge Console shows recorded state. It does not prove that a provider did something Forge has
  no record of.

## Related

> [card] [Workflow execution](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md)
>
> How a run moves from step to step.

> [card] [Governance pipeline](https://docs.gloo.com/forge/architecture/flows/governance-pipeline.md)
>
> The checks every dispatch passes.

> [card] [Approval lifecycle](https://docs.gloo.com/forge/run/approvals-and-hitl.md#approval-lifecycle)
>
> How a held action waits for and resumes after a decision.

> [card] [Choose an interface](https://docs.gloo.com/forge/get-started/choose-an-interface.md)
>
> Forge Console, the HTTP API or MCP.


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