The open-source agent harness - the runtime layer that turns an LLM into a working agent.
Trueforge harness docs update (#131)
Abhishek Choudharyd0ed943956f2
diff --git a/docs/docs.json b/docs/docs.jsonindex a6eb335ed..1e1acef02 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -60,6 +60,10 @@{"group": "API","pages": ["api/overview", "api/agent-spec", "api/turn-events"]+ },+ {+ "group": "Project",+ "pages": ["roadmap"]}]},diff --git a/docs/introduction.mdx b/docs/introduction.mdxindex 71514ce66..699a2647f 100644--- a/docs/introduction.mdx+++ b/docs/introduction.mdx@@ -6,18 +6,7 @@ description: 'TrueForge is an open-source agent harness — the runtime layer th## What is an agent harness?-An agent harness is the runtime layer around an LLM that turns it into a reliable, long-running agent.--Instead of only generating text, the harness manages the full execution loop: planning, tool calling, context management, approvals, state, and streaming.--Most production harnesses include:--- An orchestration loop (`plan -> act -> observe -> continue/stop`)-- Tool routing and execution (for APIs, MCP tools, and code)-- Memory and context controls for long-running tasks-- Security boundaries (sandboxing, credentials, permissions)-- Human-in-the-loop gates for sensitive actions-- Session state that survives reconnects and restarts+An agent harness is the runtime layer around an LLM that turns it into a reliable, long-running agent. Instead of only generating text, the harness runs the full execution loop — planning, tool routing and execution, context management for long tasks, security boundaries like sandboxing and human-in-the-loop approvals, and session state that survives reconnects and restarts.<Frame caption="The harness orchestrates the agent run, connecting the model, tools, sandbox, and approvals to deliver a safe, reliable result"><img@@ -28,23 +17,96 @@ Most production harnesses include:## What is TrueForge?-TrueForge is an **open-source agent harness**. It runs the agent execution loop — model calls, tool use, context, and session state — and exposes the result three ways:--- A **chat UI**, bundled into the server and served on the same port-- An **HTTP API** (REST + Server-Sent Events) with an OpenAPI spec-- A **TypeScript library** (`@truefoundry/trueforge-core`) for embedding the agent core in your own application--You choose a model, connect MCP servers, add skills, and write instructions. TrueForge handles orchestration, tool execution, sandbox lifecycle, approvals, and streaming.--It scales down and up: run a single process backed by SQLite with `npx @truefoundry/trueforge`, or run multiple replicas backed by Postgres and Redis behind a load balancer.+TrueForge is an **open-source agent harness** with three parts: a **core server** that runs the agent loop, an **HTTP API** (with a TypeScript SDK) to drive it from code, and a **chat UI** (with a React UI SDK) to drive it from the browser.<Frame caption="The bundled chat UI — streaming responses, an expandable agent-steps panel, and tool calls."><img src="/images/getting-started-chat.png" alt="The TrueForge chat UI showing an agent response with an agent-steps panel and tool calls" /></Frame>+### Key Components++```mermaid+flowchart LR+ ui[Chat UI<br/><small>@truefoundry/trueforge-ui</small>]+ code[Your code<br/><small>@truefoundry/trueforge-core</small>]+ subgraph server [TrueForge server]+ api[HTTP API]+ loop[Agent loop]+ api --> loop+ end+ db[(SQLite / Postgres)]+ subgraph byo [Bring your own]+ llm[Model providers]+ mcp[MCP servers]+ sandbox[Sandbox provider]+ end++ ui --> api+ code --> api+ loop --> db+ loop --> llm+ loop --> mcp+ loop --> sandbox++ style byo stroke-dasharray: 6 4+```++### Core server++Runs the agent loop. When a user sends a message, the server:++- Plans the turn, calls the model, and executes tools — streaming every step back+- Pauses for [human approval](/human-in-the-loop) on sensitive actions+- Keeps context lean on long tasks with [context engineering](/context-engineering/overview)+- Persists sessions, so conversations survive reconnects and restarts++The services the loop talks to — [model providers](/models), [MCP servers](/mcp-servers), the [sandbox provider](/sandbox) — are **bring your own**: you configure them, TrueForge orchestrates them.++<Note>+ Many harnesses run the agent *inside* a sandbox. TrueForge treats the **sandbox as a tool**: one is provisioned only+ when the agent actually needs to execute code. That's why one server can run many agents concurrently, and why turns+ that don't need code execution are cheaper and faster.+</Note>++### HTTP API + TypeScript SDK++Everything the server does is exposed as an API, so anything you see in the UI you can automate:++- REST + Server-Sent Events, with an OpenAPI spec and interactive docs at `/api/v1/docs`+- A TypeScript SDK (`@truefoundry/trueforge-core`) to create and call agents from your own code++See the [API overview](/api/overview).++### Chat UI + UI SDK++A ready-made interface for the agents you create:++- Browse your agents, chat with them, and manage models, MCP servers, skills, and sandbox settings+- Bundled with the server and served on the same port — nothing extra to deploy+- Also published as a customizable [UI SDK](/ui-sdk/index) (`@truefoundry/trueforge-ui`): theme it to your organization and launch your own Claude Desktop-like interface, backed by your TrueForge server++## Two ways to run it++The agent features are identical in both modes — only the backend around the server changes. The [Quickstart](/quickstart) has run instructions for each.++### Local mode — a personal productivity tool++Like Claude Desktop, but on your terms: one process on your machine, started with `npx @truefoundry/trueforge`.++- UI and backend run locally; sessions are stored in a local SQLite file+- No database server, Redis, or other infrastructure to set up++### Hosted mode — a shared deployment for your team++Like Claude's managed agents: one deployment the whole company uses, via Docker Compose or the Helm chart.++- Multiple server replicas run behind a load balancer+- **Postgres** replaces SQLite as durable storage shared by all replicas+- **Redis** peers the replicas — it hands off turn event streams and cancellation signals, so a client can reconnect to any replica and still resume a turn running on another one+## Capabilities-<CardGroup cols={2}>+<CardGroup cols={3}><Card title="Models" icon="brain" href="/models">OpenAI, Anthropic, Google Gemini, and any OpenAI-compatible provider. Configure once, switch per agent.</Card>@@ -72,64 +134,16 @@ It scales down and up: run a single process backed by SQLite with `npx @truefoun</Card></CardGroup>-## Architecture--TrueForge is a single server process (or several peered replicas) plus a database — and Redis when you run more than one replica.--```mermaid-flowchart LR- browser([Browser / your app])- subgraph server [TrueForge server]- ui[Chat UI]- api[HTTP API + agent loop]- end- db[(Postgres or SQLite)]- redis[(Redis)]- llm[Model providers]- mcp[MCP servers]- sandbox[Sandbox provider]-- browser --> ui- browser --> api- api --> db- api <--> redis- api --> llm- api --> mcp- api --> sandbox-```--| Component | Role |-| --------------------- | --------------------------------------------------------------------------------------------------- |-| **Chat UI** | React chat interface, bundled into the server image and served on the same port as the API. |-| **Server** | Node.js server: the agent execution loop, sessions, turns, streaming, settings, and OpenAPI docs. |-| **Postgres / SQLite** | Session, turn, and settings storage. SQLite in standalone mode; Postgres for multi-replica. |-| **Redis** | Cross-replica peering (turn cancellation and stream handoff). Only needed when running > 1 replica. |-| **Sandbox provider** | Remote isolated compute for code execution and skills. Optional — enable it per agent. |--## Core concepts--Interaction with an agent follows a strict hierarchy: **one Agent → many Sessions → many Turns → many Events**.--<Frame caption="One agent serves many sessions; each session has many turns; each turn emits many events.">- <img src="/images/agent-session-hierarchy.png" alt="Hierarchy diagram: one Agent contains many Sessions, each Session many Turns, each Turn many Events" />-</Frame>--| Concept | What it is |-| ----------- | --------------------------------------------------------------------------------------------------------------------- |-| **Agent** | A saved definition — model, instructions, MCP servers, skills, and runtime config. See [Agent spec](/api/agent-spec). |-| **Session** | One conversation with an agent. Turns in a session chain together, so the agent remembers earlier context. |-| **Turn** | One request/response boundary — a user message, an approval decision, or an answer to an agent question. |-| **Event** | A JSON object streamed while a turn runs: model output, tool responses, approval requests, subagent lifecycle. |--See the [API overview](/api/overview) for the full lifecycle with examples.-## Start building-<CardGroup cols={2}>+<CardGroup cols={3}><Card title="Quickstart" icon="rocket" href="/quickstart">Run TrueForge with one command, configure a model provider, and start chatting.</Card><Card title="Use the API" icon="code" href="/api/overview">Create sessions, stream turn events, and integrate TrueForge into your application.</Card>+ <Card title="Build with the UI SDK" icon="palette" href="/ui-sdk/index">+ Embed and customize the chat experience in your own React application.+ </Card></CardGroup>diff --git a/docs/quickstart.mdx b/docs/quickstart.mdxindex 4e7df0dd6..f89016d4e 100644--- a/docs/quickstart.mdx+++ b/docs/quickstart.mdx@@ -6,28 +6,24 @@ description: 'Run TrueForge with one command, configure a model provider, and ha## Run TrueForge+TrueForge runs in [two modes](/introduction#two-ways-to-run-it): **local mode** — a single process on your machine, like a personal productivity tool — and **hosted mode** — a shared deployment for your team, with Postgres for storage and Redis for cross-replica peering. The agent features are identical in both.+<Tabs>- <Tab title="npx">- Requires [Node.js](https://nodejs.org) 22.13 or newer. One command, no other infrastructure — data is stored in a local SQLite file:+ <Tab title="Local mode (npx)">+ Requires [Node.js](https://nodejs.org) 22.13 or newer. One command, no other infrastructure — the UI and backend run locally, and data is stored in a local SQLite file:```bashnpx @truefoundry/trueforge```- Then open [http://localhost:8790](http://localhost:8790).-- | Configuration | Default | Description |- | ----------------- | -------------------------- | ----------------------------------------------- |- | `--port` / `PORT` | `8790` | HTTP port the server (UI + API) listens on. |- | `SQLITE_PATH` | OS data dir | Location of the SQLite database file. |- | `PUBLIC_BASE_URL` | `http://localhost:${PORT}` | Public origin, used for MCP OAuth callbacks. |+ Then open [http://localhost:8790](http://localhost:8790). The defaults work out of the box — see the [FAQ](#faq) to change the port or data location.</Tab>- <Tab title="Docker Compose">- Runs the full production topology on your machine: the server (UI + API), Postgres, and Redis.+ <Tab title="Hosted mode (Docker Compose)">+ Runs the full hosted topology on your machine: the server (UI + API), Postgres, and Redis.```bash- git clone <REPO_URL> trueforge && cd trueforge # TODO: repo URL+ git clone https://github.com/truefoundry/trueforge && cd trueforgecp packages/server/.env.example packages/server/.envdocker compose up --build```@@ -41,8 +37,8 @@ description: 'Run TrueForge with one command, configure a model provider, and ha| Host ports | `8791`, `5433`, `6380` | App, Postgres, and Redis. |</Tab>- <Tab title="Kubernetes (Helm)">- The Helm chart deploys the server in distributed mode with bundled Postgres and Redis (or point it at your own). No values are required for a basic install:+ <Tab title="Hosted mode (Kubernetes)">+ The Helm chart deploys the server in hosted mode with bundled Postgres and Redis (or point it at your own). No values are required for a basic install:```bash# TODO: replace <HELM_REPO> with the published Helm repo URL@@ -61,8 +57,9 @@ description: 'Run TrueForge with one command, configure a model provider, and ha</Tabs><Note>- Standalone (`npx`) uses SQLite and needs no other services. Docker Compose and Kubernetes run the multi-replica- topology: Postgres for storage and Redis for cross-replica peering. The agent features are identical in both.+ Local mode (`npx`) uses SQLite and needs no other services. Docker Compose and Kubernetes run hosted mode: Postgres+ replaces SQLite as durable storage, and Redis peers the replicas so streams and cancellations follow the client+ across them.</Note>## Configure a model provider@@ -167,6 +164,43 @@ curl -N -X POST http://localhost:8790/api/v1/sessions/{session_id}/turns \See the [API overview](/api/overview) for the full lifecycle — turn chaining, approvals, and event handling.+## FAQ++<AccordionGroup>+ <Accordion title="How do I run the server on a different port?">+ Pass `--port`, or set the `PORT` environment variable:++ ```bash+ npx @truefoundry/trueforge --port 3000+ # or+ PORT=3000 npx @truefoundry/trueforge+ ```++ In hosted mode, change the host port mappings in `docker-compose.yml` instead.++ </Accordion>+ <Accordion title="Where does local mode store its data?">+ In a SQLite file in your OS's application data directory. To put it somewhere else, set the `SQLITE_PATH` environment variable:++ ```bash+ SQLITE_PATH=~/trueforge/db.sqlite npx @truefoundry/trueforge+ ```++ </Accordion>+ <Accordion title="What is PUBLIC_BASE_URL and when do I need to set it?">+ The public origin the server hands to MCP servers for OAuth callbacks. It defaults to `http://localhost:<port>`, which is correct as long as you access TrueForge from the same machine.++ Set it when the server is reachable at a different address — behind a domain, reverse proxy, or on another host:++ ```bash+ PUBLIC_BASE_URL=https://agents.example.com npx @truefoundry/trueforge+ ```++ In hosted mode, set it in `packages/server/.env` (Docker Compose) or via `server.publicBaseUrl` (Helm).++ </Accordion>+</AccordionGroup>+## Next steps<CardGroup cols={2}>diff --git a/docs/roadmap.mdx b/docs/roadmap.mdxnew file mode 100644index 000000000..bce982b37--- /dev/null+++ b/docs/roadmap.mdx@@ -0,0 +1,32 @@+---+title: 'Roadmap'+sidebarTitle: 'Roadmap'+description: 'Where TrueForge is headed — planned work across gateway integration, local mode, the harness, agent authoring, approvals, and evaluation.'+---++This page tracks the major directions we're investing in. It is directional, not a committed schedule — priorities and ordering may change. To influence it, open an issue or discussion on [GitHub](https://github.com/truefoundry/trueforge).++## Gateway integration++- **Models and MCP servers from a gateway** — pull model providers and MCP servers from a gateway like [TrueFoundry](https://www.truefoundry.com), instead of configuring each one by hand. One place for credentials, access control, and usage across every agent.++## Local mode++- **Local sandbox execution** — run the sandbox on your own machine in [local mode](/introduction#two-ways-to-run-it), so the Claude Desktop-like setup gets code execution without a remote sandbox provider.++## Smarter harness++- **Automatic model selection** — let the harness pick the right model for each task, balancing accuracy and cost instead of pinning one model per agent.+- **AI-assisted agent authoring** — save an agent directly from a chat thread, with the instructions auto-composed from what worked in the conversation.++## Agent authoring and management++- **More flexible agent saving** — expose every agent option in the UI layer, including sandbox configuration, security policies, and the rest of the [agent spec](/api/agent-spec).++## Approvals and governance++- **Approve once** — configure certain tools so one approval covers subsequent calls, instead of re-prompting the user on every invocation.++## Evaluation++- **Evaluation pipeline in CI/CD** — regression-test agents as part of CI/CD, so changes to instructions, models, or tools are evaluated before they ship.