TrueForge: an agent harness that ships the loop, the UI and the sandbox wiring

The gap TrueForge is aimed at: everything around the model call

The README opens with a claim that is worth taking literally: building an agent is easy, running one well is not. The list that follows is the actual scope of the project. Streaming, session persistence, tool servers, sandboxing, approvals and a UI are the parts that have nothing to do with your prompt or your business logic, and they are the parts TrueForge supplies. The project calls itself a harness rather than an agent framework, and the distinction matters. It runs the execution loop. It does not decide what your agent should do.

The intended audience is a team that has already decided an LLM should sit behind a chat interface with tools, and now has to answer operational questions: where does the conversation live between requests, which process holds the API keys, how does a tool call get approved by a human, and where does generated code actually execute. TrueForge answers those with shipped components rather than with a specification you implement. It is TypeScript, MIT licensed, and requires Node.js 22.14 or newer according to the badge in the README.

One loop, three surfaces: how the pieces connect

The architecture diagram in the repository shows a single server. The chat UI and the SDKs connect to a TrueForge server that exposes an HTTP API and hosts the agent loop. That loop talks to SQLite or Postgres for state, and outward to bring-your-own models, MCP servers and a sandbox. There is no separate orchestration service to deploy and no message broker in the diagram.

Storage is the axis that separates the two documented modes. Local mode is one process with a SQLite file and no extra infrastructure, started with npx @truefoundry/trueforge. Hosted mode replaces SQLite with Postgres and adds Redis, which is what the README lists as the extra infrastructure for teams and multi-replica deployments. Docker Compose, Helm and Railway are the three named ways to run hosted mode; the release list includes a Helm chart at charts/trueforge@0.2.0-rc.0, so the chart is published from this repository rather than maintained elsewhere.

The three access surfaces are the chat UI, the HTTP API with @truefoundry/trueforge-sdk, and the embeddable @truefoundry/trueforge-ui. The npm badge list also includes @truefoundry/trueforge-core, which suggests the runtime is split across packages rather than shipped as one bundle, though the README does not document the boundary between them. If you plan to extend the server rather than consume it, that boundary is the first thing to read in the source.

Catalogs, MCP servers and skills: configuration as the unit of reuse

The setup model is catalog-first. You configure models, MCP servers, skills and a sandbox once, and agents pick from what you connected. The README states that presets come from shipped YAML catalogs you can customize, which means the initial configuration is a file you edit rather than a form you fill in per agent. That is a meaningful choice: it makes environments reproducible and reviewable in version control, and it means a new agent inherits whatever the catalog already exposes instead of starting from an empty tool list.

Models are provider-agnostic in the documented sense: OpenAI, Anthropic, Google Gemini and other catalog providers, plus any OpenAI-compatible endpoint. MCP servers are remote, with header auth or OAuth, and the README notes in-chat authorization, so the OAuth consent step happens inside the chat surface rather than in a separate admin screen. Skills are git-backed SKILL.md instruction packs loaded on demand in the sandbox. The on-demand loading is the interesting part: instructions are not injected into every request, they are pulled when the agent needs them, which keeps the context window from filling with procedures that are irrelevant to the current turn.

The sandbox is described as a tool rather than an environment. Isolated code and file execution is provisioned only when needed, and secrets stay in the harness rather than being handed to the execution environment. Daytona is the provider named today, with more planned. Treat that single-provider line as a real constraint rather than a roadmap item.

Running it: two modes and the commands that start them

The fastest path is a single command from the README: npx @truefoundry/trueforge@latest. That starts local mode, which the project describes as one process backed by SQLite with no extra infrastructure. The Quickstart page linked from the README covers local, Docker Compose, Kubernetes and Railway as alternative ways in, so the npx command is a starting point rather than the only supported install.

The README is explicit about what local mode is not. It is for your machine only, it has no login by default, data lives in a local SQLite file, and the project asks you to keep it on localhost. The warning goes further: the maintainers state they cannot take responsibility for data loss or unauthorized access if local mode is used beyond that. That is unusually direct for a README, and it should be read as a design boundary rather than boilerplate. Anyone who exposes a local instance to a network has removed the only access control the default configuration provides.

Hosted mode is the answer for anything shared. It swaps SQLite for Postgres, adds Redis, and is the mode the README associates with teams and multi-replica deployments. The repository ships a Helm chart under charts/trueforge, currently at version 0.2.0-rc.0, and Docker Compose and Railway are listed as the other routes. The README does not enumerate the Postgres or Redis configuration keys in the excerpt available here, so the specific environment variables and connection settings have to come from the Quickstart guide and the chart values rather than from this summary.

Context engineering is where the design gets opinionated

The context management feature list is the most technically specific part of the README: subagents, deferred tool loading, Code Mode, large-result offloading and compaction. Each of these is a response to the same pressure, which is that a long-running agent accumulates more material than a context window can hold.

