Rohit Malhotraandopenhands
cccecf1100
The openhands-agent-server package exposes an executable named 'agent-server', not 'openhands-agent-server'. When using PyPI versions (either specific or latest), we need to use the --from syntax: uvx --from openhands-agent-server agent-server This fixes the error: An executable named 'openhands-agent-server' is not provided by package 'openhands-agent-server'. Use 'uvx --from openhands-agent-server agent-server' instead. Fixes #117 Co-authored-by: openhands <openhands@all-hands.dev>
agent-server-gui
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.
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
npmuv(for running the agent server viauvx)
1. Clone and install the frontend
git clone https://github.com/OpenHands/agent-server-gui.git
cd agent-server-gui
npm install
2. Install uv
If you do not already have uv installed, install it first (OpenHands SDK recommends uv 0.8.13+):
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:
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:
cp .env.sample .env
Then edit the values you need.
4. Start the app
npm run dev
This starts an isolated local agent-server for this checkout and the frontend on http://localhost:3001.
5. First-run sanity check
After the page opens:
/should load without errors/settingsshould load- configure a working LLM model + API key under
Settings > LLMbefore running the first live task - you should be able to open or create a conversation
More documentation
For contributor and developer workflows, including frontend-only mode, mock mode, environment variables, and build/test commands, see DEVELOPMENT.md.