🙌 OpenHands: AI-Driven Development
Revise README for project phase and quickstart (#192)
Robert Brennancab3d4c4a8a4
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.mdindex a336190694..2eed1a5b2c 100644--- a/DEVELOPMENT.md+++ b/DEVELOPMENT.md@@ -14,6 +14,25 @@ This is an alias for `npm run dev:safe`.It uses `uvx` to run a temporary `agent-server` installation for this checkout on `127.0.0.1:18000` and points the frontend at it. It isolates tmux state and conversation persistence by setting separate `TMUX_TMPDIR`, `OH_CONVERSATIONS_PATH`, `OH_BASH_EVENTS_DIR`, and `OH_VSCODE_PORT` values under `.openhands-dev/`, so it does not collide with other local or cloud-backed OpenHands sessions.+### 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` |++### 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/`+### Agent server version selectionBy default, the latest released version from PyPI is used. You can override this (highest precedence first):diff --git a/README.md b/README.mdindex 6c2fdedcce..e291929adc 100644--- a/README.md+++ b/README.md@@ -1,97 +1,61 @@# 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).+> This project is in sandbox 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+Agent Canvas is a web frontend for managing agents. You can:++- ⌨️ prompt them manually+- 🕐 run them on a schedule+- ⚡ trigger them automatically—e.g. from Slack or GitHub.++Agents can run anywhere:-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.+- 🧑💻 on your laptop+- 🖥️ on a remote virtual machine+- ☁️ in our hosted cloud+- 🏢 or inside your company’s infrastructure-### Prerequisites+You can work with any agent (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](https://openhands.dev/joinslack)++## Quickstart++**Prerequisites**:- Node.js 22.12.x or later- `npm`- `uv` (for running the agent server via `uvx`)-### 1. Clone and install the frontend+> [!WARNING]+> This runs the agent-server directly on the machine you're installing on--the agent will have full access to your filesystem!+> Stay tuned for docker sandboxing instructions.```shgit clone https://github.com/OpenHands/agent-canvas.gitcd agent-canvasnpm 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--```shnpm 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` |+# Architecture-### 5. First-run sanity check+Agent Canvas is powered by the [OpenHands Agent Server](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-agent-server/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.-After the page opens:+You can run an Agent Server anywhere:-- `/` 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+- Directly on your laptop (be careful!)+- Inside a Docker container+- On a dedicated machine like a Mac Mini+- On a virtual machine in the cloud+- Inside a Kubernetes Pod+- Inside OpenHands Cloud (our commercial offering)-### Alternative: Minimal Mode (without Automation)--To run without the automation service:--```sh-npm run dev:minimal-```+The Agent Server is often paired with an [Automation Server](https://github.com/OpenHands/automation), which lets you set up agents that run on a schedule or in response to events.-This runs only agent-server + Vite (no automation backend or ingress).-Access at `http://localhost:3001/`+<img width="1456" height="1258" alt="image" src="https://github.com/user-attachments/assets/cb6de6f5-ac30-4d04-a76a-b5c259f0c163" />## More documentation