Skip to content

πŸ™Œ OpenHands: AI-Driven Development

fix(launcher): pin uvx to Python 3.12-3.14 until deps ship 3.15 wheels (#18731)

Vasco Schiavo4b147dcff291
diff --git a/.agents/skills/local-stack-runtime/references/guide.md b/.agents/skills/local-stack-runtime/references/guide.md
index c1e813fffc..38b3b687b5 100644
--- a/.agents/skills/local-stack-runtime/references/guide.md
+++ b/.agents/skills/local-stack-runtime/references/guide.md
@@ -93,6 +93,7 @@ you are running inside of β€” NOT the automation backend.
- `OH_AGENT_SERVER_LOCAL_PATH` β€” absolute path to a local `software-agent-sdk` checkout. Runs the local checkout via `uvx` with `--with-editable` for `openhands-sdk`/`openhands-tools`/`openhands-workspace` and `--reinstall` for `openhands-agent-server`, so SDK edits are picked up on restart. Highest precedence.
- `OH_AGENT_SERVER_GIT_REF` β€” git commit SHA or branch name (takes precedence over version)
- `OH_AGENT_SERVER_VERSION` β€” specific PyPI version (e.g., "1.56.0")
+ - `UV_PYTHON` β€” Python version or range uvx may use for agent-server and automation. Defaults to `python.uvxRequest` in `config/defaults.json` (`>=3.12,<3.15`), so a machine with no supported Python downloads the newest 3.14 instead of the newest CPython, whose wheels the SDK's compiled dependencies lag behind (#18654).
- `OH_SECRET_KEY` β€” secret key for settings encryption; auto-generated and persisted to `~/.openhands/agent-canvas/secret-key.txt` on first run (same file Docker uses), ensuring dev mode and Docker share the same key when both mount the same `~/.openhands` directory. Override with the env var to pin a specific key.
- `SESSION_API_KEY` / `OH_SESSION_API_KEYS_0` / `VITE_SESSION_API_KEY` β€” session API key for agent-server authentication; auto-generated using `crypto.randomBytes(32)` if not set, passed to both agent-server (`OH_SESSION_API_KEYS_0`) and frontend (`VITE_SESSION_API_KEY`)
- Default: released PyPI version `1.56.0` for agent-server SDK libraries
diff --git a/.pr/uvx-python-pin-after-canvas.png b/.pr/uvx-python-pin-after-canvas.png
new file mode 100644
index 0000000000..74cb675b1c
Binary files /dev/null and b/.pr/uvx-python-pin-after-canvas.png differ
diff --git a/.pr/uvx-python-pin-before-after.png b/.pr/uvx-python-pin-before-after.png
new file mode 100644
index 0000000000..2dd779bfe5
Binary files /dev/null and b/.pr/uvx-python-pin-before-after.png differ
diff --git a/__tests__/scripts/dev-safe.test.ts b/__tests__/scripts/dev-safe.test.ts
index b351fce91e..a3e3fdf823 100644
--- a/__tests__/scripts/dev-safe.test.ts
+++ b/__tests__/scripts/dev-safe.test.ts
@@ -23,6 +23,7 @@ import {
buildAgentServerEnv,
buildAgentServerTelemetryEnv,
buildRuntimeServicesInfo,
+ buildUvxPythonArgs,
formatMissingUvxGuidance,
formatMissingFrontendDependenciesGuidance,
getMissingFrontendDependencyBins,
@@ -540,6 +541,8 @@ describe("buildAgentServerCommand", () => {
expect(cmd.command).toBe("uvx");
// Defaults to the released PyPI version with all SDK packages pinned to same version
expect(cmd.args).toEqual([
+ "--python",
+ ">=3.12,<3.15",
"--from",
"openhands-agent-server==1.56.0",
"--with",
@@ -564,6 +567,8 @@ describe("buildAgentServerCommand", () => {
// Uses --from syntax because executable name (agent-server) differs from package name (openhands-agent-server)
// All SDK packages are pinned to the same version
expect(cmd.args).toEqual([
+ "--python",
+ ">=3.12,<3.15",
"--from",
"openhands-agent-server==1.18.0",
"--with",
@@ -588,6 +593,8 @@ describe("buildAgentServerCommand", () => {
expect(cmd.command).toBe("uvx");
expect(cmd.args).toEqual([
+ "--python",
+ ">=3.12,<3.15",
"--reinstall",
"--from",
"git+https://github.com/OpenHands/software-agent-sdk@feature-branch#subdirectory=openhands-agent-server",
@@ -611,6 +618,8 @@ describe("buildAgentServerCommand", () => {
expect(cmd.command).toBe("uvx");
expect(cmd.args).toEqual([
+ "--python",
+ ">=3.12,<3.15",
"--reinstall",
"--from",
"git+https://github.com/OpenHands/software-agent-sdk@abc1234#subdirectory=openhands-agent-server",
@@ -649,6 +658,8 @@ describe("buildAgentServerCommand", () => {
expect(cmd.command).toBe("uvx");
expect(cmd.args).toEqual([
+ "--python",
+ ">=3.12,<3.15",
"--reinstall",
"--from",
path.join(sdk, "openhands-agent-server"),
@@ -713,6 +724,37 @@ describe("buildAgentServerCommand", () => {
});
});
+describe("buildUvxPythonArgs", () => {
+ const defaults = JSON.parse(
+ readFileSync(
+ path.resolve(
+ path.dirname(fileURLToPath(import.meta.url)),
+ "../../config/defaults.json",
+ ),
+ "utf-8",
+ ),
+ ) as { python: { uvxRequest: string } };
+
+ it("requests the Python range from config/defaults.json by default", () => {
+ // Without it uvx downloads the newest CPython on a machine that has none,
+ // which fails until the SDK's compiled dependencies ship wheels for it
+ // (#18654).
+ expect(defaults.python.uvxRequest).toBe(">=3.12,<3.15");
+ expect(buildUvxPythonArgs({})).toEqual([
+ "--python",
+ defaults.python.uvxRequest,
+ ]);
+ });
+
+ it("leaves the interpreter choice to uv when UV_PYTHON is set", () => {
+ // An explicit --python would outrank uv's own variable.
+ expect(buildUvxPythonArgs({ UV_PYTHON: "3.13" })).toEqual([]);
+ const { args } = buildAgentServerCommand({ UV_PYTHON: "3.13" });
+ expect(args).not.toContain("--python");
+ expect(args[0]).toBe("--from");
+ });
+});
+
describe("validateLocalAgentServerPath", () => {
it("passes when all four workspace packages exist", () => {
const tmp = mkdtempSync(path.join(tmpdir(), "sdk-"));
diff --git a/__tests__/scripts/dev-with-automation.test.ts b/__tests__/scripts/dev-with-automation.test.ts
index 2262db0300..7d96573ab9 100644
--- a/__tests__/scripts/dev-with-automation.test.ts
+++ b/__tests__/scripts/dev-with-automation.test.ts
@@ -109,6 +109,25 @@ describe("buildAutomationCommand", () => {
expect(cmd.source).toBe(`PyPI (${DEFAULT_AUTOMATION_VERSION}, default)`);
});
+ it("requests the shared Python range for uvx in every source mode", () => {
+ // See buildUvxPythonArgs in dev-safe.mjs and #18654.
+ const variants = [
+ {},
+ { OH_AUTOMATION_VERSION: "1.0.0" },
+ { OH_AUTOMATION_GIT_REF: "main" },
+ ];
+ for (const env of variants) {
+ const { command, args } = buildAutomationCommand(env);
+ expect(command).toBe("uvx");
+ expect(args.slice(0, 2)).toEqual(["--python", ">=3.12,<3.15"]);
+ }
+ });
+
+ it("leaves the interpreter choice to uv when UV_PYTHON is set", () => {
+ const { args } = buildAutomationCommand({ UV_PYTHON: "3.13" });
+ expect(args).not.toContain("--python");
+ });
+
it("uses custom git ref from OH_AUTOMATION_GIT_REF", () => {
const cmd = buildAutomationCommand({
OH_AUTOMATION_GIT_REF: "feat/my-feature",
diff --git a/bin/agent-canvas.mjs b/bin/agent-canvas.mjs
index f399534872..2f96f7fc0a 100755
--- a/bin/agent-canvas.mjs
+++ b/bin/agent-canvas.mjs
@@ -94,6 +94,7 @@ ENVIRONMENT VARIABLES:
OH_AGENT_SERVER_GIT_REF Git ref for agent-server
OH_AGENT_SERVER_LOCAL_PATH Path to local SDK checkout (for development)
OH_AGENT_SERVER_VERSION Specific PyPI version for agent-server
+ UV_PYTHON Python version/range for uvx-run services
Note: LLM settings are configured through the web UI settings page,
not environment variables.
diff --git a/config/defaults.json b/config/defaults.json
index 86bab4889d..f58ce19a4e 100644
--- a/config/defaults.json
+++ b/config/defaults.json
@@ -8,6 +8,10 @@
"compatibility": {
"minimumAgentServer": "1.55.0"
},
+ "python": {
+ "_comment": "Interpreter request the npm and desktop launchers pass to uvx as --python for agent-server and automation. Without it uvx downloads the newest CPython when it finds no suitable interpreter, which breaks every autumn until the SDK's compiled dependencies (lmnr-claude-code-proxy, fastuuid) publish wheels for the new release (OpenHands/OpenHands#18654). Raise the upper bound once they do. UV_PYTHON in the environment replaces it.",
+ "uvxRequest": ">=3.12,<3.15"
+ },
"images": {
"agentServer": "ghcr.io/openhands/agent-server",
"agentCanvas": "ghcr.io/openhands/agent-canvas"
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
index 1d8b8065a4..f8e31146ec 100644
--- a/docs/DEVELOPMENT.md
+++ b/docs/DEVELOPMENT.md
@@ -77,6 +77,7 @@ directory before starting the Agent Server and preserve an explicit override.
| `OH_AUTOMATION_LOCAL_PATH` | Absolute `automation` checkout | unset |
| `OH_AUTOMATION_GIT_REF` | Git ref for automation backend | unset (`config/defaults.json`) |
| `OH_AUTOMATION_VERSION` | PyPI version for automation | unset (`config/defaults.json`) |
+| `UV_PYTHON` | Python version/range for uvx services | unset (`config/defaults.json`) |
### Alternative: Minimal Mode (without Automation)
diff --git a/scripts/dev-safe.mjs b/scripts/dev-safe.mjs
index da14006a4a..3438155981 100644
--- a/scripts/dev-safe.mjs
+++ b/scripts/dev-safe.mjs
@@ -60,6 +60,9 @@ const DEFAULT_AGENT_SERVER_TELEMETRY_POSTHOG_API_KEY =
const DEFAULT_AGENT_SERVER_TELEMETRY_POSTHOG_HOST =
SHARED_DEFAULTS.telemetry.posthogHost;
const AGENT_SERVER_POSTHOG_CONSTRAINT = "posthog>=6,<7";
+// Interpreter request passed to uvx for agent-server and automation; see
+// buildUvxPythonArgs.
+const DEFAULT_UVX_PYTHON_REQUEST = SHARED_DEFAULTS.python.uvxRequest;
const FRONTEND_REQUIRED_BINS = ["cross-env", "react-router"];
/**
@@ -408,6 +411,27 @@ export function validateFrontendDependencies(
*/
export const AGENT_SERVER_IMPORT_MODULES = "canvas_ui_tool";
+/**
+ * Build the `--python` arguments for a uvx-launched service.
+ *
+ * When no suitable interpreter is installed, uvx downloads the newest
+ * CPython it knows, and the SDK's compiled dependencies lag each new
+ * Python release by weeks. A fresh machine therefore failed to start as
+ * soon as Python 3.15 shipped (#18654). Requesting a range makes uvx reuse
+ * any installed interpreter inside it and otherwise download the newest
+ * matching one. An explicit `--python` would outrank uv's own UV_PYTHON
+ * variable, so it is omitted when UV_PYTHON is set.
+ *
+ * @param {Record<string, string | undefined>} env
+ * @returns {string[]}
+ */
+export function buildUvxPythonArgs(env = process.env) {
+ if (env.UV_PYTHON) {
+ return [];
+ }
+ return ["--python", DEFAULT_UVX_PYTHON_REQUEST];
+}
+
/**
* Build the uvx command and arguments for running agent-server.
*
@@ -424,6 +448,9 @@ export const AGENT_SERVER_IMPORT_MODULES = "canvas_ui_tool";
* DEFAULT_AGENT_SERVER_VERSION. Set OH_AGENT_SERVER_GIT_REF to use a
* git branch or commit instead.
*
+ * UV_PYTHON, when set, replaces the default interpreter request (the
+ * python.uvxRequest range in config/defaults.json) given to uvx.
+ *
* @param {Record<string, string | undefined>} env
* @returns {{ command: string, args: string[], source: string }}
*/
@@ -432,7 +459,7 @@ export function buildAgentServerCommand(env = process.env) {
const gitRef = env.OH_AGENT_SERVER_GIT_REF;
const version = env.OH_AGENT_SERVER_VERSION;
- const uvxArgs = [];
+ const uvxArgs = buildUvxPythonArgs(env);
let source = "";
if (localPath) {
diff --git a/scripts/dev-with-automation.mjs b/scripts/dev-with-automation.mjs
index 30d804aa8c..d0ff0fab7e 100644
--- a/scripts/dev-with-automation.mjs
+++ b/scripts/dev-with-automation.mjs
@@ -59,6 +59,7 @@ import {
buildAgentServerEnv,
buildNpmScriptCommand,
buildRuntimeServicesInfo,
+ buildUvxPythonArgs,
formatMissingUvxGuidance,
validateFrontendDependencies,
validateLocalAgentServerPath,
@@ -320,6 +321,9 @@ function validateLocalAutomationPath(localPath) {
* If none are set, defaults to the released version specified by
* DEFAULT_AUTOMATION_VERSION. Set OH_AUTOMATION_GIT_REF to use a
* git branch or commit instead.
+ *
+ * UV_PYTHON, when set, replaces the default interpreter request (the
+ * python.uvxRequest range in config/defaults.json) given to uvx.
*/
function buildAutomationCommand(env = process.env) {
const localPath = env.OH_AUTOMATION_LOCAL_PATH;
@@ -327,7 +331,7 @@ function buildAutomationCommand(env = process.env) {
const version = env.OH_AUTOMATION_VERSION;
const repoUrl = env.OH_AUTOMATION_REPO || DEFAULT_AUTOMATION_REPO;
- const uvxArgs = [];
+ const uvxArgs = buildUvxPythonArgs(env);
let source = "";
if (localPath) {