mirror of
https://github.com/OpenHands/OpenHands.git
synced 2026-10-07 16:38:34 +08:00
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>
99 lines
2.7 KiB
Markdown
99 lines
2.7 KiB
Markdown
# 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](https://github.com/OpenHands/incubator-program).
|
|
|
|
## 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
|
|
- `npm`
|
|
- `uv` (for running the agent server via `uvx`)
|
|
|
|
### 1. Clone and install the frontend
|
|
|
|
```sh
|
|
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+):
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
cp .env.sample .env
|
|
```
|
|
|
|
Then edit the values you need.
|
|
|
|
### 4. Start the app
|
|
|
|
```sh
|
|
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](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
|
|
- `/settings` should load
|
|
- configure a working LLM model + API key under `Settings > LLM` before running the first live task
|
|
- you should be able to open or create a conversation
|
|
- `/api/automation/docs` should show the automation API docs
|
|
|
|
### Alternative: Minimal Mode (without Automation)
|
|
|
|
To run without the automation service:
|
|
|
|
```sh
|
|
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](./DEVELOPMENT.md).
|