Subagents split work across separate model contexts. Deferred tool loading keeps tool definitions out of the prompt until they are needed, which matters when you have connected many MCP servers and the tool schemas alone would consume a large share of the window. Large-result offloading moves bulky tool output somewhere other than the conversation, so a single verbose response does not crowd out the rest of the session. Compaction summarizes or trims history as it grows. Code Mode is named but not explained in the README, and it is the item I would want documentation for before relying on it, because the term implies a different interaction pattern (the model writing code that calls tools, rather than emitting tool calls directly) and the README does not confirm that reading.

The human-in-the-loop features sit alongside these: tool approval, ask-user-questions, and Generative UI in chat. Tool approval is the one that changes deployment shape, since it requires a live user to respond before execution continues. An agent that runs unattended overnight cannot use that checkpoint, and the README does not describe a policy layer for auto-approving specific tools.

Where TrueForge is the wrong choice

The clearest boundary is local mode. It has no login by default and stores data in a local SQLite file, and the maintainers describe it as a way to try TrueForge rather than a production or internet-facing setup. If your plan involves more than one user or more than one replica, hosted mode is the only documented option, and that means operating Postgres and Redis before you have run a single agent turn.

The second boundary is the sandbox. Daytona is the only provider the README names, with others described as planned. If your execution environment has to be something else, or has to run inside your own network under your own isolation rules, the current material does not show a supported path. The claim that secrets stay in the harness is a property of how the sandbox is wired, and it is worth confirming against the source before you rely on it.

The third is version maturity. The most recent releases listed are all release candidates: charts/trueforge@0.2.0-rc.0, @truefoundry/trueforge@0.2.0-rc.3 and @truefoundry/trueforge-ui@0.3.0-rc.3. The README does not state a stability policy or a compatibility guarantee between the server and the UI SDK, and the UI package is on a different minor version from the server. Teams that pin dependencies and upgrade deliberately should assume the interfaces can move.

Finally, TrueForge is not a place to put agent logic. It runs the loop, manages sessions and mediates tools. Planning strategies, domain rules and evaluation belong in your code, and nothing in the README suggests otherwise.

How it differs from wiring the loop yourself

The realistic alternative is assembling the same pieces from a lower-level toolkit: a model SDK for calls, a web framework for the API, a database for session state, a separate MCP client, and your own front end. That approach gives you full control over the request path and no opinion imposed on your data model. It also means you own streaming semantics, session resumption, approval flows and the sandbox boundary, and you own them before you have validated that the agent is useful.

The difference in approach is where the abstraction sits. A generic toolkit hands you primitives and expects you to compose the runtime. TrueForge hands you the runtime and expects you to configure it through catalogs, then consume it through a chat UI, an HTTP API or an embedded UI. The trade is configuration surface for implementation surface. You give up the ability to reshape the loop, and in exchange you do not write the parts of it that are identical across projects.

That trade is worse when your agent does not look like a chat. If the interaction is a batch job, a webhook handler or a long-running pipeline with no human in the conversation, the bundled UI and the approval checkpoints are overhead, and a lighter composition of a model SDK and your own queue is likely a better fit. The harness is shaped around a session with a user in it.

Licence, maintenance and what to check before adopting

TrueForge is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are preserved. That is a permissive starting point, and it is worth noting that the licence covers the repository code; the model providers, MCP servers and sandbox provider you connect are governed by their own terms, and the README does not address that. Nothing here is legal advice, and if you redistribute TrueForge inside a product, the licence text in the repository is what your counsel should read.

Maintenance cost is mostly operational. Local mode has none beyond the process itself. Hosted mode adds Postgres and Redis, which means backups, connection limits and the usual upgrade work for both. The Helm chart under charts/trueforge is versioned separately from the npm packages, so a chart upgrade and a server upgrade are two decisions rather than one. Because the current releases are release candidates, expect to read release notes between upgrades rather than assuming compatibility.

The upgrade surface is the catalog YAML. Since presets ship as YAML files you are expected to customize, your edits live alongside upstream defaults, and a change to the shipped catalogs can collide with your local modifications. Keeping your catalog changes in a separate layer, or tracking exactly which files you edited, is the practical defence. The README does not describe a merge or override mechanism for catalogs, so verify how your customizations survive an upgrade before you build a fleet of agents on top of them.

Editorial conclusion

Adopt TrueForge if you want an agent runtime you can start with npx @truefoundry/trueforge@latest and later move to Postgres and Redis without rewriting the surrounding plumbing, and if your agents fit a chat-shaped interface. Do not adopt it for an internet-facing deployment on local mode, and do not expect it to supply planning or domain logic. Before committing, verify the sandbox provider path (Daytona is the only one named today), confirm that the model and MCP catalogs cover your providers, and check whether the pre-1.0 release cadence in the charts and npm packages matches how you ship.

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. truefoundry/trueforge on GitHub