TrueForge Agent Harness and UHP

Separate the chat application, runtime API and caller identity

The current TrueForge README requires Node.js 22.14+ and offers a bundled application launched with npx @truefoundry/trueforge@latest. For repeatable evaluation, choose the application release explicitly; @truefoundry/trueforge@0.3.1 is the latest observed application tag, not the SDK/core/Helm version.

npx @truefoundry/trueforge@0.3.1

This source-derived pinned launch is unexecuted here. It downloads/runs the application; follow TrueForge’s quickstart for the selected provider and host mode.

Boundary	Acceptance question
Bundled chat UI	Does a resumed session show the intended immutable history?
Runtime HTTP API	Can the caller distinguish task state, approvals and tool failure?
MCP OAuth connection	Which user/application granted access to which tool server?
Hosted gateway mode	Is destination-specific identity/metadata preserved?

Start with one runtime and one MCP server. Capture authorization-required, authorization-success and tool-result evidence separately; a repeated authentication message is not proof of a second grant. The current patch specifically fixes duplicate mcp.auth_required UI messages, while older RC notes below explain gateway identity provenance. Test the actual resource access your application needs rather than treating a successful UI login as proof of tool permission.

For an embedded product, retain server-owned session/approval semantics instead of interpreting the UI transcript as the whole API. Use routing identity to track caller/destination ownership and UHP vs MCP to distinguish tool OAuth from a complete-harness execution protocol. Reviewed current TrueForge sources still do not establish a native UHP endpoint or CE backend.

Release check — 4 October 2026

The latest stable release observed in the upstream GitHub release API is @truefoundry/trueforge@0.3.1, published 2026-09-30. The release ships immutable chat-history session handling and duplicate mcp.auth_required message fixes in its bundled frontend. The RC6 sections below remain historical evidence for the earlier identity and MCP boundaries.

Evidence scope: the integration details, commands, measurements and development-head references below preserve the 11 Sep 2026 source snapshot. They are not presented as a fresh test of this newer release. For the current UHP protocol, HarnessRouter release and suite coordinates, use the release tracker and conformance guide. Adapter support does not establish upstream-native UHP adoption.

Source snapshot — 11 Sep 2026

TrueForge is a distinct application-side agent harness, not a UHP implementation. TrueFoundry describes it as the runtime layer that turns an LLM into a working agent. Its server owns model calls, MCP tools, skills, sandboxing, approvals, context management and session state, then exposes that runtime through a bundled chat UI, an HTTP API with a TypeScript SDK and an embeddable UI SDK.

The repository was created in July 2026 and is under active development. The latest observed application-package prerelease is @truefoundry/trueforge@0.2.0-rc.6, published 11 September 2026 at 16:35:16 UTC. RC6 is material because it promotes the previously post-RC5 TrueFoundry-mode gateway identity and MCP-manifest provenance work into a released application prerelease: destination-specific vended credentials, x-tfy-metadata request context and the type-discriminated MCP-server manifest are now release behavior rather than current-main-only behavior. Version-packaging commit 480e485d985976bab952dfaac244226c7a49a8cc is the RC6 application tag target and also bumps the independently versioned SDK/core dependencies carried by that package. Checked upstream main is later e097f21dbf7dd71f39c0938a1440efdd46da92fb; after RC6, PR #720 only advances Helm packaging to the RC6 image and PR #676 changes Introduction imagery, so no later runtime/protocol behavior is promoted here. Because the monorepo publishes several independently versioned packages and Helm-chart releases, this page names the application package explicitly instead of treating GitHub’s generic “latest release” label as the TrueForge application version.

Caution

No native UHP, ACP or A2A adoption is established. Reviewed TrueForge primary sources do not name UHP or ACP. The only reviewed A2A repository hit is example/research text rather than an advertised protocol surface. HarnessRouter v0.16.1 also does not list TrueForge among its ten released backends. MCP support is a separate tool-integration boundary and must not be reclassified as UHP support.

What TrueForge owns

TrueForge is a complete harness runtime rather than a thin model wrapper. Its current documentation describes these first-party responsibilities:

