Skip to content

πŸ™Œ OpenHands: AI-Driven Development

Document from-scratch agent-server setup

openhandse12213bd3706
diff --git a/.env.sample b/.env.sample
index 1a700c432f..dba2545e2b 100644
--- a/.env.sample
+++ b/.env.sample
@@ -1,8 +1,17 @@
-VITE_BACKEND_BASE_URL="localhost:3000" # Backend URL without protocol (e.g. localhost:3000)
-VITE_BACKEND_HOST="127.0.0.1:3000" # Backend host with port for API connections
-VITE_MOCK_API="false" # Enable/disable API mocking with MSW (true or false)
-VITE_MOCK_SAAS="false" # Simulate SaaS mode in development (true or false)
-VITE_USE_TLS="false" # Use HTTPS/WSS for backend connections (true or false)
+# OpenHands Agent Server target
+VITE_BACKEND_HOST="127.0.0.1:8000" # Host:port used by the Vite dev proxy
+VITE_BACKEND_BASE_URL="http://127.0.0.1:8000" # Base URL used by browser-side direct requests
+# VITE_SESSION_API_KEY="" # Optional X-Session-API-Key for authenticated backends
+# VITE_WORKING_DIR="/workspace/project" # Workspace path used when starting conversations
+# VITE_WORKER_URLS="" # Optional comma-separated worker URLs for the Browser tab
+# VITE_ENABLE_BROWSER_TOOLS="true" # Set to false to omit BrowserToolSet from new conversations
+
+# Frontend dev server
VITE_FRONTEND_PORT="3001" # Port to run the frontend application
-VITE_INSECURE_SKIP_VERIFY="false" # Skip TLS certificate verification (true or false)
+VITE_USE_TLS="false" # Use HTTPS/WSS for proxied backend connections
+VITE_INSECURE_SKIP_VERIFY="false" # Skip TLS certificate verification for proxied backend requests
+
+# Mocking / test helpers
+VITE_MOCK_API="false" # Enable/disable API mocking with MSW
+VITE_MOCK_SAAS="false" # Simulate SaaS mode in development
# VITE_GITHUB_TOKEN="" # GitHub token for repository access (used in some tests)
diff --git a/AGENTS.md b/AGENTS.md
index a57487852e..93176b23f0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -25,5 +25,7 @@
- `GET /api/conversations` expects repeated `ids` params (`?ids=a&ids=b`), not Axios's default bracket form (`ids[]=a`), so the shared Axios client needs a custom params serializer.
- Runtime git panels should prefer the conversation's reported `workspace.working_dir` when present; falling back to `/workspace/project` can produce 500s like `Not a git repository` for direct local workspaces such as `/workspace/project/agent-server-gui`.
- Live settings currently load with the `SDK settings schema unavailable.` placeholder when the backend does not expose `/api/settings/agent-schema` and `/api/settings/conversation-schema`; this is expected for the current local backend.
+- README expectation: the very first section should be a concrete from-scratch quickstart for running this frontend against a real `openhands-agent-server` (clone, install backend, optional `.env`, run `npm run dev`). Keep live-backend instructions ahead of general project overview.
+
diff --git a/README.md b/README.md
index e7be3a0c99..b18281079c 100644
--- a/README.md
+++ b/README.md
@@ -1,53 +1,87 @@
-# Getting Started with agent-server-gui
+# agent-server-gui
-## Overview
-
-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.
-
-## Tech Stack
-
-- Remix SPA Mode (React + Vite + React Router)
-- TypeScript
-- Redux
-- TanStack Query
-- Tailwind CSS
-- i18next
-- React Testing Library
-- Vitest
-- Mock Service Worker
+## Run this with OpenHands Agent Server first
-## Getting Started
+If you only read one section of this README, read this one. Most users will want to clone this repo, point it at a real `openhands-agent-server`, and start using the UI immediately.
### Prerequisites
- Node.js 22.12.x or later
-- `npm`, `bun`, or any other package manager that supports the `package.json` file
+- `npm`
+- A running OpenHands Agent Server (`openhands-agent-server`)
-### Installation
+### 1. Clone and install the frontend
```sh
-# Clone the repository
git clone https://github.com/neubig/agent-server-gui.git
-
-# Change to the project directory
cd agent-server-gui
-
-# Install the dependencies
npm install
```
-### Running the Application in Development Mode
+### 2. Install and start OpenHands Agent Server
+
+If you do not already have the backend installed, install it first:
+
+```sh
+python3 -m pip install openhands-agent-server
+```
+
+Then start the backend on the default local port:
+
+```sh
+openhands-agent-server --host 127.0.0.1 --port 8000
+```
+
+The frontend expects the backend at `127.0.0.1:8000` by default, so this is the easiest from-scratch setup.
+
+If you prefer installing from source or want the full SDK setup flow, see the OpenHands SDK docs: <https://docs.openhands.dev/sdk/getting-started>
+
+### 3. Optional: create a `.env` file
+
+If your backend is **not** running on `127.0.0.1:8000`, or if it requires a session API key, create a `.env` file:
+
+```sh
+cp .env.sample .env
+```
+
+Then update the values you need:
+
+```dotenv
+VITE_BACKEND_HOST="127.0.0.1:8000"
+VITE_BACKEND_BASE_URL="http://127.0.0.1:8000"
+VITE_FRONTEND_PORT="3001"
+# VITE_SESSION_API_KEY="your-session-api-key"
+# VITE_WORKING_DIR="/absolute/path/to/the-workspace-used-by-agent-server"
+```
+
+Notes:
-Start a local `agent_server` separately, then run the frontend dev server:
+- `VITE_BACKEND_HOST` is used by the Vite dev proxy for `/api`, `/server_info`, and `/sockets`.
+- `VITE_BACKEND_BASE_URL` is used by browser-side direct requests. Keep it pointed at the same backend.
+- `VITE_WORKING_DIR` should match the workspace path the backend will use when starting new conversations.
+- If your backend does not require `X-Session-API-Key`, leave `VITE_SESSION_API_KEY` unset.
+
+### 4. Start the frontend
```sh
npm run dev
```
This starts the frontend on [http://localhost:3001](http://localhost:3001).
-By default it proxies API and WebSocket requests to `http://127.0.0.1:8000`.
-If you want to run against mocked APIs instead, use:
+### 5. First-run sanity check
+
+After the page opens:
+
+- `/` should load without errors
+- you should be able to open or create a conversation
+- `/conversations/:id` should load conversation content
+- `/settings` should load
+ - if your backend does not expose settings schemas, the UI will show `SDK settings schema unavailable.` instead of crashing
+
+### Mock mode
+
+If you want to run the frontend without a live backend, use:
```sh
npm run dev:mock
@@ -55,29 +89,32 @@ npm run dev:mock
npm run dev:mock:saas
```
-### Building for Production
+## Overview
-There is no `Makefile` in this repository. Use the npm scripts instead:
+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.
-```sh
-npm run build
-npm run start
-```
+## Tech Stack
+
+- Remix SPA Mode (React + Vite + React Router)
+- TypeScript
+- Redux
+- TanStack Query
+- Tailwind CSS
+- i18next
+- React Testing Library
+- Vitest
+- Mock Service Worker
-### Running Against a Real agent_server
+## Building for Production
-A typical local setup is:
+There is no `Makefile` in this repository. Use the npm scripts instead:
```sh
-# terminal 1: start the backend
-# example only; use whatever command you use to run agent_server
-openhands-agent-server
-
-# terminal 2: start the frontend
-npm run dev
+npm run build
+npm run start
```
-### Environment Variables
+## Environment Variables
The frontend application uses the following environment variables: