Skip to content

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

feat: introduce sandbox environment feature flag in frontend (#958)

Sujai Kumar Gupta5300f50abfc7
diff --git a/.changeset/feature-flag-sandbox-environments.md b/.changeset/feature-flag-sandbox-environments.md
new file mode 100644
index 000000000..9d4229a30
--- /dev/null
+++ b/.changeset/feature-flag-sandbox-environments.md
@@ -0,0 +1,6 @@
+---
+'@truefoundry/trueforge': patch
+'@truefoundry/trueforge-ui': patch
+---
+
+Add a frontend feature flag for sandbox-environment management.
diff --git a/packages/frontend/README.md b/packages/frontend/README.md
index 868b3ae4a..18d6ec8e4 100644
--- a/packages/frontend/README.md
+++ b/packages/frontend/README.md
@@ -40,6 +40,9 @@ proxies `/api/*` to `VITE_SERVER_URL` (default `http://localhost:8790`).
already bound, dev exits instead of picking another. Proxy wiring lives in
[`vite.config.ts`](vite.config.ts).
+Set `VITE_SANDBOX_ENVIRONMENTS_ENABLED=true` when building or running Vite to enable the
+experimental sandbox-environments UI. It is disabled by default.
+
`predev` / `prebuild` / `pretypecheck` build `@truefoundry/trueforge-sdk` and
`@truefoundry/trueforge-ui` first so clean checkouts do not rely on stale `dist/`.
diff --git a/packages/frontend/src/App.tsx b/packages/frontend/src/App.tsx
index 9e18c2730..7099040f8 100644
--- a/packages/frontend/src/App.tsx
+++ b/packages/frontend/src/App.tsx
@@ -28,6 +28,7 @@ const authAwareFetch = createAuthAwareFetch();
// UI + API share the public prefix from `window.__TRUEFORGE_BASE_PATH__`.
const bootClient = createTrueForgeClient({ baseUrl: API_BASE_URL, fetch: authAwareFetch });
const routerBasename = uiRouterBasename();
+const sandboxEnvironmentsEnabled = import.meta.env.VITE_SANDBOX_ENVIRONMENTS_ENABLED === 'true';
/** Host brand: primary CTA fill is a gradient (see `index.css`); keep solid token for accents. */
const appTheme: ThemeConfig = {
@@ -202,7 +203,12 @@ export function App() {
return (
<div className="app-root">
<TrueForgeUI
- server={{ type: 'trueforge', baseUrl: API_BASE_URL, fetch: authAwareFetch }}
+ server={{
+ type: 'trueforge',
+ baseUrl: API_BASE_URL,
+ fetch: authAwareFetch,
+ sandboxEnvironments: sandboxEnvironmentsEnabled,
+ }}
layout="sidebar"
withRouter
{...(routerBasename ? { routes: { basename: routerBasename } } : {})}
diff --git a/packages/trueforge-ui/src/atoms/draft/AgentRuntimeConfigFields.tsx b/packages/trueforge-ui/src/atoms/draft/AgentRuntimeConfigFields.tsx
index 1ee8f1cf1..0f9c7baf0 100644
--- a/packages/trueforge-ui/src/atoms/draft/AgentRuntimeConfigFields.tsx
+++ b/packages/trueforge-ui/src/atoms/draft/AgentRuntimeConfigFields.tsx
@@ -3,6 +3,7 @@
import { useMemo } from 'react';
import { Icon } from '../../icons/Icon.js';
+import { useOptionalSandboxEnvironmentServer } from '../../server/ServerContext.js';
import { useOptionalShellMode } from '../../server/ShellModeContext.js';
import type { AgentCompactionConfig, AgentRuntimeConfig } from '../../server/types.js';
import { useReadySandboxEnvironments } from '../environments/useReadySandboxEnvironments.js';
@@ -65,6 +66,7 @@ export function AgentRuntimeConfigFields({
onChange,
}: AgentRuntimeConfigFieldsProps) {
const shell = useOptionalShellMode();
+ const environmentServer = useOptionalSandboxEnvironmentServer();
const { environments: readyEnvironments, refetch: refetchEnvironments } = useReadySandboxEnvironments();
const environmentOptions = useMemo(
@@ -242,45 +244,47 @@ export function AgentRuntimeConfigFields({
<section className="py-4">
{switchField({ field: sandboxField, className: rowClassName })}
<div className={`mt-3 border-l-2 border-primary-button-bg/50 pl-3 ${sandboxEnabled ? '' : 'opacity-50'}`}>
- <div className={cn('flex py-4', rowClassName)}>
- <span className="min-w-0 flex-1">
- <span className="text-text-primary block text-sm font-medium">Environment</span>
- <span className="text-text-secondary mt-0.5 block text-xs leading-snug">
- Image, resources, network and secrets the sandbox starts with. Stored by name.
+ {environmentServer != null ? (
+ <div className={cn('flex py-4', rowClassName)}>
+ <span className="min-w-0 flex-1">
+ <span className="text-text-primary block text-sm font-medium">Environment</span>
+ <p className="text-text-secondary mt-0.5 text-xs leading-snug">
+ Image, resources, network and secrets the sandbox starts with. Stored by name.
+ </p>
+ {shell ? (
+ <button
+ type="button"
+ onClick={() => shell.setEnvironmentsOpen(true)}
+ className="text-primary-button-bg mt-1.5 inline-flex items-center gap-1 text-xs hover:underline"
+ >
+ <span>Manage Environments</span>
+ <Icon name="external-link" className="size-3" />
+ </button>
+ ) : null}
</span>
- {shell ? (
- <button
- type="button"
- onClick={() => shell.setEnvironmentsOpen(true)}
- className="text-primary-button-bg mt-1.5 inline-flex items-center gap-1 text-xs hover:underline"
- >
- <span>Manage Environments</span>
- <Icon name="external-link" className="size-3" />
- </button>
- ) : null}
- </span>
- <div className="flex shrink-0 items-center">
- <PopoverSelect
- aria-label="Environment"
- value={value.sandbox?.environment_name?.trim() || 'default'}
- options={environmentOptions}
- disabled={disabled || !sandboxAvailable || !sandboxEnabled}
- className="w-48"
- onOpenChange={nextOpen => {
- if (nextOpen) void refetchEnvironments();
- }}
- onValueChange={selected =>
- onChange({
- ...value,
- sandbox: {
- ...value.sandbox,
- environment_name: selected === 'default' ? undefined : selected,
- },
- })
- }
- />
+ <div className="flex shrink-0 items-center">
+ <PopoverSelect
+ aria-label="Environment"
+ value={value.sandbox?.environment_name?.trim() || 'default'}
+ options={environmentOptions}
+ disabled={disabled || !sandboxAvailable || !sandboxEnabled}
+ className="w-48"
+ onOpenChange={nextOpen => {
+ if (nextOpen) void refetchEnvironments();
+ }}
+ onValueChange={selected =>
+ onChange({
+ ...value,
+ sandbox: {
+ ...value.sandbox,
+ environment_name: selected === 'default' ? undefined : selected,
+ },
+ })
+ }
+ />
+ </div>
</div>
- </div>
+ ) : null}
{switchField({ field: fileDownloadsField, className: rowClassName })}
</div>
</section>
diff --git a/packages/trueforge-ui/src/atoms/draft/DraftCompositeSelector.tsx b/packages/trueforge-ui/src/atoms/draft/DraftCompositeSelector.tsx
index 59975c20c..19d39a61f 100644
--- a/packages/trueforge-ui/src/atoms/draft/DraftCompositeSelector.tsx
+++ b/packages/trueforge-ui/src/atoms/draft/DraftCompositeSelector.tsx
@@ -5,7 +5,11 @@ import { useCallback, useEffect, useId, useMemo, useRef, useState, type ReactNod
import { useMCPAuth } from '../../hooks/useMcpAuth.js';
import { Icon } from '../../icons/Icon.js';
-import { useOptionalCatalogServer, useServerCapabilities } from '../../server/ServerContext.js';
+import {
+ useOptionalCatalogServer,
+ useOptionalSandboxEnvironmentServer,
+ useServerCapabilities,
+} from '../../server/ServerContext.js';
import { useOptionalShellMode, type SettingsSection } from '../../server/ShellModeContext.js';
import type { AgentSkill, ConnectorState } from '../../server/types.js';
import { useSlot } from '../../theme/SlotsProvider.js';
@@ -488,6 +492,8 @@ export function DraftCompositeSelector({ disabled, isRunning, onAttach }: DraftC
loading: environmentsLoading,
refetch: refetchEnvironments,
} = useReadySandboxEnvironments();
+ const environmentServer = useOptionalSandboxEnvironmentServer();
+ const tabs = environmentServer == null ? TABS.filter(item => item.id !== 'environments') : TABS;
const openPicker = (nextTab?: AttachTab) => {
if (nextTab != null) {
@@ -546,7 +552,7 @@ export function DraftCompositeSelector({ disabled, isRunning, onAttach }: DraftC
const content = (
<>
<div className="flex shrink-0 border-b border-border">
- {TABS.map(t => {
+ {tabs.map(t => {
const count = t.id === 'connectors' ? selectedMcp.length : t.id === 'skills' ? selectedSkills.length : null;
const active = tab === t.id;
return (
@@ -678,7 +684,7 @@ export function DraftCompositeSelector({ disabled, isRunning, onAttach }: DraftC
/>
) : null}
</>
- ) : (
+ ) : environmentServer != null ? (
<>
{filteredEnvironments.map(env => {
const isSelected = currentEnvName === env.name;
@@ -710,7 +716,7 @@ export function DraftCompositeSelector({ disabled, isRunning, onAttach }: DraftC
/>
) : null}
</>
- )}
+ ) : null}
</div>
</>
</>
diff --git a/packages/trueforge-ui/src/containers/useResolvedServer.ts b/packages/trueforge-ui/src/containers/useResolvedServer.ts
index 870d16022..c23043e00 100644
--- a/packages/trueforge-ui/src/containers/useResolvedServer.ts
+++ b/packages/trueforge-ui/src/containers/useResolvedServer.ts
@@ -94,6 +94,7 @@ export function useResolvedServer(
const trueforgeFetch = builtIn?.fetch;
const catalog = builtIn?.catalog;
const permissions = builtIn?.permissions;
+ const sandboxEnvironments = builtIn?.sandboxEnvironments;
const [state, setState] = useState<ResolvedServerState>(() => {
if (directServer) {
@@ -119,6 +120,7 @@ export function useResolvedServer(
...(trueforgeFetch !== undefined ? { fetch: trueforgeFetch } : {}),
...(catalog != null ? { catalog } : {}),
...(permissions != null ? { permissions } : {}),
+ ...(sandboxEnvironments !== undefined ? { sandboxEnvironments } : {}),
});
};
@@ -145,7 +147,16 @@ export function useResolvedServer(
return () => {
cancelled = true;
};
- }, [directServer, trueforgeBaseUrl, trueforgeToken, trueforgeFetch, catalog, permissions, onError]);
+ }, [
+ directServer,
+ trueforgeBaseUrl,
+ trueforgeToken,
+ trueforgeFetch,
+ catalog,
+ permissions,
+ sandboxEnvironments,
+ onError,
+ ]);
return state;
}
diff --git a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/index.ts b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/index.ts
index 8373f698e..7653a3eac 100644
--- a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/index.ts
+++ b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/index.ts
@@ -84,13 +84,15 @@ export type CreateTrueForgeAgentUIServerOptions = CreateTrueForgeClientOptions &
catalog?: CatalogServer;
/** Optional host-provided resource permissions port. */
permissions?: PermissionsServer;
+ /** Enable sandbox-environment routes and UI. Defaults to true for compatibility. */
+ sandboxEnvironments?: boolean;
};
/**
* Compose chat + builder + agent sessions + default settings catalogs into an `AgentUIServer`.
*/
export function createTrueForgeAgentUIServer(options: CreateTrueForgeAgentUIServerOptions = {}) {
- const { catalog: catalogOverride, permissions, ...clientOptions } = options;
+ const { catalog: catalogOverride, permissions, sandboxEnvironments = true, ...clientOptions } = options;
const client = createTrueForgeClient(clientOptions);
const catalog =
catalogOverride ??
@@ -109,7 +111,7 @@ export function createTrueForgeAgentUIServer(options: CreateTrueForgeAgentUIServ
sessions: createHarnessAgentSessionsServer({ ...clientOptions, client }),
metrics: createHarnessAgentMetricsServer({ ...clientOptions, client }),
schedules: createScheduleServer({ client }),
- sandboxEnvironments: createSandboxEnvironmentServer({ client }),
+ ...(sandboxEnvironments ? { sandboxEnvironments: createSandboxEnvironmentServer({ client }) } : {}),
permissions: permissions ?? createHarnessPermissionsServer({ client }),
getMe: async () => {
const { data } = await client.auth.me();
diff --git a/packages/trueforge-ui/src/server/TrueForgeServerConfig.ts b/packages/trueforge-ui/src/server/TrueForgeServerConfig.ts
index c9c7f375d..0a3c7d2bf 100644
--- a/packages/trueforge-ui/src/server/TrueForgeServerConfig.ts
+++ b/packages/trueforge-ui/src/server/TrueForgeServerConfig.ts
@@ -14,6 +14,8 @@ export type TrueForgeBuiltInServerConfig = {
fetch?: typeof fetch;
catalog?: CatalogServer;
permissions?: PermissionsServer;
+ /** Enable sandbox-environment routes and UI. Defaults to true for compatibility. */
+ sandboxEnvironments?: boolean;
};
/**
diff --git a/packages/trueforge-ui/test/atoms/draft/AgentRuntimeConfigFields.test.tsx b/packages/trueforge-ui/test/atoms/draft/AgentRuntimeConfigFields.test.tsx
index 26584f0e2..0eee126f4 100644
--- a/packages/trueforge-ui/test/atoms/draft/AgentRuntimeConfigFields.test.tsx
+++ b/packages/trueforge-ui/test/atoms/draft/AgentRuntimeConfigFields.test.tsx
@@ -16,11 +16,13 @@ function renderRuntimeFields({
value = { sandbox: { enabled: true } },
layout = 'detailed',
sandboxAvailable = true,
+ environmentsEnabled = true,
onChange = vi.fn(),
}: {
value?: AgentRuntimeConfig;
layout?: 'compact' | 'detailed';
sandboxAvailable?: boolean;
+ environmentsEnabled?: boolean;
onChange?: (val: AgentRuntimeConfig) => void;
} = {}) {
const environmentServer = createMockSandboxEnvironmentServer({
@@ -64,7 +66,7 @@ function renderRuntimeFields({
});
const server = createMockAgentUIServer({
- sandboxEnvironments: environmentServer,
+ ...(environmentsEnabled ? { sandboxEnvironments: environmentServer } : {}),
});
return render(
@@ -81,6 +83,14 @@ function renderRuntimeFields({
}
describe('AgentRuntimeConfigFields', () => {
+ it('hides environment controls when sandbox environments are disabled', () => {
+ renderRuntimeFields({ environmentsEnabled: false });
+
+ expect(screen.queryByText('Environment')).not.toBeInTheDocument();
+ expect(screen.queryByRole('button', { name: /Manage Environments/ })).not.toBeInTheDocument();
+ expect(screen.queryByRole('button', { name: 'Environment' })).not.toBeInTheDocument();
+ });
+
it('renders environment row in detailed layout with Manage Environments link', async () => {
renderRuntimeFields();
diff --git a/packages/trueforge-ui/test/atoms/draft/DraftCompositeSelector.test.tsx b/packages/trueforge-ui/test/atoms/draft/DraftCompositeSelector.test.tsx
index d01980507..b7a1b2362 100644
--- a/packages/trueforge-ui/test/atoms/draft/DraftCompositeSelector.test.tsx
+++ b/packages/trueforge-ui/test/atoms/draft/DraftCompositeSelector.test.tsx
@@ -143,6 +143,7 @@ describe('DraftCompositeSelector', () => {
expect(screen.getByRole('dialog', { name: 'Add to composer' })).toBeInTheDocument();
expect(screen.getByRole('button', { name: /Connectors/ })).toBeInTheDocument();
expect(screen.getByRole('button', { name: /Skills/ })).toBeInTheDocument();
+ expect(screen.queryByRole('button', { name: /Environment/ })).not.toBeInTheDocument();
expect(screen.queryByRole('button', { name: /Capabilities/ })).not.toBeInTheDocument();
agentSpec = { ...agentSpec, model: { name: ' ' } };
diff --git a/packages/trueforge-ui/test/containers/useResolvedServer.test.tsx b/packages/trueforge-ui/test/containers/useResolvedServer.test.tsx
index 25e8e4576..19c5cb4eb 100644
--- a/packages/trueforge-ui/test/containers/useResolvedServer.test.tsx
+++ b/packages/trueforge-ui/test/containers/useResolvedServer.test.tsx
@@ -17,19 +17,20 @@ const defaultHarnessPermissions: PermissionsServer = {
})),
};
-const mockCreateTrueForgeAgentUIServer = vi.fn((options?: { permissions?: PermissionsServer }) =>
- Promise.resolve(
- createMockAgentUIServer({
- getCapabilities: async () => ({
- data: {
- sandbox: { enabled: true },
- skill: { enabled: true },
- settings: { enabled: true },
- },
+const mockCreateTrueForgeAgentUIServer = vi.fn(
+ (options?: { permissions?: PermissionsServer; sandboxEnvironments?: boolean }) =>
+ Promise.resolve(
+ createMockAgentUIServer({
+ getCapabilities: async () => ({
+ data: {
+ sandbox: { enabled: true },
+ skill: { enabled: true },
+ settings: { enabled: true },
+ },
+ }),
+ permissions: options?.permissions ?? defaultHarnessPermissions,
}),
- permissions: options?.permissions ?? defaultHarnessPermissions,
- }),
- ),
+ ),
);
vi.mock('@/plugins/trueforge-agent-server-adapter/index.js', () => ({
@@ -92,6 +93,25 @@ describe('useResolvedServer', () => {
expect(result.current.server?.permissions).toBe(permissions);
});
+ it('passes the sandbox environments feature flag to the trueforge server', async () => {
+ mockCreateTrueForgeAgentUIServer.mockClear();
+ const { result } = renderHook(() =>
+ useResolvedServer({
+ type: 'trueforge',
+ token: 'tok',
+ sandboxEnvironments: false,
+ }),
+ );
+
+ await waitFor(() => {
+ expect(result.current.status).toBe('ready');
+ });
+ expect(mockCreateTrueForgeAgentUIServer).toHaveBeenCalledWith({
+ token: 'tok',
+ sandboxEnvironments: false,
+ });
+ });
+
it('attaches an optional catalog onto the trueforge server when factory returns one', async () => {
const catalog = createMockCatalog();
mockCreateTrueForgeAgentUIServer.mockImplementationOnce(async () =>
diff --git a/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/permissionsServer.test.ts b/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/permissionsServer.test.ts
index 8747f20cb..8ba92282b 100644
--- a/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/permissionsServer.test.ts
+++ b/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/permissionsServer.test.ts
@@ -41,3 +41,20 @@ describe('createTrueForgeAgentUIServer permissions', () => {
expect(server.permissions).toBe(permissions);
});
});
+
+describe('createTrueForgeAgentUIServer feature flags', () => {
+ it('enables sandbox environments by default', () => {
+ const server = createTrueForgeAgentUIServer({ fetch: vi.fn() });
+
+ expect(server.sandboxEnvironments).toBeDefined();
+ });
+
+ it('omits sandbox environments when disabled', () => {
+ const server = createTrueForgeAgentUIServer({
+ fetch: vi.fn(),
+ sandboxEnvironments: false,
+ });
+
+ expect(server.sandboxEnvironments).toBeUndefined();
+ });
+});