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:
| Idea | One line | Read |
|---|---|---|
| Postgres decides | Status, attempts, fences, approvals and verdicts live in Postgres; Temporal payloads carry ids | Data model |
| One ledger | Every request writes exactly one usage row; a reservation is a reserved row | Agent-core decorators |
| One key holder | Only the gateway holds the provider key; api and workers refuse it at startup | Gateway |
| Job tokens | Each turn or step registers a policy-bound token with a TTL, revoked in finally | Job tokens and policies |
| Fail closed | Kill switch, config refusals, strict schemas, CHECK constraints | Configuration |
| One status vocabulary | Runtime statuses are error codes; two tables map them to HTTP | Error model |
Section map
| Section | Start here | Covers |
|---|---|---|
| Architecture | Architecture overview | System context, packages and boundaries, data model, error model, configuration |
| Runtime and API | Runtime overview | REST API, sessions and workflows, agent-core decorators, runtimes and the CLI, worker fleet |
| Security and governance | Security overview | Threat model, gateway, job tokens and policies, MCP registry, sandbox, secrets and keys |
| Software factory | Factory overview | Job lifecycle, gates and approvals, patch policy, sandbox roles |
| CodeCrucible (quality) | Quality overview | Analysis library, assessment and verify workflows, exec worker and image, anti-gaming, data model, REST and limits, status |
| Operations | Operations overview | Deployment topology, runbooks, secrets flow, persistence and backups, testing and CI, observability, releases, session dossiers |
| Reference | Glossary | Glossary, decisions, repository docs map, writing guide |
Reading order
For a first pass through the system, read in this order:
- Architecture overview and System context: what runs where.
- Packages and apps: the workspace and its enforced boundaries.
- Runtime overview and REST API: the request path.
- Agent-core decorators: kill switch, budget, limits, redaction.
- Sessions and workflows: durable turns on Temporal.
- Security overview and Gateway: the key holder and its controls.
- Data model and Error model: the tables and the codes.
- Factory overview or Quality overview, depending on the work.
- 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.mdpackages/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.tsdocs/design-worker-fleet.md,docs/deploy-quality.md,docs/deploy-sandbox.mdwebsite/docusaurus.config.js,website/sidebars.js