The open-source agent harness - the runtime layer that turns an LLM into a working agent.
---
title: "TrueForgeUI"
description: "The entry component and every prop it accepts."
---
```tsx
import { TrueForgeUI } from "@truefoundry/trueforge-ui";
```
## Properties
<ParamField path="server" type="TrueForgeServerConfig" required>
Where the chat gets its data. Either a built-in config object or a ready `AgentUIServer`.
<Expandable title="TrueForgeServerConfig">
<ParamField path="type" type='"trueforge"'>
Omit entirely to pass an `AgentUIServer` object directly — there is no `"custom"` wrapper.
`"trueforge"` loads the Harness adapter (`plugins/trueforge-agent-server-adapter`). See
[Quickstart](/ui-sdk/get-started/quickstart).
</ParamField>
<ParamField path="baseUrl" type="string">
TrueForge / Harness API root. Used when `type` is `"trueforge"`. Defaults to `'/'`.
</ParamField>
<ParamField path="token" type="string">
Bearer token for `@truefoundry/trueforge-sdk` when `type` is `"trueforge"`. Prefer `fetch` for
cookie / OIDC hosts.
</ParamField>
<ParamField path="fetch" type="typeof fetch">
Custom fetch for `type: "trueforge"` (cookie sessions, auth interceptors).
</ParamField>
<ParamField path="catalog" type="CatalogServer">
Attach or override settings catalogs. See [Settings catalog](/ui-sdk/reference/catalog).
</ParamField>
<ParamField path="permissions" type="PermissionsServer">
Override the built-in permissions port.
</ParamField>
</Expandable>
See [Server contract](/ui-sdk/setup-custom-servers/server-contract).
</ParamField>
<ParamField path="layout" type="LayoutProp" required>
A built-in layout name or your own component.
<Expandable title="LayoutProp">
<ParamField path='"sidebar"' type="BuiltInLayout">
Full-page chat with a persistent thread list.
</ParamField>
<ParamField path='"drawer"' type="BuiltInLayout">
Thread list collapses into an overlay drawer.
</ParamField>
<ParamField path='"dock"' type="BuiltInLayout">
Right-pinned panel, capped at 400px. Stacks list and thread.
</ParamField>
<ParamField path='"widget"' type="BuiltInLayout">
Floating launcher expanding into a compact panel.
</ParamField>
<ParamField path="Custom" type="ComponentType<{ className?: string }>">
Your own component, rendered inside the full provider stack.
</ParamField>
</Expandable>
See [Layouts](/ui-sdk/guides/layouts).
</ParamField>
<ParamField path="agentConfig" type="AgentConfig" default='{ mode: "AgentLibraryWithComposer" }'>
Which agent-selection surfaces the shell exposes.
<Expandable title="AgentConfig">
<ParamField path='{ mode: "SingleAgent"; name: string }' type="variant">
Pins the UI to one named agent. `name` is required; selection controls are hidden.
</ParamField>
<ParamField path='{ mode: "AgentLibrary" }' type="variant">
Users pick from saved agents. New chat is disabled in this mode only.
</ParamField>
<ParamField path='{ mode: "AgentComposer"; defaultAgentSpec?: AgentSpec }' type="variant">
Users assemble an ad-hoc agent.
</ParamField>
<ParamField path='{ mode: "AgentLibraryWithComposer"; defaultAgentSpec?: AgentSpec }' type="variant">
Both surfaces. The default.
</ParamField>
</Expandable>
`defaultAgentSpec` seeds a new draft and is picked up on new chat, not on clear chat. See
[Agent modes](/ui-sdk/concepts/agent-modes).
</ParamField>
<ParamField path="theme" type="ThemeConfig">
Preset, color mode, tokens, branding, and content class names.
<Expandable title="ThemeConfig">
<ParamField path="preset" type='"trueforge" | "claude" | "chatgpt" | "gemini"' default='"trueforge"'>
Base token palette.
</ParamField>
<ParamField path="mode" type='"light" | "dark" | "system"'>
Omit for uncontrolled — the SDK resolves `system` and persists the user's choice to
`localStorage` under `aui-theme-preference`. Passing a value makes it controlled and turns
`setTheme` into a no-op.
</ParamField>
<ParamField path="tokens" type="Partial<SemanticTokens>">
Per-token overrides, merged over the preset and applied as inline styles.
<Expandable title="SemanticTokens">
<ParamField path="Across product" type="string">
`sidebarBg`, `sidebarText`, `topbarBg`, `primaryBg`, `secondaryBg`, `border`, `fontFamily`
(maps to `--font-agent-ui`).
</ParamField>
<ParamField path="Building blocks" type="string">
`inputBoxBg`, `inputBorder`, `textPrimary`, `textSecondary`, `cardBg`,
`dropdownSelectedItemBg`, `dropdownSelectedItemText`.
</ParamField>
<ParamField path="Chat" type="string">
`userMessageBg`, `userMessageText`, `assistantMessageBg`, `assistantMessageText`.
</ParamField>
<ParamField path="Buttons" type="string">
`primaryButtonBg` / `primaryButtonHover` / `primaryButtonText`, and the same trio for
`secondaryButton*` and `ghostButton*`.
</ParamField>
<ParamField path="Status" type="string">
`successBg` / `successText`, `failureBg` / `failureText`, `warningBg` / `warningText`.
</ParamField>
<ParamField path="Kept internals" type="string">
`focusRing`, `radius`, `composerRadius`, `overlay`, `shadowColor`, `scrollbarThumb`.
</ParamField>
</Expandable>
</ParamField>
<ParamField path="brand" type="BrandConfig">
Optional. Omit it to use the built-in TrueForge wordmark in expanded chrome and
square mark in compact surfaces. When set, choose `mode` first, then pass the
fields that mode requires.
<Expandable title="BrandConfig">
<ParamField path="mode" type='"icon-title" | "icon-only" | "logo"'>
Chrome look. `icon-title` shows `name` beside the square mark; `icon-only`
and `logo` keep `name` for alt only.
</ParamField>
<ParamField path="name" type="string">
Required. Accessible image label (`alt` / `aria-label`). Also shown as title
text beside the square icon when `mode` is `icon-title`.
</ParamField>
<ParamField path="icon" type="string | BrandLogoConfig">
Square image used in collapsed and compact surfaces. Optional for
`icon-title` (default mark); required for `icon-only` and `logo`.
</ParamField>
<ParamField path="logo" type="string | BrandLogoConfig">
Wider image used when `mode` is `logo`. Falls back to `icon` in
`BrandLogo` if needed. Required for `mode: "logo"`.
</ParamField>
<ParamField path="href" type="string">
Wraps configured brand images in a same-tab link.
</ParamField>
</Expandable>
<Expandable title="BrandLogoConfig">
<ParamField path="light" type="string">
Source used when the resolved mode is light.
</ParamField>
<ParamField path="dark" type="string">
Source used when the resolved mode is dark.
</ParamField>
<ParamField path="src" type="string">
Mode-agnostic source, used when neither `light` nor `dark` is set.
</ParamField>
</Expandable>
A single configured mode is used for both modes, so `{ light }` alone never renders a
missing image. Use `BrandLogo` with `variant="icon"` or `variant="logo"` in custom
layouts. To render a component rather than an image, override its slot through
`overrides`.
</ParamField>
<ParamField path="icons" type="IconMap">
Replace registry icons by name. Values are Lucide components, React nodes, render
functions, or SVGR components.
</ParamField>
<ParamField path="classNames" type="ContentClassNames">
Host CSS classes for content renderers. See [Custom Theme — Styling rendered content](/ui-sdk/setup-custom-ui/custom-theme).
<Expandable title="ContentClassNames">
<ParamField path="markdown" type="string">
Root of the markdown renderer (joins `.aui-markdown`).
</ParamField>
<ParamField path="inlineCode" type="string">
Inline code spans inside markdown.
</ParamField>
<ParamField path="syntaxHighlighter" type="{ root?, pre?, code?, lineNumber? }">
Fenced non-OpenUI code blocks (joins `.aui-syntax-highlighter` on `root`).
</ParamField>
<ParamField path="openui" type="{ root?, scope? }">
Generative UI fence blocks (`root` joins `.aui-openui`; `scope` is the OpenUI theme selector).
</ParamField>
<ParamField path="monaco" type="{ root?, editor?, monacoTheme? }">
Monaco editor wrapper (`root` joins `.aui-monaco`), mount container (`editor`), and optional Monaco theme name (`monacoTheme`).
</ParamField>
</Expandable>
</ParamField>
<ParamField path="className" type="string">
Applied to the theme root wrapper.
</ParamField>
</Expandable>
See [Theming](/ui-sdk/setup-custom-ui/custom-theme).
</ParamField>
<ParamField path="overrides" type="SlotOverrides">
Replace any built-in component. `Partial<AtomSlots>`, derived from the SDK's default slot
table — so editor autocomplete lists the overridable names. See
[Slot overrides](/ui-sdk/setup-custom-ui/slot-overrides).
</ParamField>
<ParamField path="className" type="string">
Passed to the layout component, and to the loading and error states. Typically
`"h-full min-h-0"`. To style the theme wrapper instead, use `theme.className`.
</ParamField>
<ParamField path="initialSessionId" type="string">
Open an existing session on mount instead of starting fresh.
</ParamField>
<ParamField path="adapters" type="RuntimeAdapters">
Runtime adapter overrides. Attachments default to `trueForgeAttachmentAdapter`.
</ParamField>
<ParamField path="onError" type="(error: unknown) => void">
Called when the server fails to resolve or the runtime raises an error.
</ParamField>
## Behavior notes
The component mounts every provider it needs, so you do not have to wrap it in anything.
Switching agents, starting a new draft, or clearing the chat resets the conversation — the
current transcript is cleared so that one agent's messages do not carry into another's context.
Persisted sessions remain available through the thread list.
<Warning>
If `window.location.search` contains `screenType=mcp-auth`, the component renders only the
OAuth completion screen and no layout. See [MCP OAuth](/ui-sdk/setup-custom-ui/mcp-oauth).
</Warning>
## Example
```tsx
<TrueForgeUI
server={{ type: "trueforge", baseUrl, token }}
layout="sidebar"
agentConfig={{ mode: "AgentComposer", defaultAgentSpec: { model: { name: "openai-main/gpt-4.1" } } }}
theme={{
preset: "claude",
brand: { mode: "logo", name: "Acme", icon: "/icon.svg", logo: "/wordmark.svg" },
}}
overrides={{ ClearChatButton: MyClearButton }}
className="h-full min-h-0"
onError={(e) => reportError(e)}
/>
```