Skip to content

πŸ™Œ OpenHands: AI-Driven Development

Fix live agent-server frontend integration

openhandse406274c1242
diff --git a/.env.sample b/.env.sample
index dba2545e2b..9e3cccbae2 100644
--- a/.env.sample
+++ b/.env.sample
@@ -1,7 +1,7 @@
# OpenHands Agent Server target
VITE_BACKEND_HOST="127.0.0.1:8000" # Host:port used by the Vite dev proxy
VITE_BACKEND_BASE_URL="http://127.0.0.1:8000" # Base URL used by browser-side direct requests
-# VITE_SESSION_API_KEY="" # Optional X-Session-API-Key for authenticated backends
+# VITE_SESSION_API_KEY="" # Set to the same value as backend SESSION_API_KEY or OH_SESSION_API_KEYS_0 when auth is enabled
# VITE_WORKING_DIR="/workspace/project" # Workspace path used when starting conversations
# VITE_WORKER_URLS="" # Optional comma-separated worker URLs for the Browser tab
# VITE_ENABLE_BROWSER_TOOLS="true" # Set to false to omit BrowserToolSet from new conversations
diff --git a/AGENTS.md b/AGENTS.md
index 93176b23f0..81cc746116 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -22,9 +22,12 @@
- Useful regression tests for mock mode live in `__tests__/api/option-service.test.ts`, `__tests__/api/mock-conversation-handlers.test.ts`, and `__tests__/api/mock-settings-handlers.test.ts`.
- Browser-verified mock-mode tour artifact was generated at `artifacts/frontend-tour.gif`.
- Live `agent_server` compatibility quirks discovered during browser verification:
+ - Latest `openhands-agent-server` live-mode notes (verified against 1.18.1):
+ - `/api/settings/agent-schema` and `/api/settings/conversation-schema` exist on recent servers, but they return `401` when the server was started with `SESSION_API_KEY` or `OH_SESSION_API_KEYS_0`; the frontend must send the same value as `VITE_SESSION_API_KEY` / `X-Session-API-Key`.
+ - The provider/model picker should use `/api/llm/providers`, `/api/llm/models`, and `/api/llm/models/verified`; `/api/v1/config/providers/search` and `/api/v1/config/models/search` 404 on current live agent-server releases.
+ - When the browser is accessing the frontend through a remote host (for example an All Hands work URL) but `VITE_BACKEND_BASE_URL` points at `127.0.0.1`/`localhost`, browser-side REST calls must fall back to the frontend origin so Vite can proxy `/api` and `/sockets` to the local backend.
- `GET /api/conversations` expects repeated `ids` params (`?ids=a&ids=b`), not Axios's default bracket form (`ids[]=a`), so the shared Axios client needs a custom params serializer.
- Runtime git panels should prefer the conversation's reported `workspace.working_dir` when present; falling back to `/workspace/project` can produce 500s like `Not a git repository` for direct local workspaces such as `/workspace/project/agent-server-gui`.
- - Live settings currently load with the `SDK settings schema unavailable.` placeholder when the backend does not expose `/api/settings/agent-schema` and `/api/settings/conversation-schema`; this is expected for the current local backend.
- README expectation: the very first section should be a concrete from-scratch quickstart for running this frontend against a real `openhands-agent-server` (clone, install backend, optional `.env`, run `npm run dev`). Keep live-backend instructions ahead of general project overview.
diff --git a/README.md b/README.md
index b18281079c..93794be86d 100644
--- a/README.md
+++ b/README.md
@@ -34,6 +34,8 @@ openhands-agent-server --host 127.0.0.1 --port 8000
The frontend expects the backend at `127.0.0.1:8000` by default, so this is the easiest from-scratch setup.
+If you start the backend with `SESSION_API_KEY` or `OH_SESSION_API_KEYS_0`, every `/api/*` route is authenticated with `X-Session-API-Key`. In that case the frontend must send the same key via `VITE_SESSION_API_KEY`.
+
If you prefer installing from source or want the full SDK setup flow, see the OpenHands SDK docs: <https://docs.openhands.dev/sdk/getting-started>
### 3. Optional: create a `.env` file
@@ -50,6 +52,7 @@ Then update the values you need:
VITE_BACKEND_HOST="127.0.0.1:8000"
VITE_BACKEND_BASE_URL="http://127.0.0.1:8000"
VITE_FRONTEND_PORT="3001"
+# Use the same value as backend SESSION_API_KEY or OH_SESSION_API_KEYS_0 when auth is enabled.
# VITE_SESSION_API_KEY="your-session-api-key"
# VITE_WORKING_DIR="/absolute/path/to/the-workspace-used-by-agent-server"
```
@@ -59,6 +62,7 @@ Notes:
- `VITE_BACKEND_HOST` is used by the Vite dev proxy for `/api`, `/server_info`, and `/sockets`.
- `VITE_BACKEND_BASE_URL` is used by browser-side direct requests. Keep it pointed at the same backend.
- `VITE_WORKING_DIR` should match the workspace path the backend will use when starting new conversations.
+- If the backend is secured with `SESSION_API_KEY` or `OH_SESSION_API_KEYS_0`, set `VITE_SESSION_API_KEY` to the same value or live requests will fail with `401 Unauthorized`.
- If your backend does not require `X-Session-API-Key`, leave `VITE_SESSION_API_KEY` unset.
### 4. Start the frontend
@@ -77,7 +81,8 @@ After the page opens:
- you should be able to open or create a conversation
- `/conversations/:id` should load conversation content
- `/settings` should load
- - if your backend does not expose settings schemas, the UI will show `SDK settings schema unavailable.` instead of crashing
+ - on secured backends, make sure `VITE_SESSION_API_KEY` matches the backend session key
+ - if your backend is too old to expose settings schemas, the UI will show an actionable `SDK settings schema unavailable.` message instead of crashing
### Mock mode
diff --git a/__tests__/api/agent-server-config.test.ts b/__tests__/api/agent-server-config.test.ts
new file mode 100644
index 0000000000..684573c17a
--- /dev/null
+++ b/__tests__/api/agent-server-config.test.ts
@@ -0,0 +1,42 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { getAgentServerBaseUrl } from "#/api/agent-server-config";
+
+const STORAGE_KEY = "openhands-agent-server-config";
+const ORIGINAL_LOCATION = window.location;
+
+function mockWindowLocation(url: string) {
+ Object.defineProperty(window, "location", {
+ configurable: true,
+ value: new URL(url),
+ });
+}
+
+afterEach(() => {
+ window.localStorage.clear();
+ Object.defineProperty(window, "location", {
+ configurable: true,
+ value: ORIGINAL_LOCATION,
+ });
+});
+
+describe("getAgentServerBaseUrl", () => {
+ it("uses the browser origin when a remote browser is pointed at localhost backend config", () => {
+ mockWindowLocation("https://work-1.example.dev/settings");
+ window.localStorage.setItem(
+ STORAGE_KEY,
+ JSON.stringify({ baseUrl: "http://127.0.0.1:8000" }),
+ );
+
+ expect(getAgentServerBaseUrl()).toBe("https://work-1.example.dev");
+ });
+
+ it("preserves a non-local backend URL from stored config", () => {
+ mockWindowLocation("https://work-1.example.dev/settings");
+ window.localStorage.setItem(
+ STORAGE_KEY,
+ JSON.stringify({ baseUrl: "https://agent.example.com" }),
+ );
+
+ expect(getAgentServerBaseUrl()).toBe("https://agent.example.com");
+ });
+});
diff --git a/__tests__/api/config-service.test.ts b/__tests__/api/config-service.test.ts
new file mode 100644
index 0000000000..7499833f89
--- /dev/null
+++ b/__tests__/api/config-service.test.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import ConfigService from "#/api/config-service/config-service.api";
+
+describe("ConfigService", () => {
+ it("derives providers from llm endpoints", async () => {
+ const page = await ConfigService.searchProviders({ limit: 10 });
+
+ expect(page.next_page_id).toBeNull();
+ expect(page.items.some((provider) => provider.name === "anthropic")).toBe(true);
+ expect(
+ page.items.find((provider) => provider.name === "anthropic")?.verified,
+ ).toBe(true);
+ });
+
+ it("derives provider models from llm endpoints", async () => {
+ const page = await ConfigService.searchModels({
+ provider__eq: "anthropic",
+ limit: 20,
+ });
+
+ expect(page.next_page_id).toBeNull();
+ expect(page.items.some((model) => model.name === "claude-opus-4-5-20251101")).toBe(
+ true,
+ );
+ expect(page.items.every((model) => model.provider === "anthropic")).toBe(true);
+ });
+});
diff --git a/artifacts/frontend-tour.gif b/artifacts/frontend-tour.gif
index 9526c50531..44a626e586 100644
Binary files a/artifacts/frontend-tour.gif and b/artifacts/frontend-tour.gif differ
diff --git a/src/api/agent-server-config.ts b/src/api/agent-server-config.ts
index da84fddeb8..6d3b2708d5 100644
--- a/src/api/agent-server-config.ts
+++ b/src/api/agent-server-config.ts
@@ -36,11 +36,46 @@ function normalizeBaseUrl(value?: string | null): string | null {
return `http://${trimmed}`;
}
+function shouldUseProxyOrigin(baseUrl: string): boolean {
+ if (typeof window === "undefined") {
+ return false;
+ }
+
+ try {
+ const configuredUrl = new URL(baseUrl);
+ const localHosts = new Set(["127.0.0.1", "localhost", "0.0.0.0"]);
+ const browserHostname = window.location.hostname;
+
+ return (
+ localHosts.has(configuredUrl.hostname) &&
+ !localHosts.has(browserHostname)
+ );
+ } catch {
+ return false;
+ }
+}
+
+function resolveAgentServerBaseUrl(baseUrl: string | null): string | null {
+ if (!baseUrl) {
+ return null;
+ }
+
+ if (shouldUseProxyOrigin(baseUrl)) {
+ return window.location.origin;
+ }
+
+ return baseUrl;
+}
+
export function getAgentServerBaseUrl(): string {
- const envUrl = normalizeBaseUrl(import.meta.env.VITE_BACKEND_BASE_URL);
+ const envUrl = resolveAgentServerBaseUrl(
+ normalizeBaseUrl(import.meta.env.VITE_BACKEND_BASE_URL),
+ );
if (envUrl) return envUrl;
- const storedUrl = normalizeBaseUrl(readStoredConfig().baseUrl);
+ const storedUrl = resolveAgentServerBaseUrl(
+ normalizeBaseUrl(readStoredConfig().baseUrl),
+ );
if (storedUrl) return storedUrl;
if (typeof window !== "undefined") {
diff --git a/src/api/config-service/config-service.api.ts b/src/api/config-service/config-service.api.ts
index 61d57be643..42ef44dea6 100644
--- a/src/api/config-service/config-service.api.ts
+++ b/src/api/config-service/config-service.api.ts
@@ -1,42 +1,117 @@
import { openHands } from "../open-hands-axios";
import type {
+ LLMModel,
LLMModelPage,
+ LLMProvider,
ProviderPage,
SearchModelsParams,
SearchProvidersParams,
} from "./config-service.types";
-function toSearchParams(
- params: SearchModelsParams | SearchProvidersParams,
-): string {
- const searchParams = new URLSearchParams();
- for (const [key, value] of Object.entries(params)) {
- if (value !== undefined && value !== null) {
- searchParams.append(key, String(value));
- }
+function filterByQuery<T extends { name: string }>(items: T[], query?: string): T[] {
+ if (!query) {
+ return items;
}
- return searchParams.toString();
+
+ const normalizedQuery = query.toLowerCase();
+ return items.filter((item) => item.name.toLowerCase().includes(normalizedQuery));
+}
+
+function filterByVerified<T extends { verified: boolean }>(
+ items: T[],
+ verified?: boolean,
+): T[] {
+ if (verified === undefined) {
+ return items;
+ }
+
+ return items.filter((item) => item.verified === verified);
+}
+
+function limitItems<T>(items: T[], limit?: number): T[] {
+ if (!limit || limit <= 0) {
+ return items;
+ }
+
+ return items.slice(0, limit);
}
class ConfigService {
static async searchModels(
params: SearchModelsParams = {},
): Promise<LLMModelPage> {
- const qs = toSearchParams(params);
- const { data } = await openHands.get<LLMModelPage>(
- `/api/v1/config/models/search?${qs}`,
+ const [modelsResponse, verifiedResponse] = await Promise.all([
+ openHands.get<{ models: string[] }>("/api/llm/models"),
+ openHands.get<{ models: Record<string, string[]> }>(
+ "/api/llm/models/verified",
+ ),
+ ]);
+
+ const provider = params.provider__eq ?? null;
+ const verifiedNames = new Set(
+ provider ? (verifiedResponse.data.models?.[provider] ?? []) : [],
);
- return data;
+ const verifiedItems: LLMModel[] = [...verifiedNames].map((name) => ({
+ provider,
+ name,
+ verified: true,
+ }));
+
+ const prefixedItems: LLMModel[] = provider
+ ? (modelsResponse.data.models ?? [])
+ .filter((model) => model.startsWith(`${provider}/`))
+ .map((model) => model.slice(provider.length + 1))
+ .filter((name) => name.length > 0 && !verifiedNames.has(name))
+ .map((name) => ({
+ provider,
+ name,
+ verified: false,
+ }))
+ : [];
+
+ const items = limitItems(
+ filterByVerified(
+ filterByQuery([...verifiedItems, ...prefixedItems], params.query),
+ params.verified__eq,
+ ),
+ params.limit,
+ );
+
+ return {
+ items,
+ next_page_id: null,
+ };
}
static async searchProviders(
params: SearchProvidersParams = {},
): Promise<ProviderPage> {
- const qs = toSearchParams(params);
- const { data } = await openHands.get<ProviderPage>(
- `/api/v1/config/providers/search?${qs}`,
+ const [providersResponse, verifiedResponse] = await Promise.all([
+ openHands.get<{ providers: string[] }>("/api/llm/providers"),
+ openHands.get<{ models: Record<string, string[]> }>(
+ "/api/llm/models/verified",
+ ),
+ ]);
+
+ const verifiedProviders = new Set(
+ Object.keys(verifiedResponse.data.models ?? {}),
);
- return data;
+ const providers: LLMProvider[] = (providersResponse.data.providers ?? []).map(
+ (name) => ({
+ name,
+ verified: verifiedProviders.has(name),
+ }),
+ );
+
+ const items = limitItems(
+ filterByVerified(filterByQuery(providers, params.query), params.verified__eq),
+ params.limit,
+ );
+
+ return {
+ items,
+ next_page_id: null,
+ };
}
}
diff --git a/src/components/features/settings/sdk-settings/sdk-section-page.tsx b/src/components/features/settings/sdk-settings/sdk-section-page.tsx
index 882667c26b..0d9584759d 100644
--- a/src/components/features/settings/sdk-settings/sdk-section-page.tsx
+++ b/src/components/features/settings/sdk-settings/sdk-section-page.tsx
@@ -78,6 +78,25 @@ const normalizeView = (
return "basic";
};
+const getSchemaUnavailableMessage = (
+ error: unknown,
+ fallbackMessage: string,
+): string => {
+ if (!(error instanceof AxiosError)) {
+ return fallbackMessage;
+ }
+
+ if (error.response?.status === 401) {
+ return `${fallbackMessage} This agent server requires X-Session-API-Key. Set VITE_SESSION_API_KEY in the frontend to the same value used by the backend SESSION_API_KEY or OH_SESSION_API_KEYS_0.`;
+ }
+
+ if (error.response?.status === 404) {
+ return `${fallbackMessage} This backend does not expose /api/settings/* schema endpoints. Upgrade to a recent openhands-agent-server release.`;
+ }
+
+ return fallbackMessage;
+};
+
export interface SdkSectionHeaderProps {
values: SettingsFormValues;
isDisabled: boolean;
@@ -141,14 +160,12 @@ export function SdkSectionPage({
const conversationSchemaQuery = useConversationSettingsSchema(
settings?.conversation_settings_schema,
);
- const schema =
+ const activeSchemaQuery =
settingsSource === "conversation_settings"
- ? conversationSchemaQuery.data
- : agentSchemaQuery.data;
- const isSchemaLoading =
- settingsSource === "conversation_settings"
- ? conversationSchemaQuery.isLoading
- : agentSchemaQuery.isLoading;
+ ? conversationSchemaQuery
+ : agentSchemaQuery;
+ const schema = activeSchemaQuery.data;
+ const isSchemaLoading = activeSchemaQuery.isLoading;
const { data: config } = useConfig();
const { data: me } = useMe();
const { hasPermission } = usePermission(me?.role ?? "member");
@@ -184,6 +201,14 @@ export function SdkSectionPage({
const showAdvanced =
forceShowAdvancedView || hasAdvancedSettings(filteredSchema);
const showAll = allowAllView && hasMinorSettings(filteredSchema);
+ const schemaUnavailableMessage = React.useMemo(
+ () =>
+ getSchemaUnavailableMessage(
+ activeSchemaQuery.error,
+ t(I18nKey.SETTINGS$SDK_SCHEMA_UNAVAILABLE),
+ ),
+ [activeSchemaQuery.error, t],
+ );
const initialValues = React.useMemo(() => {
if (!settings || !filteredSchema) return null;
@@ -305,7 +330,7 @@ export function SdkSectionPage({
if (!filteredSchema || filteredSchema.sections.length === 0) {
return (
<Typography.Paragraph className="text-tertiary-alt">
- {t(I18nKey.SETTINGS$SDK_SCHEMA_UNAVAILABLE)}
+ {schemaUnavailableMessage}
</Typography.Paragraph>
);
}
diff --git a/src/hooks/query/use-agent-settings-schema.ts b/src/hooks/query/use-agent-settings-schema.ts
index fd9136d382..2e79769024 100644
--- a/src/hooks/query/use-agent-settings-schema.ts
+++ b/src/hooks/query/use-agent-settings-schema.ts
@@ -10,7 +10,7 @@ const useSettingsSchema = (
) => {
const isOnIntermediatePage = useIsOnIntermediatePage();
const { data: userIsAuthenticated } = useIsAuthed();
- const { data, isLoading, isFetching } = useQuery({
+ const { data, error, isLoading, isFetching } = useQuery({
queryKey: ["settings-schema", type],
queryFn:
type === "conversation"
@@ -29,6 +29,7 @@ const useSettingsSchema = (
if (fallbackSchema) {
return {
data: fallbackSchema,
+ error: null,
isLoading: false,
isFetching: false,
};
@@ -36,6 +37,7 @@ const useSettingsSchema = (
return {
data,
+ error,
isLoading,
isFetching,
};