The open-source agent harness - the runtime layer that turns an LLM into a working agent.
Changes in docs (#278)
Abhishek Choudhary81d4340d8c8b
diff --git a/README.md b/README.mdindex 5658fad53..6df749769 100644--- a/README.md+++ b/README.md@@ -48,93 +48,11 @@ Building an agent is easy. Running one well is not - you need streaming, sessionIt scales down and up: **local mode** (one process, SQLite) or **hosted mode** (Postgres + Redis, Docker Compose or Helm).-## Quick start+## Getting started-### Local mode (npx)+Run TrueForge (local, Docker Compose, or Kubernetes), connect a model and tools, and build your first reusable agent in the [Quickstart](https://trueforge.dev/quickstart).-Requires [Node.js](https://nodejs.org) 22.13 or newer. One command, no other infrastructure - UI and backend run locally; data is stored in SQLite:--```bash-npx @truefoundry/trueforge@rc-```--Then open [http://localhost:8790](http://localhost:8790).--### From source (pnpm)--Standalone (SQLite) topology from a clone - no Docker. Requires Node.js 22.13+ and [pnpm](https://pnpm.io):--```bash-git clone https://github.com/truefoundry/trueforge.git-cd trueforge-cp packages/server/.env.example packages/server/.env-pnpm standalone:dev-```--Then open [http://localhost:3000](http://localhost:3000) - Vite serves the UI with live reload and proxies API calls to the server on port 8790. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development guide (including Postgres + Redis).--### Hosted mode (Docker Compose)--Server (UI + API), Postgres, and Redis:--```bash-git clone https://github.com/truefoundry/trueforge.git-cd trueforge-cp packages/server/.env.example packages/server/.env-docker compose up --build-```--Then open [http://localhost:8791](http://localhost:8791).--| Configuration | Default | Description |-| ----------------------------------------------------- | ---------------------- | ---------------------------------------------- |-| `POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB` | from `.env` | Postgres credentials (`packages/server/.env`). |-| Host ports | `8791`, `5433`, `6380` | App, Postgres, and Redis. |--Every environment variable is documented in [`packages/server/.env.example`](packages/server/.env.example).--### Hosted mode (Kubernetes)--The [`charts/trueforge`](charts/trueforge) Helm chart deploys hosted mode with bundled Postgres and Redis (or your own):--```bash-helm install trueforge oci://tfy.jfrog.io/tfy-helm/trueforge \- --version <x.y.z>-```--See the [chart README](charts/trueforge/README.md) (including [`configs.oidc`](charts/trueforge/README.md#oidc)) and [Quickstart](https://trueforge.dev/quickstart) for values and details.--## Build your first agent--Full walkthrough: [Quickstart](https://trueforge.dev/quickstart). The example below builds a **web research briefer** — it searches the web, fans out to parallel subagents, and renders an interactive brief. To get started, you only need a model key.--1. **Add a model provider** - **Settings → Models**, pick a provider, paste your API key.-- --2. **Connect a web-search tool** - **Settings → Connectors**, connect **Exa** (no auth needed).-- --3. **Compose and run** - pick a model, enable Exa, and send:-- > Research the current state of open-source vector databases. Compare Qdrant, Weaviate, and Milvus on performance, features, and licensing, then write a one-page brief with sources.-- The agent searches with Exa, delegates to parallel subagents, and renders an interactive brief inline. Generative UI is on by default, so no extra setup is needed.-- --4. **Save as an agent** - click **Save Agent** and name it `web-research-brief`.-- --5. **Find it in the Agent Library** - open **Agents Library**, then **Try** or **Edit**. In hosted mode with login enabled, agents created by anyone are visible to everyone - see [Agent Library](https://trueforge.dev/agent-library).-- --> **Optional — run code, files, and richer skills.** To let the agent run code or use skills like **web-artifacts-builder** (which packages the brief into a standalone, shareable HTML page), add a **Daytona** sandbox under **Settings → Sandbox providers**. Skills run in the sandbox.->-> +To work on TrueForge from this repository, see [CONTRIBUTING.md](CONTRIBUTING.md).## Architecture@@ -169,18 +87,18 @@ flowchart LR## Documentation-| Section | What you'll find |-| -------------------------------------------------------------- | ----------------------------------------------------------------- |-| [Introduction](https://trueforge.dev/introduction) | What an agent harness is and how TrueForge fits together |-| [Quickstart](https://trueforge.dev/quickstart) | Run local or hosted, build your first agent |-| [Initial Setup](https://trueforge.dev/harness/initial-setup) | Models, MCP, skills, sandbox - catalogs and overrides |-| [Create an Agent](https://trueforge.dev/create-agent/overview) | Select resources; tool approval, questions, Generative UI |-| [Key Features](https://trueforge.dev/key-features/overview) | Sandbox-as-tool, subagents, deferred tools, Code Mode, compaction |-| [Benchmarking](https://trueforge.dev/benchmarking) | Cost/accuracy vs Claude Managed Agents and deepagents |-| [Setup Login](https://trueforge.dev/authentication/overview) | Optional OIDC for shared deployments |-| [SDK](https://trueforge.dev/api/overview) | TypeScript client: sessions, turns, events |-| [Chat UI](https://trueforge.dev/chat-ui) | Bundled UI and embedding `@truefoundry/trueforge-ui` |-| [API Reference](https://trueforge.dev/api-reference) | OpenAPI paths and schemas |+| Section | What you'll find |+| ------------------------------------------------------------------- | ----------------------------------------------------------------- |+| [Introduction](https://trueforge.dev/introduction) | What an agent harness is and how TrueForge fits together |+| [Quickstart](https://trueforge.dev/quickstart) | Run local or hosted, build your first agent |+| [Initial Setup](https://trueforge.dev/harness/initial-setup) | Models, MCP, skills, sandbox - catalogs and overrides |+| [Create an Agent](https://trueforge.dev/create-agent/overview) | Select resources; tool approval, questions, Generative UI |+| [Harness Capabilities](https://trueforge.dev/key-features/overview) | Sandbox-as-tool, subagents, deferred tools, Code Mode, compaction |+| [Setup Login](https://trueforge.dev/authentication/overview) | Optional OIDC for shared deployments |+| [Benchmarking](https://trueforge.dev/benchmarking) | Cost/accuracy vs Claude Managed Agents and deepagents |+| [SDK](https://trueforge.dev/api/overview) | TypeScript client: sessions, turns, events |+| [Chat UI](https://trueforge.dev/chat-ui) | Bundled UI and embedding `@truefoundry/trueforge-ui` |+| [API Reference](https://trueforge.dev/api-reference) | OpenAPI paths and schemas |## Benchmarksdiff --git a/docs/api/overview.mdx b/docs/api/overview.mdxindex b58514213..b2336a148 100644--- a/docs/api/overview.mdx+++ b/docs/api/overview.mdx@@ -297,11 +297,28 @@ sequenceDiagramA separate issue — Bob's shipping question, or even Jane's next problem — runs in its own session, where Turn 1 starts fresh with no refund history carried over.+## Call an authenticated API++When [login is off](/authentication/overview) (the default), omit any token — the SDK talks to the server as the shared local admin.++When [OIDC login](/authentication/overview) is enabled, the HTTP API requires authentication. The chat UI uses an HttpOnly cookie after sign-in. For the SDK — or any other HTTP client — send the same OIDC **ID token** as a bearer token:++```typescript+const client = new TrueForge({+ baseUrl: 'https://trueforge.myorg.com',+ token: process.env.TRUEFORGE_TOKEN,+});+```++That sets `Authorization: Bearer <id_token>` on every request. Get the token from your identity provider (or reuse a browser session). There is no device-code or client-credentials flow yet. Keep ID token lifetimes short at the IdP — the same JWT unlocks the API as either a cookie or a bearer token.++A missing or expired token against an OIDC-enabled server returns `401`.+## Run it with the SDK### 1. Create a session-Pass an inline agent spec, or reference a saved agent by name:+Pass an inline agent spec, or reference a saved agent by name. The example below assumes login is off; if OIDC is on, pass `token` as shown in [Call an authenticated API](#call-an-authenticated-api).```typescriptimport { TrueForge } from '@truefoundry/trueforge-sdk';diff --git a/docs/api/use-agent.mdx b/docs/api/use-agent.mdxindex edb1eeb40..2885bd280 100644--- a/docs/api/use-agent.mdx+++ b/docs/api/use-agent.mdx@@ -30,7 +30,7 @@ const client = new TrueForge({});```-When auth is enabled, pass `token` (Bearer ID token). When auth is disabled, omit it.+When [OIDC login](/authentication/overview) is enabled, pass `token` — an ID token from your IdP. See [Call an authenticated API](/api/overview#call-an-authenticated-api). When login is off, omit it.## Create a sessiondiff --git a/docs/authentication/overview.mdx b/docs/authentication/overview.mdxindex 287145037..d9acbe6f8 100644--- a/docs/authentication/overview.mdx+++ b/docs/authentication/overview.mdx@@ -205,9 +205,7 @@ Each signed-in person maps to exactly one role, decided by the role claim in the- **The [Agent Library](/agent-library) is shared** — agents created by anyone are visible to everyone on the instance.</Note>-## Call the API with a token (optional)--The UI stores an HttpOnly cookie after login. For the [SDK](/api/overview), send the same ID token as `Authorization: Bearer <id_token>`. Obtain the token from your IdP (or reuse a browser session) — there is no device or client-credentials flow yet. Keep ID token lifetimes short at the IdP, since the same JWT unlocks the API as either a cookie or a bearer token.+To call the HTTP API or SDK against a server with login enabled, pass an ID token — see [Call an authenticated API](/api/overview#call-an-authenticated-api).## Troubleshooting@@ -218,7 +216,7 @@ The UI stores an HttpOnly cookie after login. For the [SDK](/api/overview), send| `invalid client secret` | App is SPA/public — recreate it as a **Web** (confidential) app with a client secret || Blank authorize screen when requesting `groups` | Custom Authorization Server is missing the `groups` scope and/or ID-token groups claim (Okta) || Login works but everyone is `role: "user"` | Groups/roles claim missing from the ID token, wrong claim name, or admin value mismatch (case-sensitive) |-| SDK returns `401` | OIDC is on and the request has no `Authorization: Bearer` header or session cookie |+| SDK returns `401` | OIDC is on and the request has no [ID token](/api/overview#call-an-authenticated-api) or session cookie |## Security checklistdiff --git a/docs/create-agent/agent-spec.mdx b/docs/create-agent/agent-spec.mdxindex 12e3eef5d..5c1230de5 100644--- a/docs/create-agent/agent-spec.mdx+++ b/docs/create-agent/agent-spec.mdx@@ -49,7 +49,7 @@ The only required field.## `instructions`-Optional string. The agent's system prompt — its role, behavior, and constraints. The harness appends its own guidance for enabled capabilities (sandbox, subagents, etc.), so keep this focused on _your_ agent. See [Key Features](/key-features/overview) for how context is managed at runtime.+Optional string. The agent's system prompt — its role, behavior, and constraints. The harness appends its own guidance for enabled capabilities (sandbox, subagents, etc.), so keep this focused on _your_ agent. See [Harness Capabilities](/key-features/overview) for how context is managed at runtime.## `messages`diff --git a/docs/docs.json b/docs/docs.jsonindex 2a5aedfd4..724c1b840 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -53,7 +53,7 @@},"agent-library",{- "group": "Key Features",+ "group": "Harness Capabilities","pages": ["key-features/overview","key-features/subagents",@@ -62,8 +62,8 @@"key-features/large-tool-responses"]},- "benchmarking",- "authentication/overview"+ "authentication/overview",+ "benchmarking"]},{diff --git a/docs/introduction.mdx b/docs/introduction.mdxindex d51264ace..3e3f096cd 100644--- a/docs/introduction.mdx+++ b/docs/introduction.mdx@@ -19,6 +19,8 @@ An agent harness is the runtime layer around an LLM that turns it into a reliablTrueForge 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.+<GitHub.Repo repo="truefoundry/trueforge" />+<Frame caption="The bundled chat UI — a streaming response with the agent-steps panel expanded to show reasoning, tool calls, and a subagent."><img src="/images/chat-ui.png" alt="The TrueForge chat UI showing an agent response with the agent-steps panel expanded — reasoning, Exa tool calls, and a subagent" /></Frame>@@ -57,7 +59,7 @@ 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](/create-agent/overview#tool-approval) on sensitive actions-- Keeps context lean on long tasks with [key features](/key-features/overview) like subagents and compaction+- Keeps context lean on long tasks with [harness capabilities](/key-features/overview) like subagents and compaction- Persists sessions, so conversations survive reconnects and restartsThe 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.@@ -104,16 +106,19 @@ Like Claude's managed agents: one deployment the whole company uses, via Docker- **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-## Explore the docs+## Start building<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="Initial Setup" icon="sliders" href="/harness/initial-setup">Configure models, MCP servers, skills, and sandbox — and customize the shipped catalogs.</Card><Card title="Create an Agent" icon="robot" href="/create-agent/overview">Select a model, attach connectors and skills, then save to the Agent Library.</Card>- <Card title="Key Features" icon="layer-group" href="/key-features/overview">+ <Card title="Harness Capabilities" icon="layer-group" href="/key-features/overview">Sandbox-as-tool, subagents, deferred tools, code mode, compaction, and human checkpoints.</Card><Card title="Setup Login" icon="lock" href="/authentication/overview">@@ -126,17 +131,3 @@ Like Claude's managed agents: one deployment the whole company uses, via DockerBundled chat experience, or embed `@truefoundry/trueforge-ui` in your React app.</Card></CardGroup>--## Start building--<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="Benchmarking" icon="chart-line" href="/benchmarking">- Same tasks and model vs Claude Managed Agents and deepagents — cost and accuracy.- </Card>- <Card title="UI SDK reference" icon="book" href="/chat-ui">- Themes, layouts, slots, and the full React component API.- </Card>-</CardGroup>diff --git a/docs/key-features/overview.mdx b/docs/key-features/overview.mdxindex 95928bab0..ff141e01b 100644--- a/docs/key-features/overview.mdx+++ b/docs/key-features/overview.mdx@@ -1,5 +1,5 @@----title: 'Key Features'+title: 'Harness Capabilities'sidebarTitle: 'Overview'description: 'Sandbox-as-tool, context engineering, human checkpoints, and Generative UI — how TrueForge keeps agents reliable and efficient.'---diff --git a/docs/mcp-servers.mdx b/docs/mcp-servers.mdxindex 8f54e598d..e7440be95 100644--- a/docs/mcp-servers.mdx+++ b/docs/mcp-servers.mdx@@ -58,4 +58,4 @@ If a server uses OAuth and the user has not yet authorized it, the turn pauses a- Attach MCP servers when you [create an agent](/create-agent/overview).- Configure which tools need [approval](/create-agent/overview#tool-approval) (API today).-- Keep tool schemas lean with [deferred loading](/key-features/deferred-tool-loading) in Key Features.+- Keep tool schemas lean with [deferred loading](/key-features/deferred-tool-loading) in Harness Capabilities.diff --git a/docs/quickstart.mdx b/docs/quickstart.mdxindex 617345a11..6ae39be2f 100644--- a/docs/quickstart.mdx+++ b/docs/quickstart.mdx@@ -125,21 +125,27 @@ With TrueForge open in your browser, this walkthrough takes you from an empty wo- **Skills** — enable **web-artifacts-builder**.- **Capabilities** — leave **Dynamic sub-agents** on (it's the default). This lets the agent research each item in parallel instead of one at a time.- <Columns cols={3}>- <Frame caption="Connectors">- - </Frame>- <Frame caption="Skills">- - </Frame>- <Frame caption="Capabilities">- - </Frame>- </Columns>+ <Tabs>+ <Tab title="Connectors">+ <Frame>+ + </Frame>+ </Tab>+ <Tab title="Skills">+ <Frame>+ + </Frame>+ </Tab>+ <Tab title="Capabilities">+ <Frame>+ + </Frame>+ </Tab>+ </Tabs>Then send your first message. For example:- ```text+ ```text wrapResearch the current state of open-source vector databases. Compare Qdrant, Weaviate, and Milvus on performance, features, and licensing, then write a one-page brief with sources.```@@ -156,7 +162,7 @@ With TrueForge open in your browser, this walkthrough takes you from an empty wo- **Name** — `web-research-brief`- **Instructions** —- ```text+ ```text wrapYou are a web research assistant. Given a topic or question, use Exa to search the web and pull content from the most relevant, recent sources. When the request compares several items, research each one in parallel, then synthesize the findings into a clear one-page brief.```@@ -220,7 +226,7 @@ With TrueForge open in your browser, this walkthrough takes you from an empty wo<Card title="Create an Agent" icon="robot" href="/create-agent/overview">Select resources and configure approvals, questions, and Generative UI.</Card>- <Card title="Key Features" icon="layer-group" href="/key-features/overview">+ <Card title="Harness Capabilities" icon="layer-group" href="/key-features/overview">Subagents, deferred tools, code mode, compaction, and more.</Card><Card title="SDK" icon="code" href="/api/overview">