Skip to main content

AgentForge technical reference

AgentForge is a provider-agnostic, security-governed agent platform. It exposes a REST API for synchronous agent runs, durable multi-turn sessions on Temporal, a sandboxed software factory that turns a task into a reviewed pull request, and CodeCrucible, a mutation-testing quality gate. A governance gateway is the only process that holds the model provider key; everything else reaches the model through it with short-lived per-job tokens, and every call is metered against one Postgres ledger.

This site is the verbose technical reference for an engineer new to the repository. It is written from the code and the repository's own docs, and every page ends with a Sources section naming the files it was written from, so any claim can be checked. Where the code or docs say something is not built or not verified, the page says so too.

System at a glance​

Key ideas, each with its own page:

IdeaOne lineRead
Postgres decidesStatus, attempts, fences, approvals and verdicts live in Postgres; Temporal payloads carry idsData model
One ledgerEvery request writes exactly one usage row; a reservation is a reserved rowAgent-core decorators
One key holderOnly the gateway holds the provider key; api and workers refuse it at startupGateway
Job tokensEach turn or step registers a policy-bound token with a TTL, revoked in finallyJob tokens and policies
Fail closedKill switch, config refusals, strict schemas, CHECK constraintsConfiguration
One status vocabularyRuntime statuses are error codes; two tables map them to HTTPError model

Section map​

SectionStart hereCovers
ArchitectureArchitecture overviewSystem context, packages and boundaries, data model, error model, configuration
Runtime and APIRuntime overviewREST API, sessions and workflows, agent-core decorators, runtimes and the CLI, worker fleet
Security and governanceSecurity overviewThreat model, gateway, job tokens and policies, MCP registry, sandbox, secrets and keys
Software factoryFactory overviewJob lifecycle, gates and approvals, patch policy, sandbox roles
CodeCrucible (quality)Quality overviewAnalysis library, assessment and verify workflows, exec worker and image, anti-gaming, data model, REST and limits, status
OperationsOperations overviewDeployment topology, runbooks, secrets flow, persistence and backups, testing and CI, observability, releases, session dossiers
ReferenceGlossaryGlossary, decisions, repository docs map, writing guide

Reading order​

For a first pass through the system, read in this order:

  1. Architecture overview and System context: what runs where.
  2. Packages and apps: the workspace and its enforced boundaries.
  3. Runtime overview and REST API: the request path.
  4. Agent-core decorators: kill switch, budget, limits, redaction.
  5. Sessions and workflows: durable turns on Temporal.
  6. Security overview and Gateway: the key holder and its controls.
  7. Data model and Error model: the tables and the codes.
  8. Factory overview or Quality overview, depending on the work.
  9. Operations overview before touching a deployment.

New terms are defined in the Glossary; the reasons behind major choices are in Decisions.

Conventions on this site​

  • Hosts are named by role ("the core host", "the sandbox host"), never by name or address.
  • Repository files appear as code spans such as packages/db/src/schema.ts, not links.
  • "Not built" and "Unverified" are used exactly as the source documents use them.
  • How to add or change a page: Writing guide.

Sources​

  • README.md, GLOSSARY.md, CODING_STANDARDS.md
  • packages/db/src/schema.ts (table comments on Postgres as system of record)
  • apps/api/src/config.ts, apps/worker/src/config.ts, apps/worker/src/factory/config.ts, apps/gateway/src/config.ts
  • docs/design-worker-fleet.md, docs/deploy-quality.md, docs/deploy-sandbox.md
  • website/docusaurus.config.js, website/sidebars.js