• model-provider selection for OpenAI, Anthropic, Gemini and OpenAI-compatible endpoints;
• remote MCP-server tools with header authentication or OAuth, including in-chat authorization;
• git-backed and TrueFoundry-registry SKILL.md instruction/capability packs loaded on demand;
• isolated code/file execution through a sandbox provider, with Daytona documented today and TrueFoundry-mode sandbox plumbing present in the RC line;
• human checkpoints such as tool approval and user questions;
• subagents, deferred tool loading, Code Mode, large-result offloading and context compaction;
• session, turn and scheduled-run persistence surfaced through the HTTP API / TypeScript SDK;
• a bundled chat interface and embeddable UI SDK.

That bundle is relevant to UHP research because it is almost exactly the kind of complete harness execution surface that a client-to-harness interoperability protocol could sit in front of. The existence of an HTTP API, however, does not make that API UHP-compatible.

HTTP API versus UHP

TrueForge’s native network boundary is its own server HTTP API. The SDK exposes TrueForge concepts such as agents, sessions, turns, schedules and events against that API. UHP separately defines a versioned client → UHP server → harness contract with its own task/session/response semantics and conformance suite.

No reviewed TrueForge source provides a UHP adapter, UHP endpoint map, UHP version declaration or UHP conformance result. Therefore:

• TrueForge’s HTTP API is not treated as a UHP implementation;
• similar words such as “session” or “turn” are not assumed to have UHP semantics;
• running TrueForge behind a future adapter would be an integration fact, not native TrueForge adoption unless TrueFoundry itself publishes that support.

MCP is a native tool boundary

TrueForge does document first-party MCP integration. Administrators can configure remote MCP servers from catalog entries or custom URLs, and the current documentation supports header authentication and OAuth. The harness resolves those tool sources for agent execution and can complete authorization from the chat flow.

The 0.2.0-rc.3 application package added live per-user MCP authentication checks before tools are loaded into the agent builder and TrueFoundry-mode mid-turn authorization gating across supported authentication modes. It also removed MCP-server list pagination across the API/SDK/UI so the configured catalog is returned as a complete list and searched client-side. Those capabilities remain in the RC6 line. They are TrueForge harness/control-plane semantics around MCP; they do not change MCP’s wire protocol.

Released RC6 includes PR #714, which makes MCP-server provenance explicit in TrueForge’s own OpenAPI/SDK surface. MCPServerManifest is a type-discriminated OpenAPI oneOf between RemoteMCPServerManifest (type: "remote", an ordinary MCP endpoint URL) and TrueFoundryMCPServerManifest (type: "truefoundry", a resolved AI Gateway proxy URL for a TrueFoundry-managed server). The generated TypeScript SDK mirrors that union and removes the former shared McpServerType enum. This is an application/API typing boundary around how TrueForge represents MCP server origin and routing; it is not an MCP wire-protocol revision.

This is an agent/harness → MCP tools boundary. It does not replace TrueForge’s surrounding agent loop, session store, approvals, sandbox or HTTP API, and it does not imply that MCP is part of UHP conformance.

Skills, sandboxing and subagents

TrueForge treats skills and execution infrastructure as harness capabilities:

• Skills: git-backed SKILL.md packs and TrueFoundry-registry skill references are resolved into the runtime; the RC3 line added a type-discriminated registry skill source and saved-agent/turn resolution through ServiceFoundry.
• Sandbox: isolated file/code execution is provisioned as a tool; the documented implementation uses Daytona today, while the RC line also carries a TrueFoundry-mode sandbox provider path.
• Subagents: the harness can fan work out to parallel subagents and merge results while keeping their intermediate context out of the main agent’s context.
• Context controls: deferred tool loading, compaction and large-result offloading are runtime mechanisms rather than network protocol primitives.

These are useful examples of the implementation topology UHP should remain agnostic about. A UHP client can care about portable task/session behavior without dictating whether a server’s backing harness uses one agent, subagents, a sandbox, Code Mode or a particular skill-loader architecture.

Local and hosted security boundary

TrueForge explicitly separates a convenience local topology from shared deployment:

Mode	Storage / infrastructure	Authentication boundary
Local / standalone	Single process with SQLite	No login by default. Upstream warns to keep it on localhost and not expose it as a production or internet-facing service.
Hosted / distributed	Postgres + Redis; documented through Docker Compose, Helm or Railway	Optional OIDC login for shared/team deployments, plus internal service credentials for server-to-server control paths.

