π OpenHands: AI-Driven Development
feat: use uvx for temporary agent-server installation in dev mode (#99)
Rohit Malhotra6fa219cf252b
diff --git a/.env.sample b/.env.sampleindex 4ef207574a..cbb6fd4b0c 100644--- a/.env.sample+++ b/.env.sample@@ -19,7 +19,11 @@ VITE_INSECURE_SKIP_VERIFY="false" # Skip TLS certificate verification for proxieVITE_MOCK_API="false" # Enable/disable API mocking with MSW# VITE_GITHUB_TOKEN="" # GitHub token for repository access (used in some tests)-# `npm run dev` (scripts/dev-safe.mjs) β isolated local backend+# `npm run dev` (scripts/dev-safe.mjs) β isolated local backend via uvx# OH_GUI_SAFE_BACKEND_PORT="18000" # Port the spawned agent-server listens on# OH_GUI_SAFE_VSCODE_PORT="18001" # Port forwarded to the embedded VS Code (defaults to backend port + 1)# OH_GUI_SAFE_STATE_DIR="$HOME/.openhands/agent-server-gui" # Where conversations, tmux sockets, and bash events are stored++# Agent server version selection (uvx)+# OH_AGENT_SERVER_VERSION="" # Specific PyPI version (e.g., "1.18.0"). Uses latest release if unset.+# OH_AGENT_SERVER_GIT_REF="" # Git commit SHA or branch name (e.g., "main", "abc1234"). Takes precedence over version.diff --git a/.openhands/setup.sh b/.openhands/setup.shindex 26be163eff..92ba88b869 100755--- a/.openhands/setup.sh+++ b/.openhands/setup.sh@@ -6,6 +6,22 @@ ENV_FILE="$REPO_ROOT/.env"cd "$REPO_ROOT" || exit 1+# Install uv if not present (required for running agent-server via uvx)+if ! command -v uvx &> /dev/null; then+ echo "Installing uv..."+ curl -LsSf https://astral.sh/uv/install.sh | sh++ # Add uv to PATH for the rest of this script+ export PATH="$HOME/.local/bin:$PATH"++ # Verify installation+ if ! command -v uvx &> /dev/null; then+ echo "Warning: uv installed but uvx not found in PATH."+ echo "You may need to add ~/.local/bin to your PATH:"+ echo ' export PATH="$HOME/.local/bin:$PATH"'+ fi+fi+if [ ! -d node_modules ]; thennpm cifidiff --git a/AGENTS.md b/AGENTS.mdindex a44b66db39..0acfc36212 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -48,9 +48,7 @@- When the browser is accessing the frontend through a remote host (for example an All Hands work URL) but `VITE_BACKEND_BASE_URL` points at `127.0.0.1`/`localhost`, browser-side REST calls must fall back to the frontend origin so Vite can proxy `/api` and `/sockets` to the local backend.- `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`.- - For the current `openhands-agent-server` PyPI/uv-tool flow, `uv tool install -U openhands-agent-server` alone was not sufficient in this environment. A working install was:- - `uv tool install -U --with openhands-tools --with openhands-workspace openhands-agent-server`- - `uv tool install` exposes the executable as `agent-server`, not `openhands-agent-server`, and may require adding `~/.local/bin` to `PATH`.+ - For development, `npm run dev` now uses `uvx` to run a temporary agent-server installation, so no permanent `uv tool install` is required. For standalone installations, `uv tool install -U --with openhands-tools --with openhands-workspace openhands-agent-server` would expose the executable as `agent-server` (not `openhands-agent-server`), possibly requiring `~/.local/bin` on `PATH`.- Current SDK / agent-server conversation start payloads must use SDK-registered snake_case tool names, not the old class-style names. Working names against SDK v1.18.1 were:- `terminal`- `file_editor`@@ -70,15 +68,19 @@- Git provider token persistence note: this direct-agent-server frontend now persists `Settings > Git` provider tokens locally in browser storage instead of posting to an app-backend secrets route. `src/api/secrets-service.ts` writes the token payload to localStorage, mirrors provider hosts into `provider_tokens_set` through `SettingsService.saveSettings()`, and `use-delete-git-providers` clears that local state.- Agent server connection settings now live at `Settings > Agent Server` (`/settings/agent-server`). The page reads deployment defaults from `VITE_BACKEND_BASE_URL` / `VITE_SESSION_API_KEY`, saves user overrides in the `openhands-agent-server-config` localStorage key, and must stay reachable even when the backend compatibility probe fails so users can recover from missing or wrong backend configuration.-- README expectation: keep the first section as a concrete, chronological from-scratch quickstart for running this frontend against a real `openhands-agent-server` (clone, install backend, optional `.env`, run `npm run dev`).+- README expectation: keep the first section as a concrete, chronological from-scratch quickstart for running this frontend against a real `openhands-agent-server` (clone, install uv, optional `.env`, run `npm run dev`).- Keep README user-focused and move contributor/developer-specific workflows (`dev:safe`, mock mode, detailed env vars/build-test notes) into `DEVELOPMENT.md`.-- `scripts/dev-safe.mjs` should fail fast if `agent-server` cannot be spawned (for example missing PATH entries).+- `scripts/dev-safe.mjs` uses `uvx` for temporary agent-server installation β no permanent `uv tool install` needed. Environment variables:+ - `OH_AGENT_SERVER_VERSION` β specific PyPI version (e.g., "1.18.0")+ - `OH_AGENT_SERVER_GIT_REF` β git commit SHA or branch name (takes precedence over version)+ - Default: latest released version from PyPI+- `scripts/dev-safe.mjs` should fail fast if `uvx` cannot be spawned (for example missing PATH entries).- Vite dev mode can black-screen on first load with `504 Outdated Optimize Dep` if core client-entry deps are not prebundled; keep `react`, `react/jsx-runtime`, `react-dom/client`, and `react-router/dom` in `optimizeDeps.include`.- Vercel deployment note: React Router builds for this repo must keep `build/client` intact on actual Vercel builds and include `presets: [vercelPreset()]` from `@vercel/react-router/vite`; flattening `build/client` during a Vercel build produces deployments with empty outputs (`routes: null`, no static files) and a production 404.- The repo should include a root `LICENSE` file to satisfy the incubator-program requirements.- OpenHands repo bootstrap files live under `.openhands/`:- - `.openhands/setup.sh` installs frontend dependencies with `npm ci` when needed, creates `.env` from `.env.sample` if missing, appends `VITE_WORKING_DIR` for this repo when unset, and generates `src/i18n/declaration.ts` via `npm run make-i18n`.+ - `.openhands/setup.sh` installs `uv` (via `curl -LsSf https://astral.sh/uv/install.sh | sh`) if not present, installs frontend dependencies with `npm ci` when needed, creates `.env` from `.env.sample` if missing, appends `VITE_WORKING_DIR` for this repo when unset, and generates `src/i18n/declaration.ts` via `npm run make-i18n`.- `.openhands/pre-commit.sh` mirrors the repo's local quality gate with `npm run lint && npm run test`.- GitHub PR-review automation should stay aligned with the current OpenHands repo conventions: keep the review workflow at `.github/workflows/pr-review-by-openhands.yml`, keep the companion `.github/workflows/pr-review-evaluation.yml`, auto-run on newly opened non-draft PRs and `ready_for_review` events from established contributors, still support the `review-this` label / `openhands-agent` / `all-hands-bot` reviewer triggers, use the OpenHands app LLM proxy defaults, and use the dual-trigger pattern (`pull_request` for same-repo PRs, `pull_request_target` for forks) so workflow changes can self-verify without widening fork secret exposure.- The repo now includes `.agents/skills/custom-codereview-guide.md`, adapted from `OpenHands/software-agent-sdk`, to force PR reviews to always leave either an APPROVE or COMMENT review instead of silently finishing with no review object.diff --git a/DEVELOPMENT.md b/DEVELOPMENT.mdindex ab23ea39e7..1d9eb4cc7d 100644--- a/DEVELOPMENT.md+++ b/DEVELOPMENT.md@@ -12,9 +12,22 @@ npm run devThis is an alias for `npm run dev:safe`.-It starts a dedicated local `agent-server` 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.+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.-Useful overrides:+### Agent server version selection++By default, the latest released version from PyPI is used. You can override this:++```sh+# Use a specific PyPI version+OH_AGENT_SERVER_VERSION=1.18.0 npm run dev++# Use a git branch or commit (takes precedence over version)+OH_AGENT_SERVER_GIT_REF=main npm run dev+OH_AGENT_SERVER_GIT_REF=abc1234 npm run dev+```++### Other useful overrides- `OH_GUI_SAFE_BACKEND_PORT` β backend port for the isolated server (default `18000`)- `OH_GUI_SAFE_VSCODE_PORT` β VS Code sidecar port (default `backend port + 1`)diff --git a/README.md b/README.mdindex 991be4135b..c83835f342 100644--- a/README.md+++ b/README.md@@ -11,7 +11,7 @@ This repository is a near-direct port of the OpenHands frontend adapted to talk- Node.js 22.12.x or later- `npm`-- OpenHands Agent Server (`agent-server`) installed and available on your `PATH`+- `uv` (for running the agent server via `uvx`)### 1. Clone and install the frontend@@ -21,9 +21,9 @@ cd agent-server-guinpm install```-### 2. Install OpenHands Agent Server+### 2. Install uv-If you do not already have the backend installed, install `uv` first (OpenHands SDK recommends `uv` 0.8.13+):+If you do not already have `uv` installed, install it first (OpenHands SDK recommends `uv` 0.8.13+):```shcurl -LsSf https://astral.sh/uv/install.sh | sh@@ -31,23 +31,14 @@ curl -LsSf https://astral.sh/uv/install.sh | shNeed Windows or another install method? See the official uv installation guide: <https://docs.astral.sh/uv/getting-started/installation/>-Then install or upgrade the agent server package together with the tool/workspace dependencies it needs:--```sh-uv tool install -U \- --with openhands-tools \- --with openhands-workspace \- openhands-agent-server-```--`uv tool install` exposes the server as the `agent-server` CLI. If `~/.local/bin` is not already on your `PATH`, add it before continuing:+If `~/.local/bin` is not already on your `PATH`, add it:```shexport PATH="$HOME/.local/bin:$PATH"-command -v agent-server+command -v uvx```-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>+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` filediff --git a/__tests__/scripts/dev-safe.test.ts b/__tests__/scripts/dev-safe.test.tsindex 08d6551fb0..e9f2911f52 100644--- a/__tests__/scripts/dev-safe.test.ts+++ b/__tests__/scripts/dev-safe.test.ts@@ -9,7 +9,8 @@ import { describe, expect, it } from "vitest";import {buildSafeDevConfig,buildNpmScriptCommand,- formatMissingAgentServerGuidance,+ buildAgentServerCommand,+ formatMissingUvxGuidance,} from "../../scripts/dev-safe.mjs";const repoRoot = path.resolve(@@ -17,16 +18,15 @@ const repoRoot = path.resolve("../..",);-describe("formatMissingAgentServerGuidance", () => {+describe("formatMissingUvxGuidance", () => {it("includes install, PATH, README, and fallback workflow hints", () => {- const guidance = formatMissingAgentServerGuidance(+ const guidance = formatMissingUvxGuidance("/workspace/project/agent-server-gui",);- expect(guidance).toContain(- "uv tool install -U --with openhands-tools --with openhands-workspace openhands-agent-server",- );+ expect(guidance).toContain("curl -LsSf https://astral.sh/uv/install.sh | sh");expect(guidance).toContain('export PATH="$HOME/.local/bin:$PATH"');+ expect(guidance).toContain("command -v uvx");expect(guidance).toContain(path.join("/workspace/project/agent-server-gui", "README.md"),);@@ -38,6 +38,78 @@ describe("formatMissingAgentServerGuidance", () => {});});+describe("buildAgentServerCommand", () => {+ it("uses latest release by default", () => {+ const cmd = buildAgentServerCommand({});++ expect(cmd.command).toBe("uvx");+ expect(cmd.args).toEqual([+ "--with",+ "openhands-tools",+ "--with",+ "openhands-workspace",+ "openhands-agent-server",+ ]);+ });++ it("uses specific PyPI version when OH_AGENT_SERVER_VERSION is set", () => {+ const cmd = buildAgentServerCommand({ OH_AGENT_SERVER_VERSION: "1.18.0" });++ expect(cmd.command).toBe("uvx");+ expect(cmd.args).toEqual([+ "--with",+ "openhands-tools",+ "--with",+ "openhands-workspace",+ "openhands-agent-server==1.18.0",+ ]);+ });++ it("uses git ref with subdirectory syntax for monorepo", () => {+ const cmd = buildAgentServerCommand({ OH_AGENT_SERVER_GIT_REF: "main" });++ expect(cmd.command).toBe("uvx");+ expect(cmd.args).toEqual([+ "--from",+ "git+https://github.com/OpenHands/software-agent-sdk@main#subdirectory=openhands-agent-server",+ "--with",+ "git+https://github.com/OpenHands/software-agent-sdk@main#subdirectory=openhands-tools",+ "--with",+ "git+https://github.com/OpenHands/software-agent-sdk@main#subdirectory=openhands-workspace",+ "agent-server",+ ]);+ });++ it("uses git ref for commit SHA", () => {+ const cmd = buildAgentServerCommand({ OH_AGENT_SERVER_GIT_REF: "abc1234" });++ expect(cmd.command).toBe("uvx");+ expect(cmd.args).toEqual([+ "--from",+ "git+https://github.com/OpenHands/software-agent-sdk@abc1234#subdirectory=openhands-agent-server",+ "--with",+ "git+https://github.com/OpenHands/software-agent-sdk@abc1234#subdirectory=openhands-tools",+ "--with",+ "git+https://github.com/OpenHands/software-agent-sdk@abc1234#subdirectory=openhands-workspace",+ "agent-server",+ ]);+ });++ it("git ref takes precedence over version", () => {+ const cmd = buildAgentServerCommand({+ OH_AGENT_SERVER_VERSION: "1.18.0",+ OH_AGENT_SERVER_GIT_REF: "feature-branch",+ });++ expect(cmd.command).toBe("uvx");+ expect(cmd.args).toContain("--from");+ expect(cmd.args).toContain(+ "git+https://github.com/OpenHands/software-agent-sdk@feature-branch#subdirectory=openhands-agent-server",+ );+ expect(cmd.args).not.toContain("openhands-agent-server==1.18.0");+ });+});+describe("buildSafeDevConfig", () => {it("builds isolated default paths and ports", () => {const cwd = "/workspace/project/agent-server-gui";@@ -136,12 +208,14 @@ describe("buildNpmScriptCommand", () => {});describe("dev-safe CLI startup", () => {- it("exits promptly when agent-server is missing", async () => {+ it("exits promptly when uvx is missing", async () => {+ // Skip this test if uvx is globally installed via /usr/local/bin symlink+ // that may still be accessible even with a stripped PATHconst child = spawn(process.execPath, ["scripts/dev-safe.mjs"], {cwd: repoRoot,env: {- ...process.env,- PATH: "/usr/bin:/bin",+ // Use empty PATH to ensure uvx is not found+ PATH: "",},stdio: ["ignore", "pipe", "pipe"],});@@ -169,15 +243,13 @@ describe("dev-safe CLI startup", () => {expect(exitResult.timedOut).toBe(false);expect(exitResult.code).toBe(1);- expect(output).toContain("Failed to start agent-server");- expect(output).toContain(- "uv tool install -U --with openhands-tools --with openhands-workspace openhands-agent-server",- );+ expect(output).toContain("Failed to start uvx");+ expect(output).toContain("curl -LsSf https://astral.sh/uv/install.sh | sh");expect(output).toContain("https://docs.astral.sh/uv/getting-started/installation/",);expect(output).toContain("README.md");expect(output).toContain("npm run dev:mock");- expect(output).toContain("spawn agent-server ENOENT");+ expect(output).toContain("spawn uvx ENOENT");});});diff --git a/scripts/dev-safe.mjs b/scripts/dev-safe.mjsindex d7910a84e7..f86f6f6ac7 100644--- a/scripts/dev-safe.mjs+++ b/scripts/dev-safe.mjs@@ -8,6 +8,8 @@ import { pathToFileURL } from "node:url";const DEFAULT_BACKEND_PORT = 18000;const DEFAULT_WAIT_TIMEOUT_MS = 30_000;+const DEFAULT_AGENT_SERVER_PACKAGE = "openhands-agent-server";+const AGENT_SERVER_GIT_REPO = "https://github.com/OpenHands/software-agent-sdk";function isEnoentError(error) {return Boolean(@@ -19,22 +21,21 @@ function isEnoentError(error) {);}-export function formatMissingAgentServerGuidance(cwd = process.cwd()) {+export function formatMissingUvxGuidance(cwd = process.cwd()) {const readmePath = path.join(cwd, "README.md");return [- "Failed to start agent-server. Make sure it is installed and on your PATH.",+ "Failed to start uvx. Make sure uv is installed and on your PATH.","","To fix this:",- "1. Install the backend CLI:",- " uv tool install -U --with openhands-tools --with openhands-workspace openhands-agent-server",- "2. Make sure the uv tool bin dir is on your PATH:",+ "1. Install uv:",+ " curl -LsSf https://astral.sh/uv/install.sh | sh",+ "2. Make sure the uv bin dir is on your PATH:",' export PATH="$HOME/.local/bin:$PATH"',- " command -v agent-server",+ " command -v uvx","","Need Windows or another install method? https://docs.astral.sh/uv/getting-started/installation/",`See the local Quickstart for details: ${readmePath}`,- "- README > Quickstart > 2. Install OpenHands Agent Server","","Other options:","- npm run dev:frontend # use an already running backend",@@ -42,6 +43,62 @@ export function formatMissingAgentServerGuidance(cwd = process.cwd()) {].join("\n");}+/**+ * Build the uvx command and arguments for running agent-server.+ *+ * Environment variables:+ * - OH_AGENT_SERVER_VERSION: Specific PyPI version (e.g., "1.18.0")+ * - OH_AGENT_SERVER_GIT_REF: Git commit SHA or branch name (takes precedence over version)+ *+ * @param {Record<string, string | undefined>} env+ * @returns {{ command: string, args: string[] }}+ */+export function buildAgentServerCommand(env = process.env) {+ const gitRef = env.OH_AGENT_SERVER_GIT_REF;+ const version = env.OH_AGENT_SERVER_VERSION;++ const uvxArgs = [];++ if (gitRef) {+ // Use git ref with subdirectory syntax for uv workspace monorepo+ // The software-agent-sdk repo has packages in subdirectories:+ // openhands-agent-server/, openhands-tools/, openhands-workspace/+ const baseGitUrl = `git+${AGENT_SERVER_GIT_REPO}@${gitRef}`;+ uvxArgs.push(+ "--from",+ `${baseGitUrl}#subdirectory=openhands-agent-server`,+ "--with",+ `${baseGitUrl}#subdirectory=openhands-tools`,+ "--with",+ `${baseGitUrl}#subdirectory=openhands-workspace`,+ "agent-server",+ );+ } else if (version) {+ // Use specific PyPI version: uvx --with ... openhands-agent-server==version+ uvxArgs.push(+ "--with",+ "openhands-tools",+ "--with",+ "openhands-workspace",+ `${DEFAULT_AGENT_SERVER_PACKAGE}==${version}`,+ );+ } else {+ // Use latest released version: uvx --with ... openhands-agent-server+ uvxArgs.push(+ "--with",+ "openhands-tools",+ "--with",+ "openhands-workspace",+ DEFAULT_AGENT_SERVER_PACKAGE,+ );+ }++ return {+ command: "uvx",+ args: uvxArgs,+ };+}+function parsePort(value, fallback) {if (value == null || value === "") {return fallback;@@ -133,8 +190,8 @@ function spawnProcess(command, args, options) {const child = spawn(command, args, { stdio: "inherit", ...options });child.once("error", (error) => {- if (isEnoentError(error) && command === "agent-server") {- console.error(formatMissingAgentServerGuidance(options?.cwd));+ if (isEnoentError(error) && command === "uvx") {+ console.error(formatMissingUvxGuidance(options?.cwd));} else if (isEnoentError(error)) {console.error(`Failed to start ${command}. Make sure it is installed and on your PATH.`,@@ -160,7 +217,15 @@ async function main() {mkdirSync(dir, { recursive: true });}+ const agentServerCmd = buildAgentServerCommand();+ const agentServerSource = process.env.OH_AGENT_SERVER_GIT_REF+ ? `git ref: ${process.env.OH_AGENT_SERVER_GIT_REF}`+ : process.env.OH_AGENT_SERVER_VERSION+ ? `version: ${process.env.OH_AGENT_SERVER_VERSION}`+ : "latest release";+console.log("Starting isolated agent-server + frontend dev stack...");+ console.log(`- agent-server: ${agentServerSource}`);console.log(`- backend: ${config.backendBaseUrl}`);console.log(`- vscode port: ${config.vscodePort}`);console.log(`- working dir: ${config.workingDir}`);@@ -168,8 +233,14 @@ async function main() {console.log("");const backend = spawnProcess(- "agent-server",- ["--host", "127.0.0.1", "--port", String(config.backendPort)],+ agentServerCmd.command,+ [+ ...agentServerCmd.args,+ "--host",+ "127.0.0.1",+ "--port",+ String(config.backendPort),+ ],{cwd: config.cwd,env: {