# TrueForge

> An agent harness that runs the execution loop, tools, sandbox and UI for you

- Category: Agents & Automation / Agent Frameworks & Builders
- Language: TypeScript
- Licence: MIT
- Repository: https://github.com/truefoundry/trueforge
- Website: https://trueforge.dev
- Canonical page: https://ai-tldr.dev/tools/trueforge/

## In short

TrueForge is an open-source agent harness — the runtime layer between a model and a working agent. It sits in the Agent Frameworks & Builders category of the Agents & Automation tools and is open-source, written in TypeScript and licensed MIT. To get started: run TrueForge locally.

## Overview

TrueForge is an open-source agent harness — the runtime layer between a model and a working agent. It runs the execution loop for you: model calls, MCP tools, skills, sandboxing, approvals, context management and session state, none of which is interesting to rebuild but all of which is required before an agent is usable.

It exposes that loop three ways: a bundled chat UI, an HTTP API with a TypeScript SDK (`@truefoundry/trueforge-sdk`), and an embeddable UI SDK (`@truefoundry/trueforge-ui`) for putting agent chat inside your own product. Configuration is catalogue-driven — you connect models, MCP servers, skills and a sandbox once from shipped YAML catalogues you can customise, and individual agents pick from what is connected.

The runtime scales in both directions. Local mode is a single process backed by SQLite, started with one npx command, and is explicitly meant for trying things out on your own machine rather than exposing to a network. Hosted mode adds Postgres and Redis and deploys via Docker Compose, Helm or Railway for teams and multi-replica setups. Context engineering features — subagents, deferred tool loading, Code Mode, large-result offloading and compaction — are built in, as are human checkpoints such as tool approval, ask-user questions and generative UI in chat.

## What it does

- Runs the full agent loop: model calls, MCP tools, skills, sandboxing, approvals, context management and session state
- Three interfaces over one runtime — a chat UI, an HTTP API with a TypeScript SDK, and an embeddable UI SDK
- Any model provider: OpenAI, Anthropic, Google Gemini and other catalogue providers, or any OpenAI-compatible endpoint
- Remote MCP servers with header auth or OAuth, including in-chat authorization, plus git-backed SKILL.md instruction packs loaded on demand
- Sandbox as a tool — isolated code and file execution provisioned only when needed, with secrets kept in the harness
- Context engineering built in: subagents, deferred tool loading, Code Mode, large-result offloading and compaction
- Local mode (one process, SQLite) or hosted mode (Postgres + Redis) via Docker Compose, Helm or Railway

## Getting started

TrueForge needs Node.js 22.14 or newer. A single npx command starts local mode with SQLite storage — no database or extra services to stand up first.

1. Run TrueForge locally

   Local mode runs one process backed by a local SQLite file. It has no login by default, so keep it on localhost — use hosted mode for anything shared.

```bash
npx @truefoundry/trueforge@latest
```

2. Connect models, tools and a sandbox

   Configure model providers, MCP servers, skills and a sandbox once from the shipped YAML catalogues. Agents you create then pick from whatever you connected.

3. Automate with the SDK

   The HTTP API is wrapped by a TypeScript SDK, so agents can be driven from your own code rather than the bundled chat UI.

```bash
npm install @truefoundry/trueforge-sdk
```

4. Embed the chat UI in your product

   The UI SDK packages the chat surface for embedding. For a team deployment, switch to hosted mode (Postgres + Redis) via Docker Compose, Helm or Railway — see the quickstart at trueforge.dev.

```bash
npm install @truefoundry/trueforge-ui
```

## When to use it

- Ship an agent product without building streaming, session persistence, tool approval and a chat UI from scratch
- Give an internal team a shared agent with MCP tools and a sandbox, deployed on Kubernetes via the Helm chart
- Embed agent chat directly in your own application using the UI SDK instead of linking out to a separate tool
- Run skills and sandboxed code execution against your own model provider while keeping provider secrets inside the harness