The distinction matters operationally. A local harness endpoint with no login should not be mistaken for a safe remotely addressable agent service merely because it exposes HTTP. RC4’s internal schedule-execution key protects a specific controller → server path; it does not convert the general standalone HTTP surface into an authenticated remote-service posture.

0.2.0-rc.4 schedule-auth boundary retained by RC6

Application prerelease 0.2.0-rc.4, published 11 September 2026 at 04:45:16 UTC, promoted PR #627’s scheduled-execution authorization work from unreleased current-main behavior into the application package. RC5 and RC6 inherit that behavior:

• the controller dispatches a persisted schedule run through one POST /api/internal/schedules/runs/execute call authenticated with TRUEFORGE_API_KEY, passing only schedule_run_id;
• the server loads the run, schedule and saved agent, then reconstructs request context from the schedule creator before starting the turn in-process;
• in TrueFoundry mode, saved-agent scheduled turns resolve model/MCP resources with agent-scoped vended credentials, while skill resolution uses a dedicated admin/service-key store; interactive inline turns retain their caller-token boundary where applicable;
• OpenAPI and the TypeScript SDK expose the internal execution operation, with explicit 401, 404 and 422 failure classes in addition to successful/no-op 204;
• the application changeset describes the service-key path as a replacement for the controller’s previous multi-step public-SDK dispatch flow.

RC4 also inherited the material RC3 harness/control-plane baseline: live per-user MCP authentication before tool loading, TrueFoundry-registry skills, service-key-protected migration/permission surfaces, scheduled-run state refinements, current-user chat-history filtering and Redis tfg: namespace isolation. The repository marks the scheduled-execution work Authz 6/6, but that label describes TrueForge’s own authorization workstream; it is not an external certification or a UHP conformance claim.

0.2.0-rc.5 release boundary

Application prerelease 0.2.0-rc.5 was published 11 September 2026 at 06:41:59 UTC. Version-packaging commit 380bdde0379164b5e88c02f16c8aa0caef981a33 bumps the application package from RC4 to RC5 and records three patch changes: generated TypeScript agent snippets include token: "USER_API_KEY" when OIDC or TrueFoundry auth is enabled, and the application boot path receives two loading/orb presentation refinements.

The separately versioned Helm chart charts/trueforge@0.2.0-rc.2, published 11 September 2026 at 06:54:05 UTC, sets appVersion to 0.2.0-rc.5 and the default image tag to 0.2.0-rc.5-380bdde. These package/chart coordinates establish the preceding RC5 release maturity; they do not create a new interoperability protocol or alter UHP, ACP, A2A or MCP wire semantics.

0.2.0-rc.6 release boundary: gateway identity and MCP provenance

Application prerelease @truefoundry/trueforge@0.2.0-rc.6 was published 11 September 2026 at 16:35:16 UTC from version-packaging commit 480e485d985976bab952dfaac244226c7a49a8cc. It turns three previously tracked post-RC5 changes into released application behavior:

• PR #706 / 04531576: destination-specific vended credentials. ServiceFoundry’s vend-token response is consumed as actorToken plus subjectToken instead of one undifferentiated token. TrueForge uses the actor credential for agent-authenticated registry lookups and the subject credential for user-authorized MCP authorize/auth-status, model-gateway api_key and MCP invocation, with the agent represented in the delegated act context. This is a material identity-scoping correction, not an MCP protocol change.
• PR #685 / 4e3b5be8: TrueFoundry gateway metadata. In TrueFoundry mode, outbound model and MCP gateway requests carry an x-tfy-metadata JSON header with tfg.session_id, tfg.turn_id and, for reference agents, optional tfg.agent_id / tfg.agent_name. The turn id is minted before resource resolution so model/MCP calls and the persisted turn use the same identifier. Session user metadata is deliberately omitted for now because of Unicode-in-header concerns. MCP header merging preserves authRequired results rather than overwriting the authorization flow. Upstream describes this as observability context, not an authentication or execution-policy change.
• PR #714 / 9501536b: MCP manifest provenance. The application/OpenAPI contract replaces one flat MCPServerManifest plus shared MCPServerType enum with an explicit discriminator and two variants: remote endpoint versus TrueFoundry-managed endpoint resolved through the AI Gateway. The generated SDK exposes the same union. The change makes the application contract’s routing provenance type-safe without changing MCP transport or message semantics.

