mirror of https://github.com/OpenHands/OpenHands.git synced 2026-10-07 16:19:05 +08:00

Files

T

Rohit Malhotraandopenhands 6fa219cf25 feat: use uvx for temporary agent-server installation in dev mode (#99 )

* feat: use uvx for temporary agent-server installation in dev mode

- Replace direct agent-server CLI invocation with uvx temporary install
- Add OH_AGENT_SERVER_VERSION env var for specific PyPI versions
- Add OH_AGENT_SERVER_GIT_REF env var for git commits/branches
- Auto-install uv in .openhands/setup.sh if not present
- Update documentation (README, DEVELOPMENT.md, AGENTS.md)
- Add comprehensive tests for buildAgentServerCommand()

This removes the requirement to permanently install agent-server via
'uv tool install'. Users only need uv installed, and npm run dev will
automatically download and run the appropriate agent-server version.

Co-authored-by: openhands <openhands@all-hands.dev>

* fix: use subdirectory syntax for git ref in uvx monorepo

The software-agent-sdk is a uv workspace monorepo with packages in
subdirectories (openhands-agent-server/, openhands-tools/, etc.).

When installing from git, uvx requires the #subdirectory= fragment to
specify which package to install from the workspace.

Tested with: OH_AGENT_SERVER_GIT_REF=main npm run dev

Co-authored-by: openhands <openhands@all-hands.dev>

---------

Co-authored-by: openhands <openhands@all-hands.dev>

2026-05-05 13:14:14 -04:00

2.1 KiB

Raw Blame History

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
npm
uv (for running the agent server via uvx)

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
/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

2.1 KiB Raw Blame History