π OpenHands: AI-Driven Development
Document from-scratch agent-server setup
openhandse12213bd3706
diff --git a/.env.sample b/.env.sampleindex 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 serverVITE_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.mdindex 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.mdindex 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 repositorygit clone https://github.com/neubig/agent-server-gui.git--# Change to the project directorycd agent-server-gui--# Install the dependenciesnpm 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```shnpm 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:```shnpm run dev:mock@@ -55,29 +89,32 @@ npm run dev:mocknpm 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 VariablesThe frontend application uses the following environment variables: