Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

Improvements in docs (#173)

Abhishek Choudhary6dd7a43cb95c
diff --git a/docs/api/overview.mdx b/docs/api/overview.mdx
index 2381de265..d75542eb3 100644
--- a/docs/api/overview.mdx
+++ b/docs/api/overview.mdx
@@ -36,7 +36,7 @@ flowchart TD
### Agent
-An **agent** is a definition, not a running process. You define it once — model, instructions, tools, config — and any number of conversations can use it. For `support-bot`, a customer support assistant that looks up orders and processes refunds via an MCP server, the [AgentSpec](/api/agent-spec) looks like this:
+An **agent** is a definition, not a running process. You define it once — model, instructions, tools, config — and any number of conversations can use it. For `support-bot`, a customer support assistant that looks up orders and processes refunds via an MCP server, the [AgentSpec](/create-agent/agent-spec) looks like this:
```json support-bot — AgentSpec
{
@@ -56,7 +56,7 @@ An **agent** is a definition, not a running process. You define it once — mode
}
```
-You can save this spec as a named agent and reference it by name in every session, or pass it inline when creating a session. See the [agent spec reference](/api/agent-spec) for every field.
+You can save this spec as a named agent and reference it by name in every session, or pass it inline when creating a session. See the [agent spec reference](/create-agent/agent-spec) for every field.
### Session
diff --git a/docs/api/use-agent.mdx b/docs/api/use-agent.mdx
index f3b3d6cac..1bd1c1c47 100644
--- a/docs/api/use-agent.mdx
+++ b/docs/api/use-agent.mdx
@@ -9,7 +9,7 @@ This guide covers everything you need to **run** an agent with [`trueforge-sdk`]
For the conceptual hierarchy (Agent → Session → Turn → Event → Delta) and a short end-to-end walkthrough, see [SDK Overview](/api/overview). For every event field, see [Turn events](/api/turn-events).
<Note>
-Prerequisite: a named agent in the registry, or an inline [agent spec](/api/agent-spec) you pass when creating the session. The quickest path to a named agent is the [Quickstart](/quickstart) UI.
+Prerequisite: a named agent in the registry, or an inline [agent spec](/create-agent/agent-spec) you pass when creating the session. The quickest path to a named agent is the [Quickstart](/quickstart) UI.
</Note>
## Install and connect
@@ -46,7 +46,7 @@ stateDiagram-v2
### Open a session
-Create a session by agent name, or pass an inline [agent spec](/api/agent-spec):
+Create a session by agent name, or pass an inline [agent spec](/create-agent/agent-spec):
```typescript
import { TrueForge } from 'trueforge-sdk';
diff --git a/docs/authentication/okta.mdx b/docs/authentication/okta.mdx
deleted file mode 100644
index 87315ba1d..000000000
--- a/docs/authentication/okta.mdx
+++ /dev/null
@@ -1,86 +0,0 @@
----
-title: 'Okta'
-sidebarTitle: 'Okta'
-description: 'Step-by-step: configure Okta as the OIDC identity provider for TrueForge.'
----
-
-Use this after reading the [Setup Login overview](/authentication/overview). Below is Okta-specific setup only.
-
-## Create the app
-
-1. Applications → **Create App Integration** → OIDC → **Web Application**.
-2. Grant type: **Authorization Code**.
-3. Sign-in redirect URI: `https://<your-public-host>/api/v1/auth/callback`.
-4. Assign users or groups who should sign in.
-5. Copy **Client ID** and **Client secret**.
-
-Use a **Web** (confidential) app with a client secret. A SPA / `PublicClientApp` fails token exchange with invalid client secret — TrueForge always authenticates to the token endpoint with the client secret.
-
-Sign-out redirect URI is unused by TrueForge (logout only clears the local cookie). Set the app origin if Okta requires a value.
-
-## Authorization Server
-
-Point `OIDC_ISSUER_URL` at a **custom** Authorization Server, usually `https://<your-oidc-domain>/oauth2/default`. On that server:
-
-1. **Access Policies** — a rule that includes this Web client, grant type Authorization Code, your users, and the scopes you request (`openid`, `profile`, `email`, and `groups` if used).
-2. **Scopes** — if you request `groups`, create a custom scope named `groups` (it is not built-in on custom authorization servers).
-3. **Claims** — add an **ID token** claim named to match `OIDC_USER_ROLE_CLAIM` (default `groups`): Groups value type, filter as needed, include in the ID token (not access token only).
-
-## Example config
-
-Group `harness-admin` → admin role:
-
-```bash
-PUBLIC_BASE_URL=https://trueforge.example.com
-OIDC_ISSUER_URL=https://integrator-XXXX.okta.com/oauth2/default
-OIDC_CLIENT_ID=0oa...
-OIDC_CLIENT_SECRET=...
-OIDC_USER_REFERENCE_CLAIM=email
-OIDC_USER_ROLE_CLAIM=groups
-OIDC_ADMIN_ROLE_VALUE=harness-admin
-OIDC_SCOPES=openid,profile,email,groups
-```
-
-Helm: set `server.publicBaseUrl` for the callback origin. Pass `OIDC_*` through `server.extraEnv` (or `extraEnvFrom`); keep the client secret in a Kubernetes Secret:
-
-```yaml
-server:
- publicBaseUrl: "https://trueforge.example.com"
- extraEnv:
- - name: OIDC_ISSUER_URL
- value: "https://integrator-XXXX.okta.com/oauth2/default"
- - name: OIDC_CLIENT_ID
- value: "0oa..."
- - name: OIDC_CLIENT_SECRET
- valueFrom:
- secretKeyRef:
- name: truefoundry-utils-oidc
- key: client-secret
- - name: OIDC_USER_REFERENCE_CLAIM
- value: email
- - name: OIDC_USER_ROLE_CLAIM
- value: groups
- - name: OIDC_ADMIN_ROLE_VALUE
- value: harness-admin
- - name: OIDC_SCOPES
- value: openid,profile,email,groups
-extraObjects:
- - apiVersion: v1
- kind: Secret
- metadata:
- name: truefoundry-utils-oidc
- type: Opaque
- stringData:
- client-secret: "..."
-```
-
-## Troubleshooting
-
-| Symptom | Likely cause |
-| ------- | ------------ |
-| `no_matching_policy` / Policy evaluation failed | Access Policy on the Authorization Server does not include this client, grant, scopes, or user |
-| `You are not allowed to access this app` | User not assigned to the Okta application, or app sign-on policy denies them |
-| `invalid client secret` | App is SPA/public; recreate as **Web** with a client secret |
-| Stuck blank authorize URL with `groups` scope | Custom AS missing `groups` scope and/or ID-token groups claim |
-| Login works but `role: "user"` | Groups claim missing from ID token, wrong claim name, or admin value mismatch (case-sensitive) |
-| SDK gets 401 | OIDC on and no `Authorization: Bearer` / cookie |
diff --git a/docs/authentication/overview.mdx b/docs/authentication/overview.mdx
index 2da6ba620..ab86984cd 100644
--- a/docs/authentication/overview.mdx
+++ b/docs/authentication/overview.mdx
@@ -1,85 +1,226 @@
---
title: 'Setup Login'
-sidebarTitle: 'Overview'
-description: 'Turn on OIDC login for shared deployments — or keep the no-auth default for local use.'
+sidebarTitle: 'Setup Login'
+description: 'Keep the no-auth default for local use, or turn on OIDC so your team signs in with your identity provider.'
---
-TrueForge authentication is optional. For local use you can leave it off. For a shared team deployment, turn on OIDC so people sign in with your identity provider and Settings stay admin-only.
+Login in TrueForge is **optional**. Run it without auth for personal, local use, or connect an OIDC identity provider (Okta, Microsoft Entra ID, or any standard OIDC IdP) so your team signs in and Settings stay admin-only.
## Choose your mode
| Mode | When to use | What users see |
| --- | --- | --- |
-| **No login** | Local `npx`, trusted networks | No login screen; everyone is a fixed local admin |
-| **OIDC login** | Hosted / shared teams | Sign-in with your IdP; roles `admin` or `user` |
+| **No login** (default) | Local `npx`, or a network you fully trust | No login screen; everyone is a single shared local admin |
+| **OIDC login** | Hosted or shared team deployments | Sign-in with your IdP; each person is an `admin` or a `user` |
-Standalone / local mode ignores OIDC even if env vars are present.
+<Note>
+ Standalone / local mode ignores OIDC even if the variables are set. OIDC login applies to hosted deployments (Docker Compose or Helm).
+</Note>
-## Guide: leave auth off (local)
+## Option A — leave login off
-1. Do **not** set `OIDC_ISSUER_URL`, `OIDC_CLIENT_ID`, or `OIDC_CLIENT_SECRET`.
-2. Run TrueForge as usual ([Quickstart](/quickstart)).
-3. Open the UI — there is no login screen. Settings and chat are available immediately.
+The default. Do **not** set any `OIDC_*` variables, run TrueForge as usual ([Quickstart](/quickstart)), and open the UI — there is no login screen, and Settings and chat are available immediately.
-Use this only on localhost or behind network controls you trust. On a public host, anyone who can reach the server gets admin Settings access under one shared identity.
+<Warning>
+ Use this only on `localhost` or behind network controls you trust. On a public host, anyone who can reach the server gets full admin access under one shared identity.
+</Warning>
-## Guide: enable OIDC for your team
+## Option B — enable OIDC login
-### 1. Prepare your identity provider
+<Steps>
+ <Step title="Register an app with your identity provider">
+ Create a **confidential (Web)** OIDC application. Whatever the provider, you need:
-Create a **confidential (Web)** OIDC app with:
-
-- Grant type **Authorization Code** (PKCE is also used)
-- Redirect URI: `{PUBLIC_BASE_URL}/api/v1/auth/callback`
-- Users/groups allowed to sign in
-- ID token claims for identity and admin membership (see below)
-
-Public / SPA clients are not supported — TrueForge needs a client secret.
-
-Provider-specific steps: [Okta](/authentication/okta).
-
-### 2. Set server environment
-
-Set all three OIDC variables together (partial config fails startup), plus the public origin:
-
-| Variable | Required | Purpose |
-| --- | --- | --- |
-| `PUBLIC_BASE_URL` | yes | Public origin users and the IdP see (no trailing path) |
-| `OIDC_ISSUER_URL` | yes* | IdP issuer (discovery at `/.well-known/openid-configuration`) |
-| `OIDC_CLIENT_ID` | yes* | OIDC client ID |
-| `OIDC_CLIENT_SECRET` | yes* | OIDC client secret |
-| `OIDC_USER_REFERENCE_CLAIM` | no (default `sub`) | Claim used as the user id for session ownership |
-| `OIDC_USER_ROLE_CLAIM` | no (default `groups`) | Claim inspected for admin membership |
-| `OIDC_ADMIN_ROLE_VALUE` | no (default `admin`) | Exact string that grants `admin` (case-sensitive) |
-| `OIDC_SCOPES` | no (default `openid,profile,email`) | Scopes for the authorize request |
-
-\*Required when enabling OIDC; otherwise leave all three unset.
-
-In Helm, set `server.publicBaseUrl` and pass `OIDC_*` through `server.extraEnv` / `server.extraEnvFrom`. Keep the client secret in a Kubernetes Secret.
-
-### 3. Map admin vs user
-
-| Role | Who | What they can do |
-| --- | --- | --- |
-| **admin** | Role claim contains `OIDC_ADMIN_ROLE_VALUE` | Chat + change Settings (models, connectors, skills, sandbox) |
-| **user** | Everyone else who can sign in | Chat and use agents; Settings hidden |
-
-Session history is still owner-only — admins are not global session superusers today. The [Agent Library](/agent-library) is currently shared: agents created by anyone are visible to everyone on the instance.
-
-### 4. Sign in and verify
-
-1. Open the UI — you should get the IdP login.
-2. After login, confirm admins see **Settings** and non-admins do not.
-3. If someone expected admin but got user, decode their ID token and check the role claim value (exact, case-sensitive). Sign out and back in after IdP claim changes.
-
-### 5. 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/client-credentials flow yet.
-
-Keep ID token lifetimes short at the IdP — the same JWT unlocks the API as cookie or Bearer.
+ - Grant type **Authorization Code** (PKCE is also used)
+ - Redirect URI: `https://<trueforge-url>/api/v1/auth/callback`, where `<trueforge-url>` is the public address of your TrueForge instance (the same value you set as `PUBLIC_BASE_URL`)
+ - The users or groups allowed to sign in
+ - An **ID token** claim carrying group/role membership, so TrueForge can tell admins from users
+
+ <Warning>
+ Public / SPA clients are **not** supported — TrueForge authenticates to the token endpoint with a client secret, so a SPA app fails token exchange with an `invalid client secret` error.
+ </Warning>
+
+ TrueForge speaks standard OIDC, so any IdP that issues ID tokens works. Pick your provider for exact steps:
+
+ <Tabs>
+ <Tab title="Okta">
+ **1. Create the application**
+
+ 1. Applications → **Create App Integration** → **OIDC** → **Web Application**.
+ 2. Grant type: **Authorization Code**.
+ 3. Sign-in redirect URI: `https://<trueforge-url>/api/v1/auth/callback`.
+ 4. Assign the users or groups who should sign in.
+ 5. Copy the **Client ID** and **Client secret**.
+
+ The sign-out redirect URI is unused — logout only clears the local cookie.
+
+ **2. Configure the Authorization Server**
+
+ Point `OIDC_ISSUER_URL` at a **custom** Authorization Server, usually `https://<your-okta-domain>/oauth2/default`. On that server:
+
+ - **Access Policies** — add a rule that includes this Web client, grant type Authorization Code, your users, and the scopes you request (`openid`, `profile`, `email`, and `groups` if used).
+ - **Scopes** — if you request `groups`, create a custom scope named `groups` (it is not built in on custom authorization servers).
+ - **Claims** — add an **ID token** claim named to match `OIDC_USER_ROLE_CLAIM` (default `groups`): Groups value type, filtered as needed, included in the **ID token**.
+
+ **3. Example values** (group `harness-admin` → admin role)
+
+ ```bash
+ OIDC_ISSUER_URL=https://integrator-XXXX.okta.com/oauth2/default
+ OIDC_CLIENT_ID=0oa...
+ OIDC_CLIENT_SECRET=...
+ OIDC_USER_REFERENCE_CLAIM=email
+ OIDC_USER_ROLE_CLAIM=groups
+ OIDC_ADMIN_ROLE_VALUE=harness-admin
+ OIDC_SCOPES=openid,profile,email,groups
+ ```
+
+ Plug these into the environment variables in the next step.
+ </Tab>
+ <Tab title="Microsoft Entra ID (Azure AD)">
+ **1. Register the application**
+
+ 1. Microsoft Entra admin center → **App registrations** → **New registration**.
+ 2. Under **Authentication** → **Add a platform** → **Web**, add the redirect URI `https://<trueforge-url>/api/v1/auth/callback`.
+ 3. Under **Certificates & secrets** → **New client secret**, create a secret and copy its **value** (not the ID).
+ 4. From the **Overview** page, copy the **Application (client) ID** and **Directory (tenant) ID**.
+
+ **2. Set the issuer and group claims**
+
+ - Issuer: use the v2.0 endpoint `https://login.microsoftonline.com/<tenant-id>/v2.0`.
+ - Under **Token configuration** → **Add groups claim**, emit the groups claim in the **ID token**.
+
+ <Note>
+ Entra emits **group Object IDs** (GUIDs) in the `groups` claim, not group names — so set `OIDC_ADMIN_ROLE_VALUE` to your admin group's Object ID. To use a readable value instead, define an **App role** and point `OIDC_USER_ROLE_CLAIM` at the `roles` claim.
+ </Note>
+
+ **3. Example values** (admin group Object ID → admin role)
+
+ ```bash
+ OIDC_ISSUER_URL=https://login.microsoftonline.com/<tenant-id>/v2.0
+ OIDC_CLIENT_ID=<application-client-id>
+ OIDC_CLIENT_SECRET=...
+ OIDC_USER_REFERENCE_CLAIM=email
+ OIDC_USER_ROLE_CLAIM=groups
+ OIDC_ADMIN_ROLE_VALUE=<admin-group-object-id>
+ OIDC_SCOPES=openid,profile,email
+ ```
+
+ If the `email` claim is missing for some users, use `preferred_username` or `oid` for `OIDC_USER_REFERENCE_CLAIM`.
+ </Tab>
+ </Tabs>
+ </Step>
+
+ <Step title="Set the server environment">
+ Set all three required OIDC variables together — partial config fails startup — plus the public origin.
+
+ | Variable | Required | Purpose |
+ | --- | --- | --- |
+ | <Tooltip tip="Public origin at which users and external services reach TrueForge (e.g. https://trueforge.myorg.com). The server uses it to build MCP OAuth and OIDC login callbacks.">`PUBLIC_BASE_URL`</Tooltip> | Yes | Public origin users and the IdP see (no trailing path) |
+ | `OIDC_ISSUER_URL` | Yes | IdP issuer (discovery at `/.well-known/openid-configuration`) |
+ | `OIDC_CLIENT_ID` | Yes | OIDC client ID |
+ | `OIDC_CLIENT_SECRET` | Yes | OIDC client secret |
+ | `OIDC_USER_REFERENCE_CLAIM` | No (default `sub`) | Claim used as the user id for session ownership |
+ | `OIDC_USER_ROLE_CLAIM` | No (default `groups`) | Claim inspected for admin membership |
+ | `OIDC_ADMIN_ROLE_VALUE` | No (default `admin`) | Exact string that grants `admin` (case-sensitive) |
+ | `OIDC_SCOPES` | No (default `openid,profile,email`) | Scopes for the authorize request |
+
+ How you pass these depends on how you run TrueForge:
+
+ <Tabs>
+ <Tab title="Docker Compose">
+ Add the variables to `packages/server/.env` (the source Compose reads):
+
+ ```bash packages/server/.env
+ PUBLIC_BASE_URL=https://trueforge.myorg.com
+ OIDC_ISSUER_URL=https://integrator-XXXX.okta.com/oauth2/default
+ OIDC_CLIENT_ID=0oa...
+ OIDC_CLIENT_SECRET=...
+ OIDC_USER_REFERENCE_CLAIM=email
+ OIDC_USER_ROLE_CLAIM=groups
+ OIDC_ADMIN_ROLE_VALUE=harness-admin
+ OIDC_SCOPES=openid,profile,email,groups
+ ```
+ </Tab>
+ <Tab title="Helm">
+ Set `server.publicBaseUrl`, pass the `OIDC_*` variables via `server.extraEnv`, and keep the client secret in a Kubernetes Secret:
+
+ ```yaml values.yaml
+ server:
+ publicBaseUrl: "https://trueforge.myorg.com"
+ extraEnv:
+ - name: OIDC_ISSUER_URL
+ value: "https://integrator-XXXX.okta.com/oauth2/default"
+ - name: OIDC_CLIENT_ID
+ value: "0oa..."
+ - name: OIDC_CLIENT_SECRET
+ valueFrom:
+ secretKeyRef:
+ name: truefoundry-utils-oidc
+ key: client-secret
+ - name: OIDC_USER_REFERENCE_CLAIM
+ value: email
+ - name: OIDC_USER_ROLE_CLAIM
+ value: groups
+ - name: OIDC_ADMIN_ROLE_VALUE
+ value: harness-admin
+ - name: OIDC_SCOPES
+ value: openid,profile,email,groups
+ extraObjects:
+ - apiVersion: v1
+ kind: Secret
+ metadata:
+ name: truefoundry-utils-oidc
+ type: Opaque
+ stringData:
+ client-secret: "..."
+ ```
+ </Tab>
+ </Tabs>
+
+ <Warning>
+ Keep `OIDC_CLIENT_SECRET` in a secret store — never commit it to version control.
+ </Warning>
+ </Step>
+
+ <Step title="Sign in and verify roles">
+ 1. Open the UI — you should be redirected to your IdP login.
+ 2. After login, confirm admins see **Settings** and non-admins do not.
+ 3. If someone expected admin but got `user`, decode their ID token and check the role claim value (exact match, case-sensitive). Sign out and back in after any IdP claim change.
+ </Step>
+</Steps>
+
+## Roles: admin vs user
+
+Each signed-in person maps to exactly one role, decided by the role claim in their ID token.
+
+| Role | Who | Can chat & use agents | Can change Settings |
+| --- | --- | --- | --- |
+| **admin** | Role claim contains `OIDC_ADMIN_ROLE_VALUE` | Yes | Yes — models, connectors, skills, sandbox |
+| **user** | Everyone else who can sign in | Yes | No — Settings hidden |
+
+<Note>
+ Two current limitations:
+ - **Session history is owner-only** — admins are not global session superusers today.
+ - **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.
+
+## Troubleshooting
+
+| Symptom | Likely cause |
+| --- | --- |
+| `no_matching_policy` / policy evaluation failed | Authorization Server access policy does not include this client, grant, scopes, or user (Okta) |
+| `You are not allowed to access this app` | User not assigned to the application, or the app sign-on policy denies them |
+| `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 |
## Security checklist
-- Prefer secrets storage for `OIDC_CLIENT_SECRET`; do not commit it.
+- Store `OIDC_CLIENT_SECRET` in a secret manager; never commit it.
- Do not expose a no-OIDC deployment on the public internet.
- Register the exact callback URL your users hit (scheme + host).
diff --git a/docs/api/agent-spec.mdx b/docs/create-agent/agent-spec.mdx
similarity index 95%
rename from docs/api/agent-spec.mdx
rename to docs/create-agent/agent-spec.mdx
index f1a459be5..3d1036e92 100644
--- a/docs/api/agent-spec.mdx
+++ b/docs/create-agent/agent-spec.mdx
@@ -4,7 +4,7 @@ sidebarTitle: 'Agent Spec'
description: 'Every field on the AgentSpec — model, instructions, MCP servers, skills, and runtime config.'
---
-An `AgentSpec` is the complete definition of an agent. Pass it inline when creating a session, or save it as a named agent and reference it by name. All fields are `snake_case`.
+An `AgentSpec` is the complete definition of an agent — everything you assemble in the [composer](/create-agent/overview) (model, connectors, skills, instructions) plus the runtime config that today is set via the [SDK](/api/overview). Saving an agent in the UI stores a spec; with the SDK you pass the same spec inline or reference a saved agent by name. All fields are `snake_case`.
```json A complete example
{
diff --git a/docs/create-agent/ask-user-questions.mdx b/docs/create-agent/ask-user-questions.mdx
index 972c3bbcf..36b10476c 100644
--- a/docs/create-agent/ask-user-questions.mdx
+++ b/docs/create-agent/ask-user-questions.mdx
@@ -12,7 +12,7 @@ It is **enabled by default**.
<Note>
Enabling or disabling Ask User Questions (`config.ask_user_questions`) is configured via the **API / SDK** today. The
- chat UI already renders questions and collects answers. See the [agent spec](/api/agent-spec#config).
+ chat UI already renders questions and collects answers. See the [agent spec](/create-agent/agent-spec#config).
</Note>
## How it feels in chat
diff --git a/docs/create-agent/generative-ui.mdx b/docs/create-agent/generative-ui.mdx
index 3c138df89..f9415b622 100644
--- a/docs/create-agent/generative-ui.mdx
+++ b/docs/create-agent/generative-ui.mdx
@@ -13,7 +13,7 @@ It is **enabled by default**, and the bundled chat UI renders it out of the box.
<Note>
Enabling or disabling Generative UI (`config.generative_ui`) is configured via the **API / SDK** today. Runtime
rendering in the chat UI works without extra setup when the feature is enabled. See the
- [agent spec](/api/agent-spec#config).
+ [agent spec](/create-agent/agent-spec#config).
</Note>
## How it works
diff --git a/docs/create-agent/overview.mdx b/docs/create-agent/overview.mdx
index b21f38620..e72f18396 100644
--- a/docs/create-agent/overview.mdx
+++ b/docs/create-agent/overview.mdx
@@ -47,4 +47,4 @@ These knobs are available on the agent today primarily through the **API / SDK**
| [Ask User Questions](/create-agent/ask-user-questions) | Enabled | Let the agent ask structured multiple-choice questions |
| [Generative UI](/create-agent/generative-ui) | Enabled | Let the agent render charts, tables, and cards |
-For the full field list, see the [agent spec](/api/agent-spec) in the SDK section.
+For the full field list, see the [Agent Spec reference](/create-agent/agent-spec).
diff --git a/docs/create-agent/tool-approval.mdx b/docs/create-agent/tool-approval.mdx
index 419bd3b5d..b9952bd82 100644
--- a/docs/create-agent/tool-approval.mdx
+++ b/docs/create-agent/tool-approval.mdx
@@ -13,7 +13,7 @@ Safe read-only tools stay autonomous. Write and destructive tools get a checkpoi
<Note>
Today, configuring `require_approval_for_tools` (and related enable/disable tool lists) is done via the **API / SDK**
when you create or update an agent. The chat UI already handles the Approve / Deny experience at runtime, but the
- builder does not yet expose the full approval policy editor. See the [agent spec](/api/agent-spec#mcp_servers).
+ builder does not yet expose the full approval policy editor. See the [agent spec](/create-agent/agent-spec#mcp_servers).
</Note>
Approval policy is set **per MCP server** on the agent. The default is write and destructive tools — any tool the MCP server does not mark as read-only, or marks as destructive. You can also list specific tool names, or gate every tool.
diff --git a/docs/docs.json b/docs/docs.json
index 4f807e758..0c05022dc 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -48,7 +48,8 @@
"create-agent/overview",
"create-agent/tool-approval",
"create-agent/ask-user-questions",
- "create-agent/generative-ui"
+ "create-agent/generative-ui",
+ "create-agent/agent-spec"
]
},
"agent-library",
@@ -63,15 +64,12 @@
]
},
"benchmarking",
- {
- "group": "Setup Login",
- "pages": ["authentication/overview", "authentication/okta"]
- }
+ "authentication/overview"
]
},
{
"group": "SDK",
- "pages": ["api/overview", "api/use-agent", "api/agent-spec", "api/turn-events"]
+ "pages": ["api/overview", "api/use-agent", "api/turn-events"]
},
{
"group": "Chat UI",
diff --git a/docs/harness/initial-setup.mdx b/docs/harness/initial-setup.mdx
index 877b9328c..4ce630d32 100644
--- a/docs/harness/initial-setup.mdx
+++ b/docs/harness/initial-setup.mdx
@@ -6,25 +6,20 @@ description: 'Configure models, MCP servers, skills, and a sandbox provider once
Before you build agents, configure the shared resources TrueForge orchestrates. You do this once in **Settings**; agents then pick from what you have connected.
-| Resource | Settings page | Purpose |
-| --- | --- | --- |
-| [Models](/models) | **Settings → Models** | Provider credentials and available model IDs |
-| [MCP servers](/mcp-servers) | **Settings → Connectors** | Tools and data from external systems |
-| [Skills](/skills) | **Settings → Skills** | Git-backed procedures the agent can load on demand |
-| [Sandbox](/sandbox) | **Settings → Sandbox providers** | Isolated compute for code, files, and skill execution |
+| Resource | Settings page | Purpose | Shipped catalog |
+| --- | --- | --- | --- |
+| [Models](/models) | **Settings → Models** | Provider credentials and available model IDs | [`model-catalog.yaml`](https://github.com/truefoundry/trueforge/blob/main/packages/server/src/catalog/model-catalog.yaml) |
+| [MCP servers](/mcp-servers) | **Settings → Connectors** | Tools and data from external systems | [`mcp-catalog.yaml`](https://github.com/truefoundry/trueforge/blob/main/packages/server/src/catalog/mcp-catalog.yaml) |
+| [Skills](/skills) | **Settings → Skills** | Git-backed procedures the agent can load on demand | [`skill-catalog.yaml`](https://github.com/truefoundry/trueforge/blob/main/packages/server/src/catalog/skill-catalog.yaml) |
+| [Sandbox](/sandbox) | **Settings → Sandbox providers** | Isolated compute for code, files, and skill execution | [`sandbox-catalog.yaml`](https://github.com/truefoundry/trueforge/blob/main/packages/server/src/catalog/sandbox-catalog.yaml) |
## What is supported out of the box
-Each Settings page is backed by a **shipped catalog** — a YAML file in the TrueForge server that lists presets the UI can offer:
+Each Settings page is backed by its **shipped catalog** — a YAML file in the TrueForge server (linked above) that lists the presets the UI can offer.
-| Catalog | Source |
-| --- | --- |
-| Models | [`model-catalog.yaml`](https://github.com/truefoundry/trueforge/blob/main/packages/server/src/catalog/model-catalog.yaml) |
-| MCP servers | [`mcp-catalog.yaml`](https://github.com/truefoundry/trueforge/blob/main/packages/server/src/catalog/mcp-catalog.yaml) |
-| Skills | [`skill-catalog.yaml`](https://github.com/truefoundry/trueforge/blob/main/packages/server/src/catalog/skill-catalog.yaml) |
-| Sandbox | [`sandbox-catalog.yaml`](https://github.com/truefoundry/trueforge/blob/main/packages/server/src/catalog/sandbox-catalog.yaml) |
+Catalogs are discovery lists only. Choosing a preset in the UI asks you for credentials (API key, OAuth, and so on); TrueForge stores the configured resource in its database and then they are used in the agent configuration.
-Catalogs are discovery lists only. Choosing a preset in the UI asks you for credentials (API key, OAuth, and so on); TrueForge stores the configured resource separately. The catalog itself is never called with your secrets.
+<Note>If you remove an entry from the catalog after configuring it in the UI, it will still be available for selection in the agent configuration.</Note>
You can also add entries that are **not** in a catalog — for example a custom OpenAI-compatible model endpoint, or an MCP server at any URL.
diff --git a/docs/introduction.mdx b/docs/introduction.mdx
index 4bb3ef0af..d60e9e628 100644
--- a/docs/introduction.mdx
+++ b/docs/introduction.mdx
@@ -51,7 +51,7 @@ flowchart LR
style byo stroke-dasharray: 6 4
```
-### Core server
+### Trueforge server
Runs the agent loop. When a user sends a message, the server:
diff --git a/docs/key-features/large-tool-responses.mdx b/docs/key-features/large-tool-responses.mdx
index de3ddd9d2..f17fcb63f 100644
--- a/docs/key-features/large-tool-responses.mdx
+++ b/docs/key-features/large-tool-responses.mdx
@@ -67,4 +67,4 @@ Turn offloading on or off per agent:
}
```
-The thresholds themselves default to **6,000 tokens** per response, **10,000 tokens** combined, and a **100-character** preview. See [`config.context_management`](/api/agent-spec#config) in the agent spec reference.
+The thresholds themselves default to **6,000 tokens** per response, **10,000 tokens** combined, and a **100-character** preview. See [`config.context_management`](/create-agent/agent-spec#config) in the agent spec reference.
diff --git a/docs/key-features/subagents.mdx b/docs/key-features/subagents.mdx
index a9fd38c4b..314696de2 100644
--- a/docs/key-features/subagents.mdx
+++ b/docs/key-features/subagents.mdx
@@ -103,4 +103,4 @@ See [Turn events](/api/turn-events#thread-created) for the full schemas.
## Disabling
-Set `config.dynamic_sub_agents.enabled: false` on the agent. See [`config.dynamic_sub_agents`](/api/agent-spec#config) in the agent spec reference.
+Set `config.dynamic_sub_agents.enabled: false` on the agent. See [`config.dynamic_sub_agents`](/create-agent/agent-spec#config) in the agent spec reference.
diff --git a/docs/mcp-servers.mdx b/docs/mcp-servers.mdx
index f77e9fef1..98d811691 100644
--- a/docs/mcp-servers.mdx
+++ b/docs/mcp-servers.mdx
@@ -25,15 +25,7 @@ You can also use **Add MCP Server** to register any remote URL that is not in th
/>
</div>
-## Where the connectors list comes from
-
-The popular servers under **Settings → Connectors** come from a shipped catalog YAML:
-
-[`mcp-catalog.yaml`](https://github.com/truefoundry/trueforge/blob/main/packages/server/src/catalog/mcp-catalog.yaml)
-
-Each entry is a ready-made remote MCP preset (URL, logo, and default auth shape — for example Linear and Notion with OAuth, or GitHub with a header placeholder). Choosing a catalog server creates a configured connector; the catalog itself is never executed against.
-
-To change which presets appear, see [Initial Setup](/harness/initial-setup#changing-what-the-ui-offers).
+The catalog entries under **Settings → Connectors** (Linear, Notion, GitHub, and others) come from the shipped MCP catalog — see [Initial Setup](/harness/initial-setup#what-is-supported-out-of-the-box) for how catalogs work and how to change what the UI offers.
## Authentication options
@@ -41,7 +33,14 @@ To change which presets appear, see [Initial Setup](/harness/initial-setup#chang
- **Header auth** — static HTTP headers (API keys, bearer tokens) sent on every request.
- **OAuth (Dynamic Client Registration)** — TrueForge registers as an OAuth client, runs the authorization-code flow, and stores and refreshes tokens. Users never paste tokens into the agent.
-Set `PUBLIC_BASE_URL` on the server so OAuth callbacks resolve to the right origin.
+<Info>
+ For OAuth to work, the MCP server must redirect the user back to your TrueForge instance — so the server needs to
+ know its own public address. That is the `PUBLIC_BASE_URL` environment variable. It defaults to
+ `http://localhost:<port>`, which is fine on your own machine; set it whenever TrueForge is reached at a different
+ address (a domain, reverse proxy, or another host). Where to set it depends on how you run TrueForge — as an env var
+ for `npx`, in `packages/server/.env` for Docker Compose, or `server.publicBaseUrl` for Helm. See the
+ [Quickstart FAQ](/quickstart#faq).
+</Info>
## In-chat authentication
diff --git a/docs/models.mdx b/docs/models.mdx
index ad114aa37..2eb07aa49 100644
--- a/docs/models.mdx
+++ b/docs/models.mdx
@@ -35,15 +35,7 @@ Open **Settings → Models**, pick a provider, and paste your API key. Models fr
/>
</div>
-## Where the model list comes from
-
-The providers and models in **Settings → Models** come from a shipped catalog YAML:
-
-[`model-catalog.yaml`](https://github.com/truefoundry/trueforge/blob/main/packages/server/src/catalog/model-catalog.yaml)
-
-That file lists the standard provider presets and model IDs. When you pick a provider in the UI, you paste your API key and TrueForge stores a configured provider — the catalog itself is never called with your credentials.
-
-To change which presets appear, see [Initial Setup](/harness/initial-setup#changing-what-the-ui-offers).
+The provider list comes from the shipped model catalog — see [Initial Setup](/harness/initial-setup#what-is-supported-out-of-the-box) for how catalogs work and how to change what the UI offers.
## Adding a custom provider
diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx
index f37d2f558..1ad68e616 100644
--- a/docs/quickstart.mdx
+++ b/docs/quickstart.mdx
@@ -30,9 +30,10 @@ TrueForge runs in [two modes](/introduction#two-ways-to-run-it): **local mode**
Then open [http://localhost:8791](http://localhost:8791).
- | Configuration | Default | Description |
- | ----------------------------------------------------- | ----------- | -------------------------------------------------------- |
- | `POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB` | from `.env` | Postgres credentials, read from `packages/server/.env`. |
+ | Configuration | Default | Description |
+ | ----------------------------------------------------- | ----------------------- | -------------------------------------------------------- |
+ | `POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB` | from `.env` | Postgres credentials, read from `packages/server/.env`. |
+ | <Tooltip tip="Public origin at which users and external services reach TrueForge (e.g. https://trueforge.myorg.com). The server uses it to build MCP OAuth and OIDC login callbacks." cta="See the FAQ" href="/quickstart#faq">`PUBLIC_BASE_URL`</Tooltip> | `http://localhost:8791` | Public origin, used for MCP OAuth callbacks. |
| Host ports | `8791`, `5433`, `6380` | App, Postgres, and Redis. |
</Tab>
@@ -180,6 +181,18 @@ With TrueForge open in your browser, this walkthrough takes you from an empty wo
```
</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://trueforge.myorg.com npx @truefoundry/trueforge
+ ```
+
+ In hosted mode, set it in `packages/server/.env` (Docker Compose) or via `server.publicBaseUrl` (Helm).
+
+ </Accordion>
</AccordionGroup>
## Next steps
diff --git a/docs/roadmap.mdx b/docs/roadmap.mdx
index bce982b37..3d6ea891f 100644
--- a/docs/roadmap.mdx
+++ b/docs/roadmap.mdx
@@ -21,7 +21,7 @@ This page tracks the major directions we're investing in. It is directional, not
## 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).
+- **More flexible agent saving** — expose every agent option in the UI layer, including sandbox configuration, security policies, and the rest of the [agent spec](/create-agent/agent-spec).
## Approvals and governance
diff --git a/docs/sandbox.mdx b/docs/sandbox.mdx
index 067848ee1..422b8ed1e 100644
--- a/docs/sandbox.mdx
+++ b/docs/sandbox.mdx
@@ -42,17 +42,11 @@ Open **Settings → Sandbox providers**, pick the [Daytona](https://www.daytona.
/>
</div>
-### Where the provider list comes from
-
-Presets come from a shipped catalog YAML:
-
-[`sandbox-catalog.yaml`](https://github.com/truefoundry/trueforge/blob/main/packages/server/src/catalog/sandbox-catalog.yaml)
-
-To change which presets appear, see [Initial Setup](/harness/initial-setup#changing-what-the-ui-offers).
+The provider presets come from the shipped sandbox catalog — see [Initial Setup](/harness/initial-setup#what-is-supported-out-of-the-box) for how catalogs work and how to change what the UI offers.
## Enabling the sandbox on an agent
-The sandbox is **off by default** per agent. Turn it on in the agent builder when you need code execution, skills, or Code Mode. You can also set `config.sandbox.enabled` when creating agents via the [SDK](/api/agent-spec).
+The sandbox is **off by default** per agent. Turn it on in the agent builder when you need code execution, skills, or Code Mode. You can also set `config.sandbox.enabled` in the [agent spec](/create-agent/agent-spec) when creating agents via the SDK.
Optional controls:
diff --git a/docs/skills.mdx b/docs/skills.mdx
index a5a333294..896498b12 100644
--- a/docs/skills.mdx
+++ b/docs/skills.mdx
@@ -23,13 +23,7 @@ Open **Settings → Skills**, pick a starter skill from the catalog, or add your
/>
</div>
-## Where the skills list comes from
-
-Starter skills under **Settings → Skills** come from a shipped catalog YAML:
-
-[`skill-catalog.yaml`](https://github.com/truefoundry/trueforge/blob/main/packages/server/src/catalog/skill-catalog.yaml)
-
-Each entry points at a git repo (and optional path/ref) with a short description. To change which presets appear, see [Initial Setup](/harness/initial-setup#changing-what-the-ui-offers).
+The starter skills in the catalog come from the shipped skill catalog — see [Initial Setup](/harness/initial-setup#what-is-supported-out-of-the-box) for how catalogs work and how to change what the UI offers.
## What a skill contains