8bb2b8c518
* Add partial stack modes to agent-canvas Co-authored-by: openhands <openhands@all-hands.dev> * fix: address PR review feedback (#1040) - Replace padEnd(75) with ANSI-aware ansiPadEnd helper in printBanner; String.padEnd counts invisible escape bytes as visible chars, causing the box border to misalign in colour terminals - Deduplicate storage directory creation in ensureDirectories; was being pushed once per launchAgentServer block and once per launchAutomation block (always both true together) — move to a shared unconditional slot - Add explanatory comment to the checkNpm two-clause OR condition Co-authored-by: openhands <openhands@all-hands.dev> * test: add e2e tests for --frontend-only, --backend-only, and port conflicts Add mock-llm-partial-stack.spec.ts with three test groups: 1. --frontend-only: verifies static frontend is served (200 on /), backend routes return 503 (/server_info, /api/settings, /api/automation/v1), and the browser shows the manage-backends modal. 2. --backend-only: verifies /server_info returns 200, /api/settings is reachable, automation endpoint works, and root/asset requests return 503 (no frontend configured). 3. Port conflict: verifies the process exits non-zero with a clear error when the ingress port is occupied, then starts successfully on a free port. Unlike the other mock-llm specs, these tests spawn their own bin/agent-canvas.mjs child processes with isolated state dirs and high port numbers (18310+ range) to avoid collisions. Co-authored-by: openhands <openhands@all-hands.dev> * fix: adjust frontend-only test to expect SPA fallback instead of 503 In frontend-only mode the ingress has no backend routes — all requests (including /server_info, /api/*) fall through to the static server's default backend, which returns index.html via SPA fallback (200 with HTML). The test now verifies that /server_info returns HTML (not JSON) and that the browser detects the missing backend and shows the manage-backends modal. Co-authored-by: openhands <openhands@all-hands.dev> * feat: add --reject-prefix to static server for clean 503 on missing backends In --frontend-only mode the static server was SPA-fallbacking API paths (/server_info, /api/*, /sockets, etc.) to index.html, returning 200 with HTML content instead of a clear failure. This made the frontend's /server_info probe ambiguous. Add a --reject-prefix flag to static-server.mjs: any matching request returns 503 ('Service Unavailable') before the SPA fallback runs. Wire it through dev-with-automation.mjs: getRejectPrefixes(config) computes which API prefixes have no backend configured (e.g. all of them in frontend-only mode) and buildRejectPrefixArgs() passes them as --reject-prefix flags to the static server. Restore the e2e test to assert 503 for /server_info, /api/settings, and /api/automation/v1 in frontend-only mode. Co-authored-by: openhands <openhands@all-hands.dev> * fix: treat non-401 HTTP errors from /server_info as unavailable loadAgentServerInfo was re-throwing all SDK HttpErrors (including 503) as-is, but root.tsx only checks for AgentServerUnavailableError. A 503 from the static server in --frontend-only mode (or any non-401 error) would fall through to the Outlet instead of showing the manage-backends modal. Narrow the re-throw to only preserve 401 (needed for the auth screen in public mode). All other HTTP errors are now wrapped as AgentServerUnavailableError so the app shows the correct recovery UI. Co-authored-by: openhands <openhands@all-hands.dev> * fix: poll automation readiness in backend-only test; retry on 5xx The automation backend starts independently from the agent-server and may not be ready when /server_info first returns 200. pollUrl now treats 5xx responses as 'not ready yet' and keeps retrying. The backend-only test also polls /api/automation/v1 before asserting on it. Co-authored-by: openhands <openhands@all-hands.dev> --------- Co-authored-by: openhands <openhands@all-hands.dev> Co-authored-by: Rohit Malhotra <rohitvinodmalhotra@gmail.com>
5.3 KiB
agent-canvas
Warning
This project is in the Beta phase. It may be vibecoded, untested, or out of date. OpenHands takes no responsibility for the code or its support. Learn more.
OpenHands is a platform for orchestrating coding agents across different environments. You can:
- ⌨️ prompt agents manually
- 🕐 run agents on a schedule
- ⚡ trigger agents automatically — e.g. from Slack, GitHub, or Datadog.
Agents can run anywhere:
- 🧑💻 on your laptop
- 🖥️ on a remote virtual machine
- ☁️ in our hosted cloud
- 🏢 or inside your company’s infrastructure
The same Agent Canvas frontend can swap between each of these environments, so you can see everything in one place.
OpenHands works with any agent harness (e.g. Claude Code, Codex) or connect directly to an LLM (e.g. Anthropic, OpenAI, Gemini, Mistral, Minimax, Kimi).
If you have questions or feedback, please open a GitHub issue or join the #proj-agent-canvas channel in Slack.
Project ownership and support
- Current status: Beta.
- Support channel: #proj-agent-canvas.
- Support level: Best effort while the project remains in Beta.
Quickstart
You can install OpenHands to run agents on any machine: on your laptop, on a dedicated computer like a Mac Mini, or on a server in the cloud.
The most powerful way to run OpenHands is on a server in the cloud. This allows your agents to continue running even when your laptop is shut, and makes it easier to trigger your agents through third-party services like Slack, GitHub, and Datadog. See SELF_HOSTING.md for details, especially with respect to security hardening.
Notably, you can run the backend in multiple different environments, and switch between them from the same Agent Canvas frontend. E.g. you can share an Agent Server with your team for agents doing code review and dependency updates, then have your personal agents running on your laptop.
Option 1: Without a Sandbox
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, uv
npm install -g @openhands/agent-canvas
agent-canvas
The agent-canvas command starts the full local stack by default. You can also split it when you want to run pieces separately:
agent-canvas --frontend-only # static frontend + ingress only
agent-canvas --backend-only # agent server + automation backend + ingress only
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_PATHcontaining the project folders you want the agent to access. Create it before starting the container.
macOS / Linux:
docker pull ghcr.io/openhands/agent-canvas:1.0.0-alpha.10
export PROJECTS_PATH="$HOME/projects" # directory containing your project folders
mkdir -p "$PROJECTS_PATH" "$HOME/.openhands"
docker run -it --rm \
-p 8000:8000 \
-v "$HOME/.openhands:/home/openhands/.openhands" \
-v "${PROJECTS_PATH}:/projects" \
ghcr.io/openhands/agent-canvas:1.0.0-alpha.10
Windows (PowerShell / Windows Terminal): See 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)
git clone https://github.com/OpenHands/agent-canvas.git
cd agent-canvas
npm install
npm run dev
Access the UI at http://localhost:8000. You can add additional backends directly from the UI.
Architecture
Agent Canvas is powered by the OpenHands Agent Server, a REST API for running multiple agents on a single machine. Each Agent Server runs on a single host/port; the Agent Canvas can connect to multiple Agent Servers and easily flip between them.
You can run an Agent Server anywhere:
- Directly on your laptop (be careful!)
- On a dedicated machine like a Mac Mini
- On a virtual machine in the cloud
- Inside OpenHands Cloud (our commercial offering)
The Agent Server is often paired with an Automation Server, which lets you set up agents that run on a schedule or in response to events.