Skip to content

πŸ™Œ OpenHands: AI-Driven Development

Rename PROJECT_PATH to PROJECTS_PATH (#521)

Engel Nyst5c42bd349287
diff --git a/AGENTS.md b/AGENTS.md
index 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.md
index 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/projects
git clone https://github.com/OpenHands/agent-canvas.git
cd agent-canvas
npm install
@@ -49,7 +49,7 @@ This serves a static production build of the frontend behind the local ingress p
Windows 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.git
cd agent-canvas
npm install
diff --git a/__tests__/bin/agent-canvas.test.ts b/__tests__/bin/agent-canvas.test.ts
new file mode 100644
index 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.ts
index 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.mjs
index 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 message
ENVIRONMENT VARIABLES:
- PROJECT_PATH Required: path to your projects directory
+ PROJECTS_PATH Required: path to your projects directory
OH_SECRET_KEY Secret key for encrypting settings
OH_AGENT_SERVER_GIT_REF Git ref for agent-server Docker image tag
OH_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-canvas
For more options, see: node scripts/dev-docker.mjs --help
`);
diff --git a/scripts/dev-docker.mjs b/scripts/dev-docker.mjs
index 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.ts
index 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.