Skip to content

πŸ™Œ 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.sample
index 4ef207574a..cbb6fd4b0c 100644
--- a/.env.sample
+++ b/.env.sample
@@ -19,7 +19,11 @@ VITE_INSECURE_SKIP_VERIFY="false" # Skip TLS certificate verification for proxie
VITE_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.sh
index 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 ]; then
npm ci
fi
diff --git a/AGENTS.md b/AGENTS.md
index 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.md
index ab23ea39e7..1d9eb4cc7d 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -12,9 +12,22 @@ npm run dev
This 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.md
index 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-gui
npm 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+):
```sh
curl -LsSf https://astral.sh/uv/install.sh | sh
@@ -31,23 +31,14 @@ 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/>
-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:
```sh
export 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` file
diff --git a/__tests__/scripts/dev-safe.test.ts b/__tests__/scripts/dev-safe.test.ts
index 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 PATH
const 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.mjs
index 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: {