π OpenHands: AI-Driven Development
Rename PROJECT_PATH to PROJECTS_PATH (#521)
Engel Nyst5c42bd349287
diff --git a/AGENTS.md b/AGENTS.mdindex b75ef69bd7..f899673b88 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -318,7 +318,7 @@ return new ConversationClient(getAgentServerClientOptions()).someMethod(...);- `OH_SECRET_KEY` β secret key for settings encryption; uses a static default for local dev since it's needed for reading persisted encrypted values across restarts- `SESSION_API_KEY` / `OH_SESSION_API_KEYS_0` / `VITE_SESSION_API_KEY` β session API key for agent-server authentication; auto-generated using `crypto.randomBytes(32)` if not set, passed to both agent-server (`OH_SESSION_API_KEYS_0`) and frontend (`VITE_SESSION_API_KEY`)- Default: released PyPI version `1.22.1` for agent-server SDK libraries-- `scripts/dev-docker.mjs` runs the agent-server inside a Docker container instead of via `uvx`, and serves a static frontend build by default for stable user/tunnel access. Use `npm run dev:docker:dynamic` or `node scripts/dev-docker.mjs --dynamic` for the Vite dev server. The default image uses versioned release tags:+- `scripts/dev-docker.mjs` runs the agent-server inside a Docker container instead of via `uvx`, and serves a static frontend build by default for stable user/tunnel access. The required host-projects env var is `PROJECTS_PATH` and it is mounted into the container at `/projects`. Use `npm run dev:docker:dynamic` or `node scripts/dev-docker.mjs --dynamic` for the Vite dev server. The default image uses versioned release tags:- `DEFAULT_AGENT_SERVER_TAG` β uses format `{version}-python` (e.g., `1.22.1-python`) for reproducibility. Note: the SDK build script strips the "v" prefix from semver release tags.- Should stay in sync with `DEFAULT_AGENT_SERVER_VERSION` in `dev-safe.mjs` for consistency between Docker and non-Docker dev modes- `OH_AGENT_SERVER_GIT_REF` β override to use a git ref-based tag (e.g., `main` β `main-python`, `abc1234` β `abc1234-python`)diff --git a/README.md b/README.mdindex e7bf821edc..0d7bc46773 100644--- a/README.md+++ b/README.md@@ -32,12 +32,12 @@ If you have questions or feedback, please open a GitHub issue or join the [#proj- `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.+Set `$PROJECTS_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 runs as your host UID/GID so files written to bind mounts remain writable from your host account. The container is still kept isolated from your host home: its `/home/openhands` is a temporary writable home, and only `~/.openhands`, `~/.claude`, `~/.codex`, and `~/.ssh` are mounted individually under it (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. Watch the video on how to run this on [Mac](https://www.youtube.com/watch?v=BenkkQmmFCg) or [Windows](https://www.youtube.com/watch?v=WAxf_RRIrB8).```sh-export PROJECT_PATH=/path/to/your/projects+export PROJECTS_PATH=/path/to/your/projectsgit clone https://github.com/OpenHands/agent-canvas.gitcd agent-canvasnpm install@@ -49,7 +49,7 @@ This serves a static production build of the frontend behind the local ingress pWindows PowerShell exception: if `npm run dev:docker` starts the backend but `localhost:8000` shows Bad Gateway, start the same stack directly with Node instead. Replace the path below with your projects folder, and do not include any prompt characters or a trailing `>` in the value.```powershell-$env:PROJECT_PATH = "/path/to/your/projects"+$env:PROJECTS_PATH = "/path/to/your/projects"git clone https://github.com/OpenHands/agent-canvas.gitcd agent-canvasnpm installdiff --git a/__tests__/bin/agent-canvas.test.ts b/__tests__/bin/agent-canvas.test.tsnew file mode 100644index 0000000000..4f0cf71e7d--- /dev/null+++ b/__tests__/bin/agent-canvas.test.ts@@ -0,0 +1,35 @@+// @vitest-environment node+import { spawn } from "node:child_process";+import { once } from "node:events";+import { dirname, resolve } from "node:path";+import { fileURLToPath } from "node:url";++import { describe, expect, it } from "vitest";++const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");++describe("agent-canvas CLI", () => {+ it("shows PROJECTS_PATH in --help output", async () => {+ const child = spawn(process.execPath, ["bin/agent-canvas.mjs", "--help"], {+ cwd: repoRoot,+ stdio: ["ignore", "pipe", "pipe"],+ });++ let stdout = "";+ let stderr = "";++ child.stdout.on("data", (chunk) => {+ stdout += chunk.toString();+ });+ child.stderr.on("data", (chunk) => {+ stderr += chunk.toString();+ });++ const [code] = await once(child, "exit");++ expect(code).toBe(0);+ expect(stderr).toBe("");+ expect(stdout).toContain("PROJECTS_PATH");+ expect(stdout).not.toContain("PROJECT_PATH=/path/to/projects");+ });+});diff --git a/__tests__/scripts/dev-docker.test.ts b/__tests__/scripts/dev-docker.test.tsindex 04bffcdabe..94e4bf7d0b 100644--- a/__tests__/scripts/dev-docker.test.ts+++ b/__tests__/scripts/dev-docker.test.ts@@ -14,6 +14,7 @@ import {getDockerHomeTmpfsArgs,getDockerUserArgs,getHostDockerUserSpec,+ getProjectsPathDockerArgs,isDockerPermissionDenied,} from "../../scripts/dev-docker.mjs";@@ -59,6 +60,20 @@ describe("docker host user", () => {});});+describe("getProjectsPathDockerArgs", () => {+ it("uses PROJECTS_PATH for the /projects bind mount", () => {+ expect(+ getProjectsPathDockerArgs({ PROJECTS_PATH: "/host/projects" }),+ ).toEqual(["-v", "/host/projects:/projects"]);+ });++ it("does not read the old PROJECT_PATH name", () => {+ expect(getProjectsPathDockerArgs({ PROJECT_PATH: "/host/projects" })).toEqual(+ [],+ );+ });+});+describe("isDockerPermissionDenied", () => {it("detects Linux docker socket permission failures", () => {expect(diff --git a/bin/agent-canvas.mjs b/bin/agent-canvas.mjsindex 686ff15b33..12cd122f40 100755--- a/bin/agent-canvas.mjs+++ b/bin/agent-canvas.mjs@@ -32,14 +32,14 @@ USAGE:npx @openhands/agent-canvas [options]REQUIRED:- PROJECT_PATH Path to your projects directory (mounted into container)+ PROJECTS_PATH Path to your projects directory (mounted into container)OPTIONS:-p, --port <port> Ingress port (default: 8000)-h, --help Show this help messageENVIRONMENT VARIABLES:- PROJECT_PATH Required: path to your projects directory+ PROJECTS_PATH Required: path to your projects directoryOH_SECRET_KEY Secret key for encrypting settingsOH_AGENT_SERVER_GIT_REF Git ref for agent-server Docker image tagOH_AGENT_SERVER_LOCAL_PATH Path to local SDK checkout (for development)@@ -49,14 +49,14 @@ Note: LLM settings are configured through the web UI settings page,not environment variables.EXAMPLES:- # Start full stack (requires PROJECT_PATH)- PROJECT_PATH=/path/to/projects npx @openhands/agent-canvas+ # Start full stack (requires PROJECTS_PATH)+ PROJECTS_PATH=/path/to/projects npx @openhands/agent-canvas# Use a specific port- PROJECT_PATH=/path/to/projects npx @openhands/agent-canvas --port 3000+ PROJECTS_PATH=/path/to/projects npx @openhands/agent-canvas --port 3000# Use local SDK checkout for development- PROJECT_PATH=/path/to/projects OH_AGENT_SERVER_LOCAL_PATH=/path/to/sdk npx @openhands/agent-canvas+ PROJECTS_PATH=/path/to/projects OH_AGENT_SERVER_LOCAL_PATH=/path/to/sdk npx @openhands/agent-canvasFor more options, see: node scripts/dev-docker.mjs --help`);diff --git a/scripts/dev-docker.mjs b/scripts/dev-docker.mjsindex d2a5a14969..7a3aa1be43 100644--- a/scripts/dev-docker.mjs+++ b/scripts/dev-docker.mjs@@ -11,7 +11,7 @@* and the secret-seeding step can reach it via http://localhost:18000.** Required environment variables:- * - PROJECT_PATH: Absolute host path to your projects. Mounted into the+ * - PROJECTS_PATH: Absolute host path to your projects. Mounted into the* container at /projects so the agent can read/edit your code. The* frontend always treats /projects as a "workspace parent", so the* dropdown lists its immediate subdirectories as workspaces.@@ -43,9 +43,9 @@* the host home unless you opt in.** Usage:- * PROJECT_PATH=/path/to/your/projects npm run dev:docker- * PROJECT_PATH=/path/to/your/projects npm run dev:docker -- --dynamic- * OH_AGENT_SERVER_GIT_REF=main PROJECT_PATH=... npm run dev:docker+ * PROJECTS_PATH=/path/to/your/projects npm run dev:docker+ * PROJECTS_PATH=/path/to/your/projects npm run dev:docker -- --dynamic+ * OH_AGENT_SERVER_GIT_REF=main PROJECTS_PATH=... npm run dev:docker*/import { spawnSync } from "node:child_process";@@ -213,6 +213,10 @@ function getDockerHomeTmpfsArgs(userSpec = getHostDockerUserSpec()) {* installed, which is not enough -- on macOS / Windows the daemon may be* stopped, and on Linux the user may not have permissions to talk to it.*/+function getProjectsPathDockerArgs(env = process.env) {+ return env.PROJECTS_PATH ? ["-v", `${env.PROJECTS_PATH}:/projects`] : [];+}+function checkDockerPrereqs(config) {if (!commandExists("docker")) {logError("docker is required for dev:docker but was not found on PATH.");@@ -236,13 +240,13 @@ function checkDockerPrereqs(config) {}logSuccess("docker daemon is running");- if (!process.env.PROJECT_PATH) {- logError("PROJECT_PATH is required for dev:docker.");+ if (!process.env.PROJECTS_PATH) {+ logError("PROJECTS_PATH is required for dev:docker.");logError("Set it to the directory containing your projects, e.g.:");- logError(" export PROJECT_PATH=/path/to/your/projects");+ logError(" export PROJECTS_PATH=/path/to/your/projects");process.exit(1);}- logSuccess(`PROJECT_PATH=${process.env.PROJECT_PATH}`);+ logSuccess(`PROJECTS_PATH=${process.env.PROJECTS_PATH}`);}function startAgentServerDocker(config) {@@ -278,7 +282,7 @@ function startAgentServerDocker(config) {const userSpec = getHostDockerUserSpec();const dockerArgs = ["run", "--rm", "--name", CONTAINER_NAME, "--init"];dockerArgs.push(...getDockerUserArgs(userSpec));- dockerArgs.push("-v", `${process.env.PROJECT_PATH}:/projects`);+ dockerArgs.push(...getProjectsPathDockerArgs());// Read-only mount of the Agent-Canvas tools directory. Coupled with// OH_EXTRA_PYTHON_PATH below so the agent-server can import// canvas_ui_tool when the conversation request lists it under@@ -413,6 +417,7 @@ export {getDockerHomeTmpfsArgs,getDockerUserArgs,getHostDockerUserSpec,+ getProjectsPathDockerArgs,isDockerPermissionDenied,resolveAgentServerImage,startAgentServerDocker,diff --git a/src/hooks/query/use-resolved-workspaces.ts b/src/hooks/query/use-resolved-workspaces.tsindex 19730cacb5..c5e14ffe40 100644--- a/src/hooks/query/use-resolved-workspaces.ts+++ b/src/hooks/query/use-resolved-workspaces.ts@@ -14,7 +14,7 @@ interface UseResolvedWorkspacesResult {/*** Implicit workspace parents that are always considered when resolving- * workspaces. The `dev:docker` script mounts the host's PROJECT_PATH at+ * workspaces. The `dev:docker` script mounts the host's PROJECTS_PATH at* `/projects` inside the agent-server container, so this directory is* effectively the user's projects root in the dockerized dev stack. We* surface its immediate subdirectories as workspaces automatically.