Skip to main content
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.

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

What runs where

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 and Trust Fabric.

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 and the workflow execution flow. 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. 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: 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.

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.
Removing a provider never deletes your Forge data. Manage providers under Platform → Capabilities, and read Capabilities.

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.

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. The routing tier is not the agent’s kind (system, worker or personal); see Workforce.

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.

Workflow execution

How a run moves from step to step.

Governance pipeline

The checks every dispatch passes.

Approval lifecycle

How a held action waits for and resumes after a decision.

Choose an interface

Forge Console, the HTTP API or MCP.