Skip to content

🙌 OpenHands: AI-Driven Development

fix(frontend): make Add Workspace modal dynamic and host-aware (#306)

Hiep Le2212906fd578
diff --git a/README.md b/README.md
index 57786ee37d..e8782f8e52 100644
--- a/README.md
+++ b/README.md
@@ -25,12 +25,15 @@ If you have questions or feedback, please open a GitHub issue or join the [#proj
### With Docker (recommended)
**Prerequisites**:
+
- Node.js 22.12.x or later
- `npm`
- Docker
Set `$PROJECT_PATH` to the directory on your machine where your projects live (e.g. `/path/to/your/projects`). The agent server will mount this directory so the agent can read and edit your code.
+By default the container is kept isolated from your host home — only `~/.openhands`, `~/.claude`, `~/.codex`, and `~/.ssh` are mounted individually (and only if they exist). If you want the **Add Workspace** dialog to browse your real host filesystem, set `OH_MOUNT_HOST_HOME=1` before `npm run dev:docker` to bind-mount your entire host home onto `/home/openhands` in the container. The Add Workspace modal also shows this hint inline when it detects the mount is off.
+
```sh
export PROJECT_PATH=/path/to/your/projects
git clone https://github.com/OpenHands/agent-canvas.git
@@ -51,6 +54,7 @@ especially with respect to security hardening. Notably, you can run the backend
them from the same Agent Canvas frontend!
**Prerequisites**:
+
- Node.js 22.12.x or later
- `npm`
- `uv` (for running the agent server via `uvx`)
diff --git a/__tests__/components/features/home/workspace-selection-form.test.tsx b/__tests__/components/features/home/workspace-selection-form.test.tsx
index 0b108c043d..738139c765 100644
--- a/__tests__/components/features/home/workspace-selection-form.test.tsx
+++ b/__tests__/components/features/home/workspace-selection-form.test.tsx
@@ -96,7 +96,11 @@ describe("WorkspaceSelectionForm", () => {
});
it("Add Workspace adds only the chosen folder (not its subfolders) and dedupes on repeat", async () => {
- vi.spyOn(FilesService, "getHome").mockResolvedValue({ home: "/Users/me" });
+ vi.spyOn(FilesService, "getHome").mockResolvedValue({
+ home: "/Users/me",
+ favorites: [],
+ locations: [{ label: "/", path: "/" }],
+ });
const searchSpy = vi
.spyOn(FilesService, "searchSubdirs")
.mockImplementation(async (path: string) => {
@@ -258,9 +262,10 @@ describe("WorkspaceSelectionForm", () => {
.spyOn(FilesService, "searchSubdirs")
.mockResolvedValue({ items: [], next_page_id: null });
- renderForm([], [
- { id: "custom-projects", name: "My Projects", path: "/projects" },
- ]);
+ renderForm(
+ [],
+ [{ id: "custom-projects", name: "My Projects", path: "/projects" }],
+ );
await waitFor(() => expect(searchSpy).toHaveBeenCalledTimes(1));
expect(searchSpy).toHaveBeenCalledWith("/projects");
@@ -330,7 +335,11 @@ describe("WorkspaceSelectionForm", () => {
});
it("Add all subdirectories saves a workspace parent and lists its children dynamically", async () => {
- vi.spyOn(FilesService, "getHome").mockResolvedValue({ home: "/Users/me" });
+ vi.spyOn(FilesService, "getHome").mockResolvedValue({
+ home: "/Users/me",
+ favorites: [],
+ locations: [{ label: "/", path: "/" }],
+ });
const searchSpy = vi
.spyOn(FilesService, "searchSubdirs")
.mockImplementation(async (path: string) => {
@@ -457,4 +466,45 @@ describe("WorkspaceSelectionForm", () => {
within(refreshedDropdown).queryByText("repoB"),
).not.toBeInTheDocument();
});
+
+ it("Add Workspace sidebar renders backend-provided favorites dynamically and navigates into them on click", async () => {
+ // Arrange: backend reports a home with a custom favorite that did NOT
+ // exist in the old hardcoded list (Documents / Desktop / Downloads).
+ // This is the regression guard for the original 404-on-navigate bug.
+ vi.spyOn(FilesService, "getHome").mockResolvedValue({
+ home: "/Users/me",
+ favorites: [{ label: "projects", path: "/Users/me/projects" }],
+ locations: [{ label: "/", path: "/" }],
+ });
+ const searchSpy = vi
+ .spyOn(FilesService, "searchSubdirs")
+ .mockImplementation(async (path: string) => {
+ if (path === "/Users/me/projects") {
+ return {
+ items: [{ name: "repo1", path: "/Users/me/projects/repo1" }],
+ next_page_id: null,
+ };
+ }
+ return { items: [], next_page_id: null };
+ });
+
+ renderForm();
+ const user = userEvent.setup();
+
+ // Act: open the modal and click the dynamic favorite.
+ await user.click(screen.getByTestId("workspace-dropdown"));
+ await user.click(await screen.findByTestId("add-workspaces-button"));
+ await screen.findByTestId("folder-browser-modal");
+ await user.click(
+ await screen.findByTestId("folder-browser-sidebar-projects"),
+ );
+
+ // Assert: the dynamic favorite drove the navigation, and the previously
+ // hardcoded names are no longer present in the sidebar.
+ await screen.findByTestId("folder-browser-entry-repo1");
+ expect(searchSpy).toHaveBeenCalledWith("/Users/me/projects");
+ expect(
+ screen.queryByTestId("folder-browser-sidebar-documents"),
+ ).not.toBeInTheDocument();
+ });
});
diff --git a/scripts/dev-docker.mjs b/scripts/dev-docker.mjs
index 710516cd33..3984608b52 100644
--- a/scripts/dev-docker.mjs
+++ b/scripts/dev-docker.mjs
@@ -18,6 +18,13 @@
* - OH_AGENT_SERVER_GIT_REF: Git ref (branch/tag/SHA) of the agent-server
* to use. Translates to the docker tag `${ref}-python`, e.g.
* `main` -> `ghcr.io/openhands/agent-server:main-python`.
+ * - OH_AGENT_SERVER_LOCAL_PATH: Absolute host path to a software-agent-sdk
+ * checkout. When set, mounts the checkout at /agent-server-src inside the
+ * container and reinstalls the four workspace packages
+ * (openhands-{sdk,tools,workspace,agent-server}) as editable installs on
+ * top of the image's pre-built venv before starting the server. Source
+ * edits on the host are reflected in the running container on module
+ * reload / process restart, matching the non-Docker dev loop.
*
* Optional credential mounts (only mounted when the host path exists):
* - ~/.openhands -> /home/openhands/.openhands (persistence)
@@ -25,6 +32,14 @@
* - ~/.codex -> /home/openhands/.codex (Codex credentials)
* - ~/.ssh -> /home/openhands/.ssh (git/ssh access)
*
+ * Optional host home mount (opt-in):
+ * Set `OH_MOUNT_HOST_HOME=1` to bind-mount your entire host home onto
+ * the container user's home at `/home/openhands`. This lets the
+ * "Add Workspace" file browser navigate your real host filesystem
+ * (and credentials/persistence dirs above are picked up automatically
+ * as subpaths). Off by default so the container stays isolated from
+ * the host home unless you opt in.
+ *
* Usage:
* PROJECT_PATH=/path/to/your/projects npm run dev:docker
* OH_AGENT_SERVER_GIT_REF=main PROJECT_PATH=... npm run dev:docker
@@ -46,6 +61,10 @@ import {
main,
spawnService,
} from "./dev-with-automation.mjs";
+import { validateLocalAgentServerPath } from "./dev-safe.mjs";
+
+// Path inside the container where OH_AGENT_SERVER_LOCAL_PATH is bind-mounted.
+const CONTAINER_LOCAL_SDK_DIR = "/agent-server-src";
// Docker image for the agent-server.
const AGENT_SERVER_REPO = "ghcr.io/openhands/agent-server";
@@ -85,9 +104,7 @@ function suggestDockerless() {
"If you'd rather not use Docker, you can run the agent-server directly with:",
);
logError(" npm run dev:dangerously-dockerless");
- logError(
- "Note: this runs the agent with full access to your filesystem.",
- );
+ logError("Note: this runs the agent with full access to your filesystem.");
}
/**
@@ -112,7 +129,9 @@ function checkDockerPrereqs(config) {
timeout: 10_000,
});
if (info.status !== 0) {
- logError("docker is installed but the daemon does not appear to be running.");
+ logError(
+ "docker is installed but the daemon does not appear to be running.",
+ );
const stderr = info.stderr ? info.stderr.toString().trim() : "";
if (stderr) {
logError(` ${stderr.split("\n")[0]}`);
@@ -134,11 +153,26 @@ function checkDockerPrereqs(config) {
function startAgentServerDocker(config) {
const image = resolveAgentServerImage();
+ const localSdkPath = process.env.OH_AGENT_SERVER_LOCAL_PATH;
+
+ // Validate up-front so we fail fast before touching docker if the user
+ // pointed at a missing / incomplete checkout.
+ if (localSdkPath) {
+ validateLocalAgentServerPath(localSdkPath);
+ }
+
logService(
"agent-server",
`Starting in Docker on port ${config.agentServerPort} (image: ${image})...`,
c.blue,
);
+ if (localSdkPath) {
+ logService(
+ "agent-server",
+ `Using local SDK source: ${localSdkPath} (mounted at ${CONTAINER_LOCAL_SDK_DIR})`,
+ c.blue,
+ );
+ }
// Best-effort cleanup of any leftover container from a previous run.
spawnSync("docker", ["rm", "-f", CONTAINER_NAME], { stdio: "ignore" });
@@ -154,17 +188,32 @@ function startAgentServerDocker(config) {
`${process.env.PROJECT_PATH}:/projects`,
];
- // Optional credential / state mounts. Only mount when the host path
- // exists so docker doesn't auto-create empty directories on the host.
- const optionalMounts = [
- [join(home, ".openhands"), "/home/openhands/.openhands"],
- [join(home, ".claude"), "/home/openhands/.claude"],
- [join(home, ".codex"), "/home/openhands/.codex"],
- [join(home, ".ssh"), "/home/openhands/.ssh"],
- ];
- for (const [src, dest] of optionalMounts) {
- if (existsSync(src)) {
- dockerArgs.push("-v", `${src}:${dest}`);
+ // Bind-mount the local software-agent-sdk checkout if requested. Mounted
+ // rw so editable installs can write their .dist-info into each package
+ // (matches the side effect of the non-Docker uvx --with-editable path).
+ if (localSdkPath) {
+ dockerArgs.push("-v", `${localSdkPath}:${CONTAINER_LOCAL_SDK_DIR}`);
+ }
+
+ // Mount credentials / state individually by default so the container
+ // stays isolated from the host home. Opt in to bind-mounting the
+ // entire host home with OH_MOUNT_HOST_HOME=1 — useful when you want
+ // the Add Workspace file browser to navigate your real host
+ // filesystem (those credential subpaths come along automatically as
+ // part of the same mount).
+ if (process.env.OH_MOUNT_HOST_HOME === "1") {
+ dockerArgs.push("-v", `${home}:/home/openhands`);
+ } else {
+ const optionalMounts = [
+ [join(home, ".openhands"), "/home/openhands/.openhands"],
+ [join(home, ".claude"), "/home/openhands/.claude"],
+ [join(home, ".codex"), "/home/openhands/.codex"],
+ [join(home, ".ssh"), "/home/openhands/.ssh"],
+ ];
+ for (const [src, dest] of optionalMounts) {
+ if (existsSync(src)) {
+ dockerArgs.push("-v", `${src}:${dest}`);
+ }
}
}
@@ -179,8 +228,7 @@ function startAgentServerDocker(config) {
OH_CONVERSATIONS_PATH:
"/home/openhands/.openhands/agent-canvas/conversations",
OH_PERSISTENCE_DIR: "/home/openhands/.openhands",
- OH_BASH_EVENTS_DIR:
- "/home/openhands/.openhands/agent-canvas/bash_events",
+ OH_BASH_EVENTS_DIR: "/home/openhands/.openhands/agent-canvas/bash_events",
TMUX_TMPDIR: "/home/openhands/.openhands/agent-canvas/tmux",
OH_SECRET_KEY: process.env.OH_SECRET_KEY || DEFAULT_SECRET_KEY,
// Required so the secret-seeding PUT /api/settings/secrets call from
@@ -191,8 +239,32 @@ function startAgentServerDocker(config) {
dockerArgs.push("-e", `${k}=${v}`);
}
+ // When using a local SDK checkout, override the image's entrypoint to
+ // reinstall the four workspace packages as editable on top of the baked-in
+ // venv, then exec the server. Reusing the image's venv avoids
+ // redownloading transitive deps; editable installs make host-side edits
+ // visible on the next module load (or container restart).
+ if (localSdkPath) {
+ dockerArgs.push("--entrypoint", "/bin/sh");
+ }
+
dockerArgs.push(image);
+ if (localSdkPath) {
+ const installCmd = [
+ "uv pip install",
+ "--python /agent-server/.venv/bin/python",
+ "--reinstall",
+ `-e ${CONTAINER_LOCAL_SDK_DIR}/openhands-sdk`,
+ `-e ${CONTAINER_LOCAL_SDK_DIR}/openhands-tools`,
+ `-e ${CONTAINER_LOCAL_SDK_DIR}/openhands-workspace`,
+ `-e ${CONTAINER_LOCAL_SDK_DIR}/openhands-agent-server`,
+ ].join(" ");
+ const runCmd =
+ "exec /agent-server/.venv/bin/python -m openhands.agent_server --host 0.0.0.0 --port 8000";
+ dockerArgs.push("-c", `${installCmd} && ${runCmd}`);
+ }
+
spawnService("agent-server", "docker", dockerArgs, {
color: c.blue,
});
@@ -218,6 +290,7 @@ if (isMainModule) {
export {
AGENT_SERVER_REPO,
+ CONTAINER_LOCAL_SDK_DIR,
CONTAINER_NAME,
CONTAINER_WORKSPACES_DIR,
DEFAULT_AGENT_SERVER_TAG,
diff --git a/src/api/files-service/files-service.api.ts b/src/api/files-service/files-service.api.ts
index 97499e2385..4de54e9284 100644
--- a/src/api/files-service/files-service.api.ts
+++ b/src/api/files-service/files-service.api.ts
@@ -10,8 +10,15 @@ export interface SubdirectoryPage {
next_page_id: string | null;
}
+export interface FileBrowserEntry {
+ label: string;
+ path: string;
+}
+
export interface HomeResponse {
home: string;
+ favorites: FileBrowserEntry[];
+ locations: FileBrowserEntry[];
}
export interface SearchSubdirsOptions {
diff --git a/src/components/features/home/workspace-dropdown/folder-browser-modal.tsx b/src/components/features/home/workspace-dropdown/folder-browser-modal.tsx
index 71824cea22..b3e317ad12 100644
--- a/src/components/features/home/workspace-dropdown/folder-browser-modal.tsx
+++ b/src/components/features/home/workspace-dropdown/folder-browser-modal.tsx
@@ -9,6 +9,7 @@ import {
useHomeDirectory,
useSearchSubdirs,
} from "#/hooks/query/use-search-subdirs";
+import { useActiveBackend } from "#/contexts/active-backend-context";
import { cn } from "#/utils/utils";
import FolderIcon from "#/icons/folder.svg?react";
import ChevronLeft from "#/icons/chevron-left-small.svg?react";
@@ -79,25 +80,6 @@ function getParentPath(path: string): string | null {
return trimmed.slice(0, idx);
}
-function buildSidebar(home: string | null): {
- favorites: SidebarEntry[];
- locations: SidebarEntry[];
-} {
- if (!home) {
- return { favorites: [], locations: [{ label: "/", path: "/" }] };
- }
- const trimmed = home.replace(/\/+$/, "");
- return {
- favorites: [
- { label: "Home", path: trimmed },
- { label: "Desktop", path: `${trimmed}/Desktop` },
- { label: "Documents", path: `${trimmed}/Documents` },
- { label: "Downloads", path: `${trimmed}/Downloads` },
- ],
- locations: [{ label: "/", path: "/" }],
- };
-}
-
export function FolderBrowserModal({
isOpen,
onClose,
@@ -106,6 +88,7 @@ export function FolderBrowserModal({
}: FolderBrowserModalProps) {
const { t } = useTranslation("openhands");
const [currentPath, setCurrentPath] = useState<string | null>(null);
+ const active = useActiveBackend();
const { data: homeData } = useHomeDirectory();
@@ -119,6 +102,12 @@ export function FolderBrowserModal({
}
}, [isOpen, homeData?.home, currentPath]);
+ // A backend switch invalidates the previous path — clear it so the
+ // open/close effect can re-seed from the new backend's homeData.home.
+ useEffect(() => {
+ setCurrentPath(null);
+ }, [active.backend.id, active.orgId]);
+
const {
data: listing,
isLoading,
@@ -126,16 +115,34 @@ export function FolderBrowserModal({
error,
} = useSearchSubdirs(isOpen ? currentPath : null);
- const sidebar = useMemo(
- () => buildSidebar(homeData?.home ?? null),
- [homeData?.home],
- );
+ const favorites: SidebarEntry[] = useMemo(() => {
+ if (!homeData?.home) return [];
+ const trimmed = homeData.home.replace(/[\\/]+$/, "") || homeData.home;
+ return [{ label: "Home", path: trimmed }, ...(homeData.favorites ?? [])];
+ }, [homeData]);
+
+ const locations: SidebarEntry[] = homeData?.locations ?? [];
if (!isOpen) return null;
const subdirs = listing?.items ?? [];
const parent = currentPath ? getParentPath(currentPath) : null;
+ // Signal that we're inside the dev:docker container without the host
+ // home mounted: the agent server reports `/home/openhands` as home and
+ // returns no favorites (the only contents are hidden credential dirs).
+ // In that case there's nothing useful for the user to browse, so we
+ // surface the OH_MOUNT_HOST_HOME=1 opt-in instead of the generic empty
+ // state. Off in production / non-Docker dev because favorites are
+ // populated there.
+ const showHostHomeHint =
+ homeData?.home === "/home/openhands" &&
+ (homeData?.favorites?.length ?? 0) === 0 &&
+ currentPath === homeData?.home &&
+ !isLoading &&
+ !isError &&
+ subdirs.length === 0;
+
const getBasename = (path: string): string => {
const trimmed = path.replace(/\/+$/, "");
if (!trimmed) return "/";
@@ -194,13 +201,13 @@ export function FolderBrowserModal({
>
<SidebarSection
label={t(I18nKey.HOME$FAVORITES)}
- entries={sidebar.favorites}
+ entries={favorites}
currentPath={currentPath}
onPick={setCurrentPath}
/>
<SidebarSection
label={t(I18nKey.HOME$LOCATIONS)}
- entries={sidebar.locations}
+ entries={locations}
currentPath={currentPath}
onPick={setCurrentPath}
/>
@@ -253,8 +260,17 @@ export function FolderBrowserModal({
</li>
)}
{!isLoading && !isError && subdirs.length === 0 && (
- <li className="px-4 py-2 text-sm text-[#B7BDC2]">
- {t(I18nKey.HOME$NO_WORKSPACES)}
+ <li
+ className="px-4 py-2 text-sm text-[#B7BDC2]"
+ data-testid={
+ showHostHomeHint
+ ? "folder-browser-host-home-hint"
+ : "folder-browser-empty"
+ }
+ >
+ {showHostHomeHint
+ ? t(I18nKey.HOME$HOST_HOME_NOT_MOUNTED_HINT)
+ : t(I18nKey.HOME$NO_WORKSPACES)}
</li>
)}
{subdirs.map((entry) => (
diff --git a/src/hooks/query/use-search-subdirs.ts b/src/hooks/query/use-search-subdirs.ts
index 52a4119301..21ad08add1 100644
--- a/src/hooks/query/use-search-subdirs.ts
+++ b/src/hooks/query/use-search-subdirs.ts
@@ -1,20 +1,25 @@
import { useQuery } from "@tanstack/react-query";
import FilesService from "#/api/files-service/files-service.api";
+import { useActiveBackend } from "#/contexts/active-backend-context";
-export const useSearchSubdirs = (path: string | null) =>
- useQuery({
- queryKey: ["file", "search_subdirs", path],
+export const useSearchSubdirs = (path: string | null) => {
+ const active = useActiveBackend();
+ return useQuery({
+ queryKey: ["file", "search_subdirs", path, active.backend.id, active.orgId],
queryFn: () => FilesService.searchSubdirs(path as string),
enabled: !!path,
retry: false,
meta: { disableToast: true },
});
+};
-export const useHomeDirectory = () =>
- useQuery({
- queryKey: ["file", "home"],
+export const useHomeDirectory = () => {
+ const active = useActiveBackend();
+ return useQuery({
+ queryKey: ["file", "home", active.backend.id, active.orgId],
queryFn: () => FilesService.getHome(),
retry: false,
meta: { disableToast: true },
staleTime: Infinity,
});
+};
diff --git a/src/i18n/translation.json b/src/i18n/translation.json
index 163c4d971d..ad5c5e1bc6 100644
--- a/src/i18n/translation.json
+++ b/src/i18n/translation.json
@@ -16506,6 +16506,23 @@
"uk": "Робочих областей ще немає",
"ca": "Encara no hi ha espais de treball"
},
+ "HOME$HOST_HOME_NOT_MOUNTED_HINT": {
+ "en": "Your host filesystem isn't visible to the agent server. Set OH_MOUNT_HOST_HOME=1 before npm run dev:docker to browse it from here.",
+ "ja": "ホストのファイルシステムはエージェントサーバーから見えません。ここから参照するには、npm run dev:docker の前に OH_MOUNT_HOST_HOME=1 を設定してください。",
+ "zh-CN": "代理服务器看不到您的宿主机文件系统。请在运行 npm run dev:docker 之前设置 OH_MOUNT_HOST_HOME=1,即可在此浏览。",
+ "zh-TW": "代理伺服器看不到您的主機檔案系統。請在執行 npm run dev:docker 之前設定 OH_MOUNT_HOST_HOME=1,即可在此瀏覽。",
+ "ko-KR": "에이전트 서버에서 호스트 파일 시스템이 보이지 않습니다. 여기서 탐색하려면 npm run dev:docker 전에 OH_MOUNT_HOST_HOME=1을 설정하세요.",
+ "no": "Vertens filsystem er ikke synlig for agent-serveren. Sett OH_MOUNT_HOST_HOME=1 før npm run dev:docker for å bla gjennom det herfra.",
+ "it": "Il filesystem dell'host non è visibile al server dell'agente. Imposta OH_MOUNT_HOST_HOME=1 prima di npm run dev:docker per esplorarlo da qui.",
+ "pt": "O sistema de arquivos do host não está visível para o servidor do agente. Defina OH_MOUNT_HOST_HOME=1 antes de npm run dev:docker para navegá-lo daqui.",
+ "es": "El sistema de archivos del anfitrión no es visible para el servidor del agente. Establece OH_MOUNT_HOST_HOME=1 antes de npm run dev:docker para explorarlo desde aquí.",
+ "ar": "نظام ملفات المضيف غير مرئي لخادم الوكيل. اضبط OH_MOUNT_HOST_HOME=1 قبل npm run dev:docker لتصفحه من هنا.",
+ "fr": "Le système de fichiers de l'hôte n'est pas visible par le serveur de l'agent. Définissez OH_MOUNT_HOST_HOME=1 avant npm run dev:docker pour le parcourir d'ici.",
+ "tr": "Ana makine dosya sistemi ajan sunucusu tarafından görülmüyor. Buradan göz atmak için npm run dev:docker öncesinde OH_MOUNT_HOST_HOME=1 ayarlayın.",
+ "de": "Das Host-Dateisystem ist für den Agenten-Server nicht sichtbar. Setze OH_MOUNT_HOST_HOME=1 vor npm run dev:docker, um es hier zu durchsuchen.",
+ "uk": "Файлова система хоста не видима для сервера агента. Встановіть OH_MOUNT_HOST_HOME=1 перед npm run dev:docker, щоб переглядати її звідси.",
+ "ca": "El sistema de fitxers de l'amfitrió no és visible per al servidor de l'agent. Establiu OH_MOUNT_HOST_HOME=1 abans de npm run dev:docker per navegar-hi des d'aquí."
+ },
"HOME$NO_WORKSPACE_OPTION": {
"en": "No workspace",
"ja": "ワークスペースなし",