Skip to content

πŸ™Œ OpenHands: AI-Driven Development

docs: clarify README install option requirements (#945)

Jamie Chicagodbc3abfed370
diff --git a/AGENTS.md b/AGENTS.md
index 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.md
index 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:**
```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
```
-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`)
```sh
diff --git a/README.windows.md b/README.windows.md
new file mode 100644
index 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`.