RC6 also persists top-level agent descriptions and syncs them to ServiceFoundry on create/update (8c31eae) and paginates/searches GET /api/v1/agents with limit, page_token, a pagination envelope and optional case-insensitive agent_name filtering (dc2151f). Those are application/control-plane refinements, not interoperability-protocol changes. The package pulls @truefoundry/trueforge-sdk@0.2.0-rc.5 and @truefoundry/trueforge-core@0.2.0-rc.4 as independently versioned dependencies.

The separately versioned Helm release charts/trueforge@0.2.0-rc.4, published 11 September 2026 at 17:06:17 UTC through PR #720, sets appVersion to 0.2.0-rc.6 and the default image tag to 0.2.0-rc.6-480e485. Checked main then advances to e097f21dbf7dd71f39c0938a1440efdd46da92fb through documentation-only PR #676. The checked post-RC6 commits do not add another TrueForge runtime release.

None of these RC6 changes establishes native UHP/ACP/A2A support, changes MCP wire semantics, or makes TrueForge a HarnessRouter backend.

How the boundaries compare

Layer	Primary job	Verified TrueForge relationship
TrueForge	Complete agent execution runtime, session/turn/schedule API and UI	Native project surface.
MCP	Harness/agent → tools and external systems	Native documented integration with header auth/OAuth and live auth gating.
Agent Skills / SKILL.md	Reusable instruction/capability packs	Native documented harness capability, including git and registry-backed sources.
ACP	Editor/client → agent protocol	Not established in reviewed TrueForge sources.
A2A	Agent → agent interoperability	Not established as a TrueForge protocol surface in reviewed sources.
UHP	Client → UHP server → complete harness	No native adoption established.
HarnessRouter	UHP reference implementation → released backend adapters	TrueForge is not in the released ten-backend set at this cutoff.

Evidence boundaries

• Observed application prerelease: @truefoundry/trueforge@0.2.0-rc.6, published 11 Sep 2026 at 16:35:16 UTC; tag/package commit 480e485d985976bab952dfaac244226c7a49a8cc.
• RC6 released gateway context: PR #685 adds x-tfy-metadata session/turn/reference-agent context to TrueFoundry-mode model/MCP gateway calls.
• RC6 released credential split: PR #706 routes actor identity to ServiceFoundry registry lookups and subject/user-authorized identity to MCP authorization/status and model/MCP gateway invocation.
• RC6 released MCP manifest provenance: PR #714 makes MCPServerManifest a type-discriminated remote-versus-TrueFoundry union in TrueForge’s OpenAPI/SDK contract.
• RC4 schedule boundary retained: PR #627’s service-key scheduled execution remains released behavior inherited by RC5 and RC6.
• Checked upstream main: e097f21dbf7dd71f39c0938a1440efdd46da92fb; post-RC6 PR #720 is chart packaging and PR #676 is documentation imagery.
• RC6 chart coordinate: charts/trueforge@0.2.0-rc.4, appVersion 0.2.0-rc.6, image 0.2.0-rc.6-480e485.
• Native MCP: established by TrueForge README/documentation and source; RC3 introduced the live auth gating retained by RC6.
• Native skills/sandbox/subagents/session API: established by TrueForge primary documentation/source.
• Native UHP: not established.
• Native ACP: not established.
• Native A2A: not established by the reviewed evidence.
• HarnessRouter backend support: not present in v0.16.1’s ten released backends.
• UHP conformance evidence: none attributed to TrueForge.

Related pages

Read Pydantic AI Harness for another application-side harness architecture, AI SDK Harnesses for a framework-level harness abstraction, harness composition for runtime topology, UHP vs MCP for the tool boundary, and ecosystem for adoption classifications.

Primary sources

• TrueForge repository
• TrueForge README
• TrueForge application package 0.2.0-rc.6
• TrueForge RC6 version-packaging commit 480e485
• TrueForge RC6 Helm chart release
• TrueForge application package 0.2.0-rc.5
• TrueForge RC5 version-packaging commit 380bdde
• TrueForge MCP server documentation
• TrueForge authentication documentation
• PR #627 — service-key scheduled execution / Authz 6/6
• PR #685 — gateway session/turn/agent metadata
• PR #706 — ServiceFoundry dual vend-token routing
• PR #714 — type-discriminated MCP server manifests
• PR #720 — RC6 Helm packaging
• TrueForge checked main e097f21
• HarnessRouter v0.16.1