trueforge
The open-source agent harness - the runtime layer that turns an LLM into a working agent.
What is it?
What it is
TrueForge is an open-source agent harness that runs the agent execution loop, providing model calls, MCP tools, skills, sandboxing, approvals, context management, and session state. It exposes functionality through a chat UI, an HTTP API with a TypeScript SDK, and an embeddable UI SDK.
Why it exists
Building an agent is easy, but running one well requires streaming, session persistence, tool servers, sandboxing, approvals, and a UI. TrueForge provides these capabilities out of the box, allowing developers to focus on building agents rather than infrastructure. It supports initial setup from catalogs, any model provider, MCP tools, skills, sandbox-as-a-tool, human checkpoints, and context engineering features.
Who should use it
Developers and teams building AI agents who need a production-ready runtime for model calls, MCP tools, sandboxing, approvals, and session state. Ideal for those wanting to go from prototype to scalable agent deployment with optional UI, SDK, or API access.
Who should avoid it
Users looking for a simple library or framework without infrastructure dependencies. Not suitable for those who only need basic LLM integration without agent orchestration, or for production deployments using local mode (SQLite only).
How it works
A quick walkthrough in plain English
How trueforge works in 4 steps
Step 1 of 4
Something triggers the flow
A schedule, webhook, or manual click tells trueforge to start.
Features
Advantages
- Rapid setup from catalogs (models, MCP, skills, sandbox) with presets
- Works in local mode (SQLite) for quick prototyping or hosted mode (Postgres+Redis) for production
- Scales from single‑process local to multi‑replica Docker/Helm deployments
- Reduces development effort by providing built‑in streaming, approvals, and UI
- Low‑cost benchmarking shows better cost efficiency vs managed agents
Disadvantages
- Local mode is not production‑ready; data stored in a local SQLite file with no authentication
- Requires Node.js ≥22.13 and a running server for hosted mode, adding infrastructure overhead
- Dependence on external sandbox providers (currently Daytona) may limit execution environments
- Community and ecosystem smaller than some competing agent frameworks
Installation
cloud
Deploy TrueForge on Kubernetes using Helm charts for hosted mode with Postgres and Redis.
docker
Run TrueForge in hosted mode with Postgres and Redis using Docker Compose or Helm charts for multi-replica deployments.
native
Run local mode with `npx @truefoundry/trueforge` for personal use with SQLite and no extra infrastructure.
compose
Use Docker Compose for hosted mode with Postgres and Redis for teams and multi-replica setups.
FAQ
How do I run TrueForge locally to try it out?
Run `npx @truefoundry/trueforge` to start TrueForge in local mode. This uses a single process with SQLite storage and requires no extra infrastructure. Note that local mode is intended for personal use on localhost only — it has no login by default and is not suitable for production or internet-facing deployments.
What is the difference between local mode and hosted mode?
Local mode runs in a single process using SQLite with no extra infrastructure, ideal for personal use or trying out TrueForge. Hosted mode uses Postgres and Redis, supports multi-replica scaling, and is intended for teams or production deployments. Hosted mode can be run via Docker Compose or Helm.
How do I connect a model provider to TrueForge?
TrueForge supports OpenAI, Anthropic, Google Gemini, and other catalog providers, as well as any OpenAI-compatible endpoint. You configure models once through the Initial Setup documentation, and agents can then select from the connected models.
What are skills in TrueForge?
Skills are git-backed `SKILL.md` instruction packs that are loaded on demand in the sandbox. They allow you to define reusable agent behaviors and instructions that can be picked up by agents during execution.
How does the sandbox work in TrueForge?
TrueForge provides sandbox-as-a-tool for isolated code and file execution. It is currently supported via Daytona, with more providers planned. Sandboxes are provisioned only when needed, and secrets remain in the harness rather than the sandbox.
What SDKs and UI options are available?
TrueForge exposes three ways to interact with the agent loop: a bundled Chat UI, an HTTP API with a TypeScript SDK (`@truefoundry/trueforge-sdk`), and an embeddable UI SDK (`@truefoundry/trueforge-ui`). You can use the UI directly, automate via the SDK, or embed the UI components into your own application.
Featured in Videos
YouTube tutorials and walkthroughs for trueforge
Alternatives
Similar projects ranked by category, topics, and text overlap.
