From ec59aaae2c0822baec5a66946bcbe9504a8e8f28 Mon Sep 17 00:00:00 2001 From: openhands Date: Fri, 29 May 2026 18:21:28 +0000 Subject: [PATCH 1/4] Clarify README install option requirements Co-authored-by: openhands --- README.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 9c73f59a..a663a975 100644 --- a/README.md +++ b/README.md @@ -60,6 +60,8 @@ agent-canvas ### Option 2: With a Docker Sandbox +**Prerequisites**: Docker, plus a host directory containing the projects you want to mount into the container + ```sh docker pull ghcr.io/openhands/agent-canvas:1.0.0-alpha.8 @@ -74,10 +76,11 @@ docker run -it --rm \ The agent will be able to access any project under `PROJECTS_PATH`. - - ### Option 3: From Source +> [!WARNING] +> This runs the agent-server directly on the machine you're installing on — the agent will have full access to your filesystem! + **Prerequisites**: Node.js 22.12.x or later, `npm`, `uv` (for running the agent server via `uvx`) ```sh From 86b54619a1aec287816f98725468acc9d40f6e1d Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 2 Jun 2026 17:02:11 +0000 Subject: [PATCH 2/4] docs: add Windows PowerShell syntax for Docker sandbox option Split Option 2 into Linux/Mac and Windows (PowerShell) code blocks to address cross-platform shell syntax differences. The original Unix-style export syntax doesn't work on Windows CMD or PowerShell. --- README.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/README.md b/README.md index 76833078..39d46b58 100644 --- a/README.md +++ b/README.md @@ -62,6 +62,7 @@ agent-canvas **Prerequisites**: Docker, plus a host directory containing the projects you want to mount into the container +**Linux / Mac:** ```sh docker pull ghcr.io/openhands/agent-canvas:1.0.0-alpha.10 @@ -74,6 +75,19 @@ docker run -it --rm \ ghcr.io/openhands/agent-canvas:1.0.0-alpha.10 ``` +**Windows (PowerShell):** +```powershell +docker pull ghcr.io/openhands/agent-canvas:1.0.0-alpha.10 + +$env:PROJECTS_PATH = "$HOME\projects" # directory containing your project folders + +docker run -it --rm \ + -p 8000:8000 \ + -v $env:USERPROFILE\.openhands:C:\home\openhands\.openhands \ + -v ${env:PROJECTS_PATH}:C:\projects \ + ghcr.io/openhands/agent-canvas:1.0.0-alpha.10 +``` + The agent will be able to access any project under `PROJECTS_PATH`. ### Option 3: From Source From 3552c39de83c58925b79d0db316abc1b4346b8db Mon Sep 17 00:00:00 2001 From: enyst Date: Tue, 2 Jun 2026 17:21:01 +0000 Subject: [PATCH 3/4] docs: refine install commands across platforms Co-authored-by: openhands --- README.md | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 39d46b58..fcc31089 100644 --- a/README.md +++ b/README.md @@ -60,18 +60,22 @@ agent-canvas ### Option 2: With a Docker Sandbox -**Prerequisites**: Docker, plus a host directory containing the projects you want to mount into the container +**Prerequisites**: -**Linux / Mac:** +- Docker: Docker Desktop on macOS/Windows, or Docker Engine/Docker Desktop on Linux. +- A host directory for `PROJECTS_PATH` containing the project folders you want the agent to access. Create it before starting the container. + +**macOS / Linux:** ```sh docker pull ghcr.io/openhands/agent-canvas:1.0.0-alpha.10 -export PROJECTS_PATH=~/projects # directory containing your project folders +export PROJECTS_PATH="$HOME/projects" # directory containing your project folders +mkdir -p "$PROJECTS_PATH" "$HOME/.openhands" docker run -it --rm \ -p 8000:8000 \ - -v ~/.openhands:/home/openhands/.openhands \ - -v ${PROJECTS_PATH}:/projects \ + -v "$HOME/.openhands:/home/openhands/.openhands" \ + -v "${PROJECTS_PATH}:/projects" \ ghcr.io/openhands/agent-canvas:1.0.0-alpha.10 ``` @@ -79,12 +83,13 @@ docker run -it --rm \ ```powershell docker pull ghcr.io/openhands/agent-canvas:1.0.0-alpha.10 -$env:PROJECTS_PATH = "$HOME\projects" # directory containing your project folders +$env:PROJECTS_PATH = Join-Path $HOME "projects" # directory containing your project folders +New-Item -ItemType Directory -Force -Path $env:PROJECTS_PATH, (Join-Path $env:USERPROFILE ".openhands") | Out-Null -docker run -it --rm \ - -p 8000:8000 \ - -v $env:USERPROFILE\.openhands:C:\home\openhands\.openhands \ - -v ${env:PROJECTS_PATH}:C:\projects \ +docker run -it --rm ` + -p 8000:8000 ` + -v "$($env:USERPROFILE)\.openhands:/home/openhands/.openhands" ` + -v "$($env:PROJECTS_PATH):/projects" ` ghcr.io/openhands/agent-canvas:1.0.0-alpha.10 ``` From 2fb4deb7d2e6150bafc8a92259024b817e3c82e1 Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 2 Jun 2026 17:45:24 +0000 Subject: [PATCH 4/4] docs: move Windows PowerShell instructions to separate README Co-authored-by: openhands --- AGENTS.md | 1 + README.md | 14 +------------- README.windows.md | 27 +++++++++++++++++++++++++++ 3 files changed, 29 insertions(+), 13 deletions(-) create mode 100644 README.windows.md diff --git a/AGENTS.md b/AGENTS.md index 15e57ef8..4a69f953 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -431,6 +431,7 @@ When adding code that needs a new string, decide up front which rule it falls un - README expectation: keep the first section as a concrete, chronological from-scratch quickstart for running this frontend against a real `openhands-agent-server` (clone, install prerequisites, optional `.env`, run `npm run dev`). - Keep README user-focused and move contributor/developer-specific workflows (`dev:safe`, mock mode, detailed env vars/build-test notes) into `DEVELOPMENT.md`. +- Windows-specific command syntax (PowerShell) lives in `README.windows.md`. When changing install / Docker sandbox instructions in `README.md`, update `README.windows.md` in the same PR to keep them in sync. - `scripts/dev-safe.mjs` uses `uvx` for temporary agent-server installation — no permanent `uv tool install` needed. Environment variables (highest precedence first): - `OH_AGENT_SERVER_LOCAL_PATH` — absolute path to a local `software-agent-sdk` checkout. Runs the local checkout via `uvx` with `--with-editable` for `openhands-sdk`/`openhands-tools`/`openhands-workspace` and `--reinstall` for `openhands-agent-server`, so SDK edits are picked up on restart. Highest precedence. - `OH_AGENT_SERVER_GIT_REF` — git commit SHA or branch name (takes precedence over version) diff --git a/README.md b/README.md index fcc31089..e9467b66 100644 --- a/README.md +++ b/README.md @@ -79,19 +79,7 @@ docker run -it --rm \ ghcr.io/openhands/agent-canvas:1.0.0-alpha.10 ``` -**Windows (PowerShell):** -```powershell -docker pull ghcr.io/openhands/agent-canvas:1.0.0-alpha.10 - -$env:PROJECTS_PATH = Join-Path $HOME "projects" # directory containing your project folders -New-Item -ItemType Directory -Force -Path $env:PROJECTS_PATH, (Join-Path $env:USERPROFILE ".openhands") | Out-Null - -docker run -it --rm ` - -p 8000:8000 ` - -v "$($env:USERPROFILE)\.openhands:/home/openhands/.openhands" ` - -v "$($env:PROJECTS_PATH):/projects" ` - ghcr.io/openhands/agent-canvas:1.0.0-alpha.10 -``` +**Windows (PowerShell / Windows Terminal):** See [README.windows.md](./README.windows.md) for the equivalent commands. The agent will be able to access any project under `PROJECTS_PATH`. diff --git a/README.windows.md b/README.windows.md new file mode 100644 index 00000000..686af07c --- /dev/null +++ b/README.windows.md @@ -0,0 +1,27 @@ +# Windows quickstart (PowerShell) + +This doc contains **Windows-specific** command syntax for running Agent Canvas with the **Docker sandbox**. + +For the main install options and overall context, see [README.md](./README.md). + +## Option 2: With a Docker Sandbox (Windows) + +**Prerequisites**: + +- Docker Desktop for Windows +- A host directory for `PROJECTS_PATH` containing the project folders you want the agent to access (create it before starting the container) + +```powershell +docker pull ghcr.io/openhands/agent-canvas:1.0.0-alpha.10 + +$env:PROJECTS_PATH = Join-Path $HOME "projects" # directory containing your project folders +New-Item -ItemType Directory -Force -Path $env:PROJECTS_PATH, (Join-Path $env:USERPROFILE ".openhands") | Out-Null + +docker run -it --rm ` + -p 8000:8000 ` + -v "$($env:USERPROFILE)\.openhands:/home/openhands/.openhands" ` + -v "$($env:PROJECTS_PATH):/projects" ` + ghcr.io/openhands/agent-canvas:1.0.0-alpha.10 +``` + +The agent will be able to access any project under `PROJECTS_PATH`.