π OpenHands: AI-Driven Development
docs: clarify README install option requirements (#945)
Jamie Chicagodbc3abfed370
diff --git a/AGENTS.md b/AGENTS.mdindex 15e57ef80c..4a69f95374 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.mdindex 9607328285..e9467b66b7 100644--- a/README.md+++ b/README.md@@ -60,24 +60,34 @@ agent-canvas### Option 2: With a Docker Sandbox+**Prerequisites**:++- 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:**```shdocker 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```-The agent will be able to access any project under `PROJECTS_PATH`.-+**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`.### 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`)```shdiff --git a/README.windows.md b/README.windows.mdnew file mode 100644index 0000000000..686af07c51--- /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`.