988cfed5c6
* feat: add automation backend integration with standalone ingress proxy - Add scripts/ingress.mjs: standalone HTTP reverse proxy for routing traffic to multiple backends based on URL path prefix - Add scripts/dev-with-automation.mjs: orchestrates full stack with agent-server, automation backend (both via uvx), Vite, and ingress - Make 'npm run dev' run full stack by default (was dev:safe, now dev:automation) - Rename 'npm run dev:safe' to 'npm run dev:minimal' for agent-server + Vite only - Update README with new quickstart showing full stack as default - Update AGENTS.md with architecture documentation Architecture: http://localhost:8000 (Ingress) ├── /api/automation/* → Automation Backend (:18001) ├── /api/*, /sockets → Agent Server (:18000) └── /* (default) → Vite Dev Server (:3001) * test: add tests for ingress and dev-with-automation scripts - Add __tests__/scripts/ingress.test.ts with 14 tests covering: - CLI argument parsing (--help, --port, --route, --default) - Route matching (exact, prefix, longest-match-first) - Proxy functionality (forwarding, query params, error handling) - 502 response when backend unavailable - 503 response for unmatched routes with no default - Add __tests__/scripts/dev-with-automation.test.ts with 19 tests covering: - buildAutomationCommand() with various git refs/repos - buildConfig() port and path configuration - CLI --help output - Graceful exit when uvx is missing - Export testable functions from dev-with-automation.mjs * fix: prevent dev-with-automation from auto-executing when imported The script was calling main() unconditionally, which caused test failures when vitest imported the module. Now check if the module is the main entry point before executing. --------- Co-authored-by: openhands <openhands@all-hands.dev> Co-authored-by: hieptl <hieptl.developer@gmail.com>
2.7 KiB
agent-canvas
Warning
This project is in an early incubator phase. It may be vibecoded, untested, or out of date. OpenHands takes no responsibility for the code or its support. Learn more.
Quickstart
This repository is a near-direct port of the OpenHands frontend adapted to talk directly to software-agent-sdk / agent_server without the usual OpenHands app backend.
Prerequisites
- Node.js 22.12.x or later
npmuv(for running the agent server viauvx)
1. Clone and install the frontend
git clone https://github.com/OpenHands/agent-canvas.git
cd agent-canvas
npm install
2. Install uv
If you do not already have uv installed, install it first (OpenHands SDK recommends uv 0.8.13+):
curl -LsSf https://astral.sh/uv/install.sh | sh
Need Windows or another install method? See the official uv installation guide: https://docs.astral.sh/uv/getting-started/installation/
If ~/.local/bin is not already on your PATH, add it:
export PATH="$HOME/.local/bin:$PATH"
command -v uvx
The npm run dev command uses uvx to automatically download and run the agent server, so no separate installation step is needed.
3. Optional: create a .env file
If you need to change the backend URL, frontend port, session API key, or working directory, copy the sample file:
cp .env.sample .env
Then edit the values you need.
4. Start the app
npm run dev
This starts the full stack:
- Agent server (via uvx)
- Automation backend (via uvx)
- Vite dev server
- Ingress proxy (routes traffic to all backends)
Access the UI at http://localhost:8000
Environment Variables
| Variable | Description | Default |
|---|---|---|
PORT |
Ingress port | 8000 |
OH_AUTOMATION_GIT_REF |
Git ref for automation backend | main |
OH_AGENT_SERVER_GIT_REF |
Git ref for agent-server | main |
5. First-run sanity check
After the page opens:
/should load without errors/settingsshould load- configure a working LLM model + API key under
Settings > LLMbefore running the first live task - you should be able to open or create a conversation
/api/automation/docsshould show the automation API docs
Alternative: Minimal Mode (without Automation)
To run without the automation service:
npm run dev:minimal
This runs only agent-server + Vite (no automation backend or ingress).
Access at http://localhost:3001/
More documentation
For contributor and developer workflows, including frontend-only mode, mock mode, environment variables, and build/test commands, see DEVELOPMENT.md.