Skip to content

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

Add optional VITE_BASE_PATH for UI public path behind Caddy. (#551)

Govinda Vashishtha9f3b4cd732db
diff --git a/.changeset/frontend-base-path-env.md b/.changeset/frontend-base-path-env.md
new file mode 100644
index 000000000..91af43e2f
--- /dev/null
+++ b/.changeset/frontend-base-path-env.md
@@ -0,0 +1,5 @@
+---
+"@truefoundry/trueforge": patch
+---
+
+Make the frontend UI public path configurable via optional `VITE_BASE_PATH` (defaults to `/`), keep API calls at `/`, and return OIDC login/logout to the UI base.
diff --git a/packages/frontend/src/App.tsx b/packages/frontend/src/App.tsx
index ad298f723..caf702fa2 100644
--- a/packages/frontend/src/App.tsx
+++ b/packages/frontend/src/App.tsx
@@ -12,10 +12,14 @@ import { probeSession, type SessionState } from './authSession';
import { parseAuthErrorReason, shouldShowAuthErrorScreen, stripAuthErrorSearch } from './authStatusSearch';
import { GetStartedScreen } from './GetStartedScreen';
import { LogoutButton } from './LogoutButton';
+import { uiRouterBasename } from './publicPath';
/** Shared cookie/OIDC fetch for boot helpers and `<TrueForgeUI server />`. */
const authAwareFetch = createAuthAwareFetch();
+// API stays at site root (`/api/...`). Caddy strips the UI public path before Harness;
+// only assets + React Router use `VITE_BASE_PATH` / `import.meta.env.BASE_URL`.
const bootClient = createTrueForgeClient({ fetch: authAwareFetch });
+const routerBasename = uiRouterBasename();
type BootState =
| { status: 'loading' }
@@ -164,6 +168,7 @@ export function App() {
server={{ type: 'trueforge', baseUrl: '/', fetch: authAwareFetch }}
layout="sidebar"
withRouter
+ {...(routerBasename ? { routes: { basename: routerBasename } } : {})}
agentConfig={{
mode: 'AgentLibraryWithComposer',
defaultAgentSpec: boot.defaultAgentSpec,
diff --git a/packages/frontend/src/GetStartedScreen.tsx b/packages/frontend/src/GetStartedScreen.tsx
index b5d4ce10a..393cae8ce 100644
--- a/packages/frontend/src/GetStartedScreen.tsx
+++ b/packages/frontend/src/GetStartedScreen.tsx
@@ -1,5 +1,5 @@
import { BrandLogo } from '@truefoundry/trueforge-ui';
-import { AUTH_LOGIN_HREF } from './authFetch';
+import { buildLoginHref } from './authFetch';
import './authScreens.css';
/**
@@ -16,7 +16,7 @@ export function GetStartedScreen() {
type="button"
className="auth-screen-button"
onClick={() => {
- window.location.assign(AUTH_LOGIN_HREF);
+ window.location.assign(buildLoginHref());
}}
>
Let&apos;s Get Started
diff --git a/packages/frontend/src/LogoutButton.tsx b/packages/frontend/src/LogoutButton.tsx
index 36f089c8c..2db69ef08 100644
--- a/packages/frontend/src/LogoutButton.tsx
+++ b/packages/frontend/src/LogoutButton.tsx
@@ -2,6 +2,7 @@ import { CenteredModal, Icon } from '@truefoundry/trueforge-ui';
import { useEffect, useState } from 'react';
import { getCachedIsOidcConnectedSession, isOidcConnectedSession, logout } from './authSession';
import './LogoutButton.css';
+import { UI_BASE_PATH } from './publicPath';
/**
* Icon button next to Settings (via `ShellActionsActionSlot` override).
@@ -43,8 +44,8 @@ export function LogoutButton() {
setBusy(true);
void logout()
.then(() => {
- // Land on the welcome gate (probe /me → unauthenticated → GetStartedScreen).
- window.location.assign('/');
+ // Land on the welcome gate under the UI public path (not site root).
+ window.location.assign(UI_BASE_PATH);
})
.catch(() => {
setBusy(false);
diff --git a/packages/frontend/src/authFetch.ts b/packages/frontend/src/authFetch.ts
index 83273c250..42d71196b 100644
--- a/packages/frontend/src/authFetch.ts
+++ b/packages/frontend/src/authFetch.ts
@@ -1,7 +1,12 @@
/**
* Browser auth entry points. Login and logout are not SDK methods (cookie session).
* On any HTTP 401, redirect to OIDC login (session required).
+ *
+ * API paths stay at `/api/...` even when the UI is mounted under a public path
+ * (Caddy strips `/trueforge` before Harness). Pass `return_to` so post-login
+ * lands back under that UI path.
*/
+import { UI_BASE_PATH } from './publicPath';
/** Browser entry for OIDC login (not available as an SDK method). */
export const AUTH_LOGIN_HREF = '/api/v1/auth/login';
@@ -9,6 +14,12 @@ export const AUTH_LOGIN_HREF = '/api/v1/auth/login';
/** Clears the local session cookie (not available as an SDK method). */
export const AUTH_LOGOUT_HREF = '/api/v1/auth/logout';
+/** Login URL with a same-origin `return_to` (defaults to the UI home). */
+export function buildLoginHref(returnTo: string = UI_BASE_PATH): string {
+ const params = new URLSearchParams({ return_to: returnTo });
+ return `${AUTH_LOGIN_HREF}?${params.toString()}`;
+}
+
export function createAuthAwareFetch(baseFetch: typeof fetch = globalThis.fetch.bind(globalThis)): typeof fetch {
let redirecting = false;
@@ -21,7 +32,7 @@ export function createAuthAwareFetch(baseFetch: typeof fetch = globalThis.fetch.
if (!redirecting) {
redirecting = true;
- window.location.assign(AUTH_LOGIN_HREF);
+ window.location.assign(buildLoginHref(`${window.location.pathname}${window.location.search}`));
}
// Do not surface 401 to callers — boot would flash a config error before navigation.
diff --git a/packages/frontend/src/publicPath.ts b/packages/frontend/src/publicPath.ts
new file mode 100644
index 000000000..b58fcac67
--- /dev/null
+++ b/packages/frontend/src/publicPath.ts
@@ -0,0 +1,16 @@
+/**
+ * UI public path from Vite `base` (`VITE_BASE_PATH`). Always `/` or a path with a
+ * trailing slash (e.g. `/trueforge/`). Distinct from the API origin: with a
+ * reverse proxy that strips this prefix, API calls stay at `/api/...`.
+ */
+export const UI_BASE_PATH =
+ typeof import.meta.env === 'object' &&
+ typeof import.meta.env.BASE_URL === 'string' &&
+ import.meta.env.BASE_URL.length > 0
+ ? import.meta.env.BASE_URL
+ : '/';
+
+/** React Router basename: no trailing slash; `undefined` when serving from `/`. */
+export function uiRouterBasename(): string | undefined {
+ return UI_BASE_PATH.length > 1 ? UI_BASE_PATH.replace(/\/$/, '') : undefined;
+}
diff --git a/packages/frontend/tests/authFetch.test.ts b/packages/frontend/tests/authFetch.test.ts
index 722f5f7a0..3a53afa32 100644
--- a/packages/frontend/tests/authFetch.test.ts
+++ b/packages/frontend/tests/authFetch.test.ts
@@ -1,8 +1,21 @@
import assert from 'node:assert/strict';
import { describe, it } from 'node:test';
-import { AUTH_LOGIN_HREF, AUTH_LOGOUT_HREF, createAuthAwareFetch } from '../src/authFetch';
+import { AUTH_LOGIN_HREF, AUTH_LOGOUT_HREF, buildLoginHref, createAuthAwareFetch } from '../src/authFetch';
import { parseAuthErrorReason } from '../src/authStatusSearch';
+describe('buildLoginHref', () => {
+ it('defaults return_to to the UI base path', () => {
+ const href = buildLoginHref();
+ assert.equal(href.startsWith(`${AUTH_LOGIN_HREF}?`), true);
+ assert.equal(new URL(href, 'http://example.test').searchParams.get('return_to'), '/');
+ });
+
+ it('encodes an explicit return_to path', () => {
+ const href = buildLoginHref('/trueforge/sessions/abc');
+ assert.equal(new URL(href, 'http://example.test').searchParams.get('return_to'), '/trueforge/sessions/abc');
+ });
+});
+
describe('createAuthAwareFetch', () => {
it('passes through non-401 responses', async () => {
const wrapped = createAuthAwareFetch(async () => new Response('ok', { status: 200 }));
@@ -22,12 +35,16 @@ describe('createAuthAwareFetch', () => {
// Minimal browser stub for the redirect path.
(globalThis as { window: Window }).window = {
location: {
+ pathname: '/sessions/abc',
+ search: '?tab=1',
assign: (href: string) => {
assigns.push(href);
},
},
} as Window;
+ const expectedLogin = buildLoginHref('/sessions/abc?tab=1');
+
try {
const wrapped = createAuthAwareFetch(async () => new Response('nope', { status: 401 }));
let settled = false;
@@ -35,12 +52,12 @@ describe('createAuthAwareFetch', () => {
settled = true;
});
await new Promise(resolve => setTimeout(resolve, 20));
- assert.deepEqual(assigns, [AUTH_LOGIN_HREF]);
+ assert.deepEqual(assigns, [expectedLogin]);
assert.equal(settled, false);
// Second 401 must not double-redirect.
void wrapped('/api/v1/models');
await new Promise(resolve => setTimeout(resolve, 20));
- assert.deepEqual(assigns, [AUTH_LOGIN_HREF]);
+ assert.deepEqual(assigns, [expectedLogin]);
} finally {
if (originalWindow === undefined) {
// node --test has no window by default
diff --git a/packages/frontend/vite.config.ts b/packages/frontend/vite.config.ts
index 4b6cab5fe..9ab66cbef 100644
--- a/packages/frontend/vite.config.ts
+++ b/packages/frontend/vite.config.ts
@@ -16,6 +16,18 @@ if (!Number.isInteger(PORT)) {
throw new Error(`FRONTEND_PORT must be an integer, got "${process.env.FRONTEND_PORT}"`);
}
+/** Optional public path (e.g. `/trueforge`). Empty/unset → `/`. Vite requires a trailing slash. */
+function resolveViteBase(raw: string | undefined): string {
+ const trimmed = raw?.trim();
+ if (trimmed === undefined || trimmed === '' || trimmed === '/') {
+ return '/';
+ }
+ const withLead = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+ return withLead.endsWith('/') ? withLead : `${withLead}/`;
+}
+
+const BASE = resolveViteBase(process.env.VITE_BASE_PATH);
+
const apiProxy: ProxyOptions = {
target: SERVER,
changeOrigin: true,
@@ -31,6 +43,7 @@ const apiProxy: ProxyOptions = {
};
export default defineConfig({
+ base: BASE,
plugins: [
react(),
monacoEditorPlugin({