Skip to content

🙌 OpenHands: AI-Driven Development

Revise README for project phase and quickstart (#192)

Robert Brennancab3d4c4a8a4
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index 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 selection
By default, the latest released version from PyPI is used. You can override this (highest precedence first):
diff --git a/README.md b/README.md
index 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.
```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` |
